Confluence MCP 服务器

这是一个用于访问 Confluence API 的 Model Context Protocol 服务器系统。它使用个人访问令牌与 Confluence 进行通信，作为在 VPN 区域内访问 Confluence API 的中介服务器。

系统架构

该项目由两台服务器组成：

1. MCP 服务器 (server.ts)：这是主要的服务器，负责与 Confluence API 通信并处理数据。

   • 默认端口: 3000
   • 提供 RESTful API
   • 处理 MCP 协议

2. 代理服务器 (proxyServer.ts)：它充当 MCP 客户端和 MCP 服务器之间的代理。

   • 默认端口: 3001
   • 接收来自 MCP 客户端的请求，并将其转发给主服务器

这种结构是为了解决 VPN 区域问题而设计的。MCP 服务器运行于 VPN 内部，能够访问 Confluence API，而代理服务器则运行在一个可以从外部访问的环境中。

功能

• 查询所有 Confluence 空间列表
• 查询特定空间内的所有页面
• 通过页面 ID 查询特定页面信息
• 创建新页面
• 更新现有页面

安装与配置

必要条件

• Node.js 16.x 或更高版本
• Bun 1.0.0 或更高版本

安装

# 저장소 클론
git clone https://github.com/yourusername/confluence-mcp-server.git
cd confluence-mcp-server

# 의존성 설치
bun install

环境变量设置

在项目根目录下创建一个 .env 文件，并添加以下内容：

PORT=3000
PROXY_PORT=3001
MCP_SERVER_URL=http://localhost:3000
CONFLUENCE_BASE_URL=https://wiki.musinsa.com
PERSONAL_ACCESS_TOKEN=your_personal_access_token
NODE_ENV=development

运行

开发环境

# MCP 서버 실행 (Confluence API와 통신)
bun run dev

# 프록시 서버 실행 (MCP 클라이언트와 통신)
bun run dev:proxy

# MCP 서버 Stdio 모드 실행 (선택 사항)
bun run dev:stdio

生产环境

# 빌드
bun run build

# MCP 서버 실행
bun run serve

# 프록시 서버 실행
bun run serve:proxy

端点

MCP 服务器端点（默认端口：3000）

• POST /mcp - 处理 MCP 请求的主要端点
• GET /mcp/tools - 查询可用工具列表
• GET /api/spaces - 查询所有空间列表
• GET /api/spaces/:spaceKey/pages - 查询特定空间的页面列表
• GET /api/pages/:pageId - 查询特定页面信息
• POST /api/pages - 创建新页面
• PUT /api/pages/:pageId - 更新页面
• GET /health - 检查服务器状态

代理服务器端点（默认端口：3001）

• POST /mcp - 接收来自 MCP 客户端的请求并转发给 MCP 服务器
• GET /tools - 查询可用工具列表
• GET /health - 检查代理服务器状态

故障排除

解决VPN区域问题

此项目通过将两个服务器分开来解决 VPN 区域问题：

1. MCP 服务器 在 VPN 内部运行，直接访问 Confluence API。
2. 代理服务器 在可以从外部访问的环境中运行，接收来自 MCP 客户端的请求。

当 MCP 客户端无法直接访问 Confluence API 时，这种配置起到了中介作用。

"Error fetching spaces: Unable to connect" 错误

此错误可能由于以下原因导致：

1. HTTPS 证书问题：开发环境中禁用了 SSL 证书验证，但在生产环境中需要正确配置证书。
2. 网络连接问题：防火墙或代理设置可能导致无法访问 Confluence 服务器。
3. Personal Access Token 问题：令牌可能已过期或格式不正确。

解决方法

1. 确认 .env 文件中的 CONFLUENCE_BASE_URL 是否正确。
2. 确认 Personal Access Token 是否有效。
3. 检查防火墙设置以确保可以访问 Confluence 服务器。
4. 联系网络管理员确认访问权限。
5. 确认 MCP 服务器和代理服务器之间的连接是否正确设置 (MCP_SERVER_URL 设置)。

测试

# 모든 테스트 실행
bun test

# 특정 테스트 실행
bun test src/test/getSpaces.test.ts

部署配置

推荐部署配置

对于生产环境，推荐以下部署配置：

1. MCP 服务器：部署在内部网络中，该网络可以访问 Confluence 服务器。
2. 代理服务器：部署在网络中，MCP 客户端可以访问。

安全考虑

• 建议使用 HTTPS 加密代理服务器和 MCP 服务器之间的通信。
• 安全管理 Personal Access Token，并根据需要定期更新。
• 在生产环境中，请添加适当的认证机制以防止对代理服务器的未授权访问。

许可证

MIT