Confluence MCP Server

Confluence MCP 服务

这是一个用于访问 Confluence API 的模型上下文协议服务器系统。它使用个人访问令牌与 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. 个人访问令牌问题：令牌可能已过期或格式不正确。

解决方法

1. 确认 .env 文件中的 CONFLUENCE_BASE_URL 正确无误。
2. 确认个人访问令牌有效。
3. 检查防火墙设置，确认可以访问 Confluence 服务器。
4. 联系网络管理员，确认访问权限。
5. 确认 MCP 服务与代理服务器之间的连接配置正确（MCP_SERVER_URL 设置）。

测试

# 모든 테스트 실행
bun test

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

部署配置

推荐的部署配置

建议在生产环境中采用以下部署配置：

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

安全注意事项

• 建议使用 HTTPS 加密代理服务器与 MCP 服务之间的通信。
• 妥善保管个人访问令牌，并根据需要定期更新。
• 在生产环境中添加适当的身份验证机制，防止未经授权访问代理服务器。

许可证

MIT