MCP 知识库服务适配器 (TypeScript)

本组件是基于 MCP 规范构建的专用适配器，用于与 Atlassian Confluence 平台进行高效、结构化的交互操作。

核心功能概览

• 数据访问：支持空间（Space）元数据获取、页面内容提取（包括存储格式和渲染格式）。
• 内容生命周期管理：提供创建新页面、检索现有页面详情、以及版本化更新页面实体的能力。
• 信息检索：强大的全文内容和属性搜索接口。
• 协议标准化：所有外部 Confluence 操作均通过 MCP 结构化，确保与系统其他部分的一致性。

快速部署与集成

环境先决条件

• Node.js 运行时环境 (推荐版本 $\geq$ 14.0.0)
• TypeScript 编译器 (推荐版本 $\geq$ 4.0.0)

安装依赖

bash npm install

构建流程

执行完整的清理与编译任务：

bash npm run build:full

认证机制配置

该适配器支持两种主要的身份验证策略。请在环境变量或配置文件中明确定义以下任一组合：

1. API 令牌认证 (首选安全模式)

推荐使用短期或长期访问令牌（Access Token）：

env CONFLUENCE_ENDPOINT=https://your-corp-wiki.atlassian.net/wiki CONFLUENCE_AUTH_METHOD=token CONFLUENCE_API_TOKEN=your-secure-token-here

2. 基本认证 (用户名/密码)

适用于特定遗留场景或初始化部署：

env CONFLUENCE_ENDPOINT=https://your-corp-wiki.atlassian.net/wiki CONFLUENCE_AUTH_METHOD=basic CONFLUENCE_USER=service_account CONFLUENCE_PASS=obfuscated_password

MCP 客户端集成示例

通过 MCP 客户端调用 Confluence 服务的方法：

获取指定空间的页面列表：

typescript const spaceContents = await mcpClient.invoke('mcp-confluence-adapter-ts.getSpaceContent', { spaceKey: 'DOCS', expand: 'page.descendants' });

发布一篇新文档：

typescript const result = await mcpClient.invoke('mcp-confluence-adapter-ts.createOrUpdatePage', { targetPageId: null, // 标识为新建 spaceKey: 'PROJ', pageTitle: 'Project Q3 Summary', body: '...', // 使用 Storage Format parentPageId: '123456', versionToLock: 1 // 乐观锁版本 });

性能与运维考量

• 连接池管理：底层 HTTP 客户端默认启用连接复用（Keep-Alive）以减少握手延迟。
• 请求速率限制：内置节流机制，防止超出 Confluence API 速率限制。
• 传输效率：自动协商 GZIP/Brotli 响应压缩，减少数据传输量。

错误报告规范

当 Confluence 返回非 2xx 状态码时，适配器将抛出结构化的 MCPError，其中包含原始 HTTP 状态码、Confluence 内部错误代码（若存在）以及完整的请求上下文，便于上层系统进行故障排查。