AI导哈

Confluence搜索服务

一个基于Model Context Protocol (MCP)的服务器，提供LexisNexis内部系统的Confluence搜索功能，支持AI助手和其他MCP客户端搜索Confluence文档。

  • by mihirjoshi21
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 mihirjoshi21/confluence_mcp

使用说明

汇流MCP服务器

为LexisNexis内部系统提供Confluence搜索功能的模型上下文协议（MCP）服务器：

  1. 汇流搜索 -从LexisNexis Confluence搜索和检索内容

概述

此MCP服务器是使用 @模型上下文协议/sdk 并通过标准化的MCP协议与LexisNexis Confluence无缝集成。它使AI助手和其他MCP客户端能够搜索Confluence文档。

特性

🔍 汇流搜索工具

  • 搜索LexisNexis Confluence空间、页面、博客文章和附件
  • 从搜索结果中检索详细内容
  • 支持CQL（汇流查询语言）查询
  • 可配置的搜索结果限制
  • 承载令牌身份验证

先决条件

  • Node.js 18+
  • npm或pnpm包管理器
  • TypeScript 5.3+
  • 访问LexisNexis内部网络（用于Confluence服务）

安装

  1. 克隆存储库：

    git clone <repository-url>
cd confluence_mcp

  2. 安装依赖项：

    npm install
# or
pnpm install

  3. 构建项目：

    npm run build

配置

环境变量

创建一个 .env 项目根目录中的文件，包含以下变量：

# Confluence Configuration
CONFLUENCE_BEARER_TOKEN=your_confluence_bearer_token_here
LIMIT=5  # Optional: Number of search results to return (default: 2)

承载令牌设置

要使用Confluence搜索功能，您需要一个有效的承载令牌：

  1. 登录LexisNexis Confluence
  2. 生成API令牌
  3. 设置 CONFLUENCE_BEARER_TOKEN 环境变量

用法

启动服务器

npm start

服务器在stdio传输上运行，并将输出：

Confluence MCP Server running on stdio

工具使用

汇流搜索

工具名称： confluence-search

说明： 使用搜索字符串搜索汇流。输入必须以“汇流”开头（不区分大小写），后跟搜索字符串。

输入格式：

confluence <your search terms>

示例：

confluence API documentation
confluence deployment guide
confluence troubleshooting

答复： 返回匹配Confluence页面的完整内容，包括HTML标记。

技术架构

MCP协议实现

此服务器实现了模型上下文协议（MCP）规范：

  • 传输层： 使用stdio传输进行通信
  • 消息格式： JSON-RPC 2.0协议
  • 工具注册： 带有模式验证的动态工具注册
  • 错误处理： 带有正确HTTP状态代码的结构化错误响应

请求/响应流

  1. 客户请求： MCP客户端发送工具调用请求
  2. 验证： 使用Zod模式验证输入参数
  3. 处理： 执行特定于工具的逻辑（API调用、身份验证）
  4. 答复： 返回带内容数组的结构化响应

速率限制和性能

  • 汇流API： 内容详细信息请求之间内置1秒延迟
  • 并发请求： 安全地处理多个工具调用
  • 内存管理： 用于大型内容检索的流式响应

API终点

汇流API

  • 基本URL: https://confluence.lexisnexis.dev
  • 搜索端点： /rest/api/search
  • 内容终结点： /rest/api/content/{id}

项目结构

confluence_mcp/
├── src/
│   └── confluence.ts          # Main MCP server implementation
├── build/                     # Compiled JavaScript output
│   └── confluence.js         # Confluence search functionality
├── package.json              # Project dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── jest.config.js            # Jest testing configuration
└── manifest.xml              # Office add-in manifest (legacy)

发展

建筑

npm run build

这将编译来自以下位置的TypeScript文件 src/ 向 build/ 目录。

测试

npm test

注意：当前未实现测试（返回“错误：未指定测试”）。

编码结构

服务器使用MCP SDK来：

  1. 创建MCP服务器实例 用于Confluence搜索功能
  2. 注册工具 使用 server.tool() 方法
  3. 处理stdio传输 用于通信
  4. 实现异步工具处理程序 通过适当的错误处理

关键依赖关系

  • @modelcontextprotocol/sdk -核心MCP功能
  • node-fetch -对API的HTTP请求
  • zod -运行时类型验证和模式验证

高级配置

Confluence搜索定制

您可以通过在中修改CQL查询来自定义搜索行为 src/confluence.ts:

const cqlQuery = `siteSearch ~ "${searchString}" AND type in ("space","user","page","blogpost")`;

环境特定设置

不同的环境可能需要不同的配置：

# Development
CONFLUENCE_BEARER_TOKEN=dev_token_here
LIMIT=2

# Production  
CONFLUENCE_BEARER_TOKEN=prod_token_here
LIMIT=10

错误处理

服务器实现了全面的错误处理：

  • 网络错误： 瞬态故障的自动重试逻辑
  • 身份验证错误： 清除无效凭据的错误消息
  • 速率限制： API费率限制的优雅处理
  • 输入验证： 基于模式的验证，带有详细的错误消息

安全考虑

⚠️ 重要安全注意事项：

  1. 资格证书： 切勿将承载令牌或密码提交给版本控制
  2. 环境变量： 使用 .env 文件或安全环境变量管理
  3. 网络访问： 此服务器需要访问LexisNexis内部网络
  4. 令牌处理： 会话令牌应安全处理，不得记录

故障排除

常见问题

  1. “无效输入”错误：

    • 确保Confluence查询以“汇流”开头

  2. 身份验证失败：

    • 检查Confluence的承载令牌有效性
    • 确保与LexisNexis服务的网络连接

  3. 没有搜索结果：

    • 尝试更广泛的搜索词
    • 检查您是否可以访问Confluence空间
    • 验证LIMIT环境变量是否设置正确

  4. 速率限制错误：

    • 服务器在请求之间实现1秒延迟
    • 对于高容量使用，考虑实施指数回退
    • 监控环境中的API速率限制

  5. 响应量大的内存问题：

    • 减小LIMIT环境变量
    • 更具体地过滤搜索结果
    • 考虑为非常大的内容实现响应流

调试日志记录

服务器将调试信息输出到stderr：

  • 搜索查询和承载令牌
  • API响应状态
  • 错误消息和堆栈跟踪

通过设置启用详细日志记录：

export DEBUG=confluence-mcp:*

性能监控

监控关键指标：

  • Confluence搜索的响应时间
  • 大型内容检索期间的内存使用情况
  • 搜索操作的错误率

集成示例

与MCP客户端一起使用

Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "confluence-mcp": {
      "command": "node",
      "args": ["c:/dev/confluence_mcp/build/confluence.js"],
      "env": {
        "CONFLUENCE_BEARER_TOKEN": "your_token_here",
        "LIMIT": "5"
      }
    }
  }
}

自定义MCP客户端

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['./build/confluence.js']
});

const client = new Client({
  name: "confluence-client",
  version: "1.0.0"
}, {
  capabilities: {}
});

await client.connect(transport);

许可证

ISC许可证

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 添加测试（在实现测试框架时）
  5. 提交拉取请求

更新日志

版本1.0.0

  • 首次发布Confluence搜索工具
  • MCP SDK集成
  • TypeScript实现
  • 基本错误处理和日志记录

有关模型上下文协议的更多信息，请访问：https://modelcontextprotocol.io/

相关 MCP