Korea Okey MCP

维基mcp

管理Confluence维基页面的模型上下文协议（MCP）服务器。

Streamable HTTP Transport支持 -使用MCP标准HTTP通信方式。

🚀 功能

• 浏览页面（wiki_get_page)
• 生成页面（wiki_create_page)
• 修改页面（wiki_update_page)
• 删除页面（wiki_delete_page)
• 搜索页面（wiki_search)
• 浏览空间列表（wiki_get_spaces)

📋 要求

• Python 3.10+
• Docker（使用容器时）
• Confluence Server/Data Center或Confluence Cloud

🔧 设置环境变量

Confluence连接设置

方法1:断开IP和端口（建议） 🌟

方法2:输入完整URL

💡 优先级: CONFLUENCE_URL > CONFLUENCE_HOST + CONFLUENCE_PORT

认证设置

认证方式：

• 服务器/DC: CONFLUENCE_PERSONAL_TOKEN 必需
• 云： CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN 必需

MCP服务器设置

💡 通信方式：

• streamable：HTTP Streamable Transport（推荐）-标准MCP HTTP通信
• stdio：标准I/O方式

💡 MCP_HOST设置：

• 0.0.0.0：允许所有网络接口连接（建议）
• 127.0.0.1：仅允许localhost连接
• 192.168.1.200：仅从特定IP进行监听（增强安全性）

🐳 使用Docker

1映像构建

cd mcp-wiki
docker build -t wiki-mcp:latest .

运行2⃣容器

本地测试（localhost:8090）

docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_HOST="host.docker.internal" \
  -e CONFLUENCE_PORT="8090" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  wiki-mcp:latest

💡 Docker 桌面版在中 host.docker.internal通过访问主机。

输入IP和端口分离（建议） 🌟

docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_HOST="192.168.1.100" \
  -e CONFLUENCE_PORT="8090" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  wiki-mcp:latest

输入完整URL

docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_URL="http://192.168.1.100:8090" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  wiki-mcp:latest

使用HTTPS

docker run -d \
  --name wiki-mcp-server \
  -p 8002:8002 \
  -e CONFLUENCE_PROTOCOL="https" \
  -e CONFLUENCE_HOST="wiki.company.com" \
  -e CONFLUENCE_PORT="443" \
  -e CONFLUENCE_PERSONAL_TOKEN="your-token-here" \
  wiki-mcp:latest

使用环境文件（.env）

