Ib API Tools MCP Server

IntelligenceBank API工具MCP服务器

一个远程MCP服务器，提供通过IntelligenceBank OAuth桥使用OAuth 2.0身份验证与IntelligenceBankneneneba API交互的工具。

概述

该服务器使AI助手（如Claude）能够通过安全、经过身份验证的连接与IntelligenceBank API进行交互。它使用：

• 运输：用于远程访问的流式HTTP
• 认证：使用PKCE的OAuth 2.0授权代码流
• OAuth桥：AWS Lambda的托管身份验证服务
• 部署：可以在本地或EC2上运行以供生产使用

快速开始

地方发展

1. 克隆并安装

   git clone https://github.com/ibproduct/ib-api-tools-mcp-server.git
   cd ib-api-tools-mcp-server
   npm install

1. 配置环境

   cp .env.example .env
   # Edit .env with your configuration

1. 构建并运行

   npm run build
   npm run dev

服务器运行于 http://localhost:3000/mcp

1. 使用MCP检查员进行测试

   npx @modelcontextprotocol/inspector

连接到： http://localhost:3000/mcp

Claude桌面配置

添加到您的Claude桌面配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ib-api-tools": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

对于生产部署，请使用： https://mcp.connectingib.com/mcp

MCP资源

服务器通过MCP资源协议提供可浏览的IntelligenceBank资源，允许Claude直接浏览文件夹和文件。

资源URI方案

资源使用自定义URI方案： ib://{clientid}/{type}/{id}

资源类型：

• folder -访问文件夹元数据和子文件夹
• resource -访问详细的文件元数据
• folder-resources -列出文件夹中的所有文件
• search -跨资源搜索

示例：

ib://BnK4JV/folder/123           # Folder details
ib://BnK4JV/resource/456         # File details
ib://BnK4JV/folder-resources/123 # Files in folder
ib://BnK4JV/search/query         # Search results

Claude中的用法

身份验证后，您可以将IntelligenceBank资源附加到对话中：

1. 单击Claude中的附件图标
2. 选择“从资源中选择”
3. 浏览IntelligenceBank文件夹和文件
4. 在对话中附加上下文资源

资源提供元数据，包括：

• 文件夹结构和层次结构
• 文件名、类型和大小
• 创建和修改日期
• 访问权限
• 自定义元数据字段

可用工具

身份验证工具

auth_login

通过自动令牌交换启动OAuth 2.0身份验证流。

输入：

• platformUrl （可选）：您的IntelligenceBank实例URL（例如。， https://demo.intelligencebank.com)

输出：

• authorizationUrl：用于身份验证的URL
• sessionId：用于跟踪身份验证进度的会话标识符
• instructions：用户友好的后续步骤说明

例子：

use_mcp_tool ib-api-tools auth_login { "platformUrl": "https://demo.intelligencebank.com" }

auth_status

检查身份验证状态并检索令牌或用户信息。

输入：

• sessionId （可选）：登录步骤中的会话ID（用于轮询身份验证）
• accessToken （可选）：用于验证和获取用户信息的访问令牌

注： 提供其中之一 sessionId 或 accessToken不是两者都有。

输出（带会话ID）：

• status：身份验证状态（待定/已完成/错误）
• authenticated：表示完成的布尔值
• tokens：访问和刷新令牌（如果已完成）
• userInfo：用户详细信息（如果已完成）

输出（带accessToken）：

• authenticated：布尔值，指示令牌是否有效
• userInfo：用户详细信息（如果有效）
• expiresIn：令牌到期前的秒数

例子：

// Check authentication progress
use_mcp_tool ib-api-tools auth_status { "sessionId": "session-id-from-login" }

// Validate existing token
use_mcp_tool ib-api-tools auth_status { "accessToken": "your-access-token" }

api_call

使用直接API访问对IntelligenceBank进行经过身份验证的API调用。

输入：

• sessionId：来自成功身份验证的会话ID
• method：HTTP方法（GET、POST、PUT、DELETE、PATCH）
• path：API端点路径（例如。， /api/3.0.0/BnK4JV/resource)
• body （可选）：POST/PUT/PATCH请求的请求体
• headers （可选）：附加标题

输出：

• success：布尔值，指示请求是否成功
• data：来自API的响应数据
• status：HTTP状态代码

特征：

• 使用IntelligenceBank会话ID(sid)用于身份验证
• 清除身份验证失败的错误消息
• 具有重新身份验证提示的会话过期检测
• 瞬态故障的重试逻辑

例子：

use_mcp_tool ib-api-tools api_call {
  "sessionId": "your-session-id",
  "method": "GET",
  "path": "/api/3.0.0/BnK4JV/resource"
}

合规性审查工具

get_compliance_filters

检索可用的类别筛选器以进行合规性审查。

输入：

• sessionId：来自成功身份验证的会话ID

输出：

• filters：可用类别筛选器数组，包括：

- name：筛选器名称（例如，“渠道”、“市场”、“地区”） - values：可选择的过滤器值数组 - uuid：每个值的唯一标识符

例子：

use_mcp_tool ib-api-tools get_compliance_filters {
  "sessionId": "your-session-id"
}

运行文件_合规性_查看

通过自动轮询运行完整的文件合规性审查工作流。

输入：

• sessionId：来自成功身份验证的会话ID
• file：要查看的文件（支持多种格式）：