# .env 파일 생성
cat > .env  .env \.cursor\mcp.json`）：

{ "mcpServers": { "wiki-mcp": { "url": "http://localhost:8002/mcp/" } } }

#### **远程服务器环境（wiki-mcp在其他服务器上运行）**

{ "mcpServers": { "wiki-mcp": { "url": "http://192.168.1.200:8002/mcp/" } } }

💡 **端点信息：**

- MCP端点： `/mcp/`
- 健康检查： `/health`
- 服务器信息： `/info`

💡 `192.168.1.200`请更改为wiki-mcp服务器的实际IP地址。

### 重新启动2⃣Cursor

完全退出并重新启动Cursor时，将自动连接。

### 3使用示例

wiki-mcp로 TES 스페이스의 페이지 목록 알려줘

wiki-mcp로 페이지 ID 98371 내용 가져와줘

## 🖥️ 远程服务器部署

### **场景：在单独的服务器上运行wiki-mcp**

#### **在1⃣服务器上运行**

서버 192.168.1.200에서 실행

docker run -d \ --name wiki-mcp-server \ -p 8002:8002 \ -e MCP_HOST="0.0.0.0" \ -e MCP_PORT="8002" \ -e CONFLUENCE_HOST="192.168.1.100" \ -e CONFLUENCE_PORT="8090" \ -e CONFLUENCE_PERSONAL_TOKEN="토큰" \ wiki-mcp:latest

**环境变量说明：**

- `MCP_HOST="0.0.0.0"`：启用外部连接
- `MCP_PORT="8002"`：服务端口
- `CONFLUENCE_HOST`：Confluence服务器IP
- `CONFLUENCE_PORT`：Confluence服务器端口

#### **2防火墙设置**

Linux (firewalld)

sudo firewall-cmd --add-port=8002/tcp --permanent sudo firewall-cmd --reload

Windows

New-NetFirewallRule -DisplayName "wiki-mcp" -Direction Inbound -LocalPort 8002 -Protocol TCP -Action Allow

#### **3客户机PC连接**

`mcp.json`:

{ "mcpServers": { "wiki-mcp": { "url": "http://192.168.1.200:8002/mcp/" } } }

### **网络配置**

PC A (Cursor) │ │ HTTP Streamable (MCP Protocol) ▼ 서버 B (192.168.1.200) wiki-mcp:8002 (FastAPI + MCP SDK) │ │ REST API (requests) ▼ 서버 C (192.168.1.100) Confluence:8090

## 🔑 创建Personal Access Token

### 汇流服务器/数据中心

1. Confluence登录
1. 配置文件图标→ **设置**
1. 左侧菜单→ **个人访问令牌**
1. **创建令牌** 单击
1. 输入名称后 **创建**
1. 复制生成的令牌（无法再次查看！）

## 🛠️ 故障排除

### 1⃣“未设置Confluence URL”

방법 1: HOST와 PORT 설정

export CONFLUENCE_HOST="192.168.1.100" export CONFLUENCE_PORT="8090"

방법 2: 전체 URL 설정

export CONFLUENCE_URL="http://192.168.1.100:8090"

### 2⃣“未设置身份验证信息”

Server/DC

export CONFLUENCE_PERSONAL_TOKEN="your-token"

Cloud

export CONFLUENCE_USERNAME="user@email.com" export CONFLUENCE_API_TOKEN="your-api-token"

### 3 SSL证书错误

export CONFLUENCE_SSL_VERIFY=false

### 4集装箱无法启动

로그 확인

docker logs wiki-mcp-server

환경 변수 확인

docker exec wiki-mcp-server env | grep CONFLUENCE

## 📚 环境变量优先级

URL解析顺序：

1. **直接作为参数传递的 `url`** （最优先）
1. **环境变量 `CONFLUENCE_URL`** （完整URL）
1. **环境变量 `CONFLUENCE_HOST` + `CONFLUENCE_PORT` + `CONFLUENCE_PROTOCOL`** （组合）

## 🏗️ 技术堆栈

### 版本0.2.0（Streamable HTTP）

区分技术用途
|------|------|------|
| **MCP传输** |MCP SDK流式HTTP |流式HTTP통신 |
| **Web框架** | Starlette | HTTP服务器|
| **ASGI服务器** 运行Uvicorn|异步服务器|
| **汇流API** |requests|Confluence REST API调用（同步）|
| **异步处理** | asyncio.to_thread（）|在异步环境中运行同步代码|

### 主要更改（v0.1.0→v0.2.0）

#### 更改的部分

- **MCP传输**上海证券交易所→ **可流式传输的HTTP** （标准MCP协议）
- **库**：fastmcp→ **mcp+Starlette**
- **端点**: `/sse` → **/mcp/**
- **通信方式**：服务器发送的事件→ **HTTP流式传输**

#### 维持的部分

- **Confluence API客户端** (`api_client.py`：未更改
- **数据模型** (`models.py`：未更改
- **所有功能**：页面CRUD，搜索，空间查询相同
- **环境变量**：相同的Confluence设置
- **部署Docker**：可用的方式相同

#### 🎯 优点

- 遵循MCP标准协议
- 更好的兼容性和可扩展性
- 通过异步处理提高性能
- 提供RESTful API端点（`/health`, `/`)

## 📄 许可证

该项目可用于个人和商业用途。