- 字符串路径： "/path/to/file.pdf" - 具有路径的对象： { "path": "/path/to/file.pdf" } - base64对象： { "filename": "doc.pdf", "content": "base64..." }

• categorization （可选）：要应用的类别筛选器数组：

  [
    {
      "categoryName": "Channel",
      "selectedOptions": ["Digital", "Print"]
    }
  ]

• pollTimeout （可选）：等待审核完成的最长时间（秒）（默认值：300）
• pollInterval （可选）：状态检查之间的时间间隔（秒）（默认值：5）

输出：

• reviewId：审核的唯一标识符
• status：审查状态（“已完成”或“错误”）
• summary：调查结果概述：

- totalIssues：发现的合规问题总数 - issuesByRule：按规则类型细分 - issuesByPage：按页码细分

• issues：一系列详细的合规调查结果，包括：

- term：引发问题的文本 - explanation：合规问题说明 - sentence：包含该问题的完整句子 - ruleName：内部规则标识符 - ruleDescription：用户友好的规则名称 - page：发现问题的页码 - feedback （可选）：附加指导

特征：

• 将文件上传到IntelligenceBank
• 创建具有可选分类的合规性审查
• 自动轮询完成情况（通常2-3分钟）
• 返回格式化的、用户友好的结果
• 支持PDF和其他文档格式

例子：

use_mcp_tool ib-api-tools run_file_compliance_review {
  "sessionId": "your-session-id",
  "file": "/path/to/document.pdf",
  "categorization": [
    {
      "categoryName": "Channel",
      "selectedOptions": ["Digital"]
    },
    {
      "categoryName": "Market",
      "selectedOptions": ["APAC"]
    }
  ]
}

授权交换（已撤销）

此工具已弃用。这 /callback 端点现在自动处理令牌交换。使用 auth_login 和 auth_status 相反。

OAuth流

自动流量（推荐）

OAuth流现在是完全自动的，具有基于会话的跟踪功能：

1. 启动登录：呼叫 auth_login 接收：

- 在浏览器中访问的授权URL - 用于跟踪身份验证进度的会话ID

1. 用户认证:

- 访问浏览器中的授权URL - 选择您的IntelligenceBank平台 - 完成登录过程

1. 自动令牌交换:

- 身份验证成功后，您将被重定向到 /callback - 服务器自动为令牌交换授权码 - 您将看到一个成功确认页面 - 令牌存储在会话中

1. 检索令牌:

- 投票 auth_status 使用您的会话ID - 接收访问令牌、刷新令牌和用户信息

1. 进行API调用:

- 使用 api_call 用于身份验证请求的会话ID工具 - 令牌在需要时自动刷新 - 仅当刷新令牌过期时才需要重新身份验证

会话管理

• 如果身份验证未完成，会话将在5分钟后过期
• 每分钟自动清理过期会话
• API调用期间出现401个错误时，令牌自动刷新
• 仅当会话或刷新令牌过期时才需要重新身份验证

可用提示

合规性_查看_帮助

登录后指导提示，帮助用户运行文件合规性审查。此提示在身份验证成功后出现，并提供以下分步说明：

1. 可选择检查可用的类别筛选器
2. 运行文件合规性审查
3. 了解审查结果

环境变量

所需的环境变量（请参见 .env.example):

• OAUTH_BRIDGE_URL：OAuth网桥服务URL
• OAUTH_CLIENT_ID：此MCP服务器的客户端标识符
• OAUTH_REDIRECT_URI：OAuth回调URL
• PORT：服务器端口（默认值：3000）
• NODE_ENV：环境（开发/生产）
• ALLOWED_ORIGINS：CORS允许的来源
• ENABLE_DNS_REBINDING_PROTECTION：启用源验证
• ALLOWED_HOSTS：允许用于DNS重新绑定保护的主机名

文档

综合文档可在 docs/ 目录：

• 身份验证审核：全面的身份验证架构分析
• 开发工作流程：本地开发、测试和部署
• 技术栈：技术选择和架构
• 代码库摘要：项目结构和组成部分
• 当前任务：当前发展状况
• 项目路线图：目标和进展

关键概念

双重身份验证系统：

• OAuth 2.0令牌：用于MCP协议合规性（访问令牌、刷新令牌）
• 智能银行凭据：用于实际的API调用（sid、clientId、apiV3url）

OAuth网桥在令牌响应中返回这两种类型的凭据。OAuth令牌满足MCP SDK要求，而IntelligenceBank会话凭据(sid)用于直接API调用。

生产部署

实时生产服务器：

• 端点: https://mcp.connectingib.com/mcp
• 例子：EC2 i-0d648adfb366a8889（us-west-1）
• 安全套接层：Let's Encrypt证书（启用自动续订）
• 状态：运行并验证✓

有关部署的详细信息，请参阅 开发工作流程 文档。

关键步骤：

1. 使用Node.js和nginx设置EC2实例
2. 克隆存储库并构建
3. 配置生产环境变量
4. 从PM2流程管理器开始
5. 使用SSL/TLS配置nginx反向代理
6. 设置DNS和SSL证书

安全

• OAuth 2.0与PKCE用于安全身份验证
• 生产需要HTTPS
• 允许的源的CORS配置
• DNS重新绑定保护
• 令牌到期和刷新处理

支持

• 问题: https://github.com/ibproduct/ib-api-tools-mcp-server/issues
• 文档：参见 docs/ 目录
• OAuth桥: https://github.com/ibproduct/ib-oauth-bridge-experimental

许可证

麻省理工学院