MCP 数据收发服务（这是一个本地MCP服务）

为只能以插件方式使用AI、或只能用该公司自己的带AI的IDE时，建立一个本地通道以API的方式调用AI，实现灵活用AI（如代码调用）

本地运行的"程序 ⇄ AI"数据桥梁：你的程序把文本/图片推给服务，AI（如 CodeBuddy）通过 MCP 读取并返回结果，程序再取回 AI 的回答。

• 仅依赖 Python 标准库（Python 3.7+，无需 pip install 任何东西）

• 纯本地运行（默认只监听 127.0.0.1，数据不出本机）

• 图片自动保存到 received_images/，消息持久化到 messages.jsonl

Related MCP server: Stream MCP

一、运行前你需要自己准备的东西

不需要：安装依赖包、注册账号、申请任何 API 密钥——服务的 api_key 首次运行时自动生成。

二、快速启动

1. 启动服务：双击 run.bat（或命令行执行 python mcp_service.py）。 首次运行会自动生成 config.json，其中包含随机生成的 api_key，并在启动窗口直接显示：

   接收接口(其他程序推送数据):
     POST http://127.0.0.1:8765/receive
     请求头: X-API-Key: dk_xxxxxxxxxxxxxxxx...

2. 记下窗口里的 api_key（也可以打开 config.json 查看）。这就是你程序推送数据时要用的密钥。

3. （可选）连接 CodeBuddy，见第三节。

4. 推送数据测试：双击 run_ui.bat 打开图形测试工具，填入 base_url 和 api_key 即可发文字/图片；或参考 examples/ 里的例程自己写客户端。

三、配置

config.json（首次运行自动生成，可手动修改）

{
  "api_key": "dk_xxxx...",      // 推送数据的密钥，可自己改成任意字符串
  "http_host": "127.0.0.1",     // 监听地址，默认仅本机
  "http_port": 8765             // HTTP 端口
}

• 换端口：改 http_port 后重启；或临时用 python mcp_service.py --port 9000 覆盖。

• 重置密钥：删除 config.json 后重启，会自动生成新 key。

连接 以CodeBuddy示例（二选一）

方式 A：stdio（推荐） —— 在 CodeBuddy 的 MCP 设置中添加：

{
  "mcpServers": {
    "gm-data-bridge": {
      "transport": "stdio",
      "command": "python",
      "args": ["<你的项目路径>/mcp_service.py", "--stdio"],
      "disabled": false,
      "description": "数据收发桥：其他程序通过 base_url+api_key 推送文本/图片，AI 通过工具读取"
    }
  }
}

stdio 模式下服务会随 CodeBuddy 自动启动，并同时开启 HTTP 接收端口。

方式 B：Streamable HTTP —— 服务先以 run.bat 启动，MCP 连接地址填 http://127.0.0.1:8765/mcp，请求头带 X-API-Key: <你的 api_key>。

AI 侧怎么读数据

对 AI 说一句即可，例如：

循环调用 get_new_data（wait_seconds=15），循环100次

或："看看有没有新数据"（AI 收到新数据时会有 收到新数据 #N 的通知提示）。

四、HTTP 接口速查（所有请求带请求头 X-API-Key）

客户端使用要点（examples/ 例程已封装好）：

• 游标机制：程序里维护 after_id（上次读到的最大编号），每次 receive_results 后更新，不重复不漏。

• 长轮询：wait_seconds=10 表示没新结果时服务端等 10 秒再返回，外部程序可放心用到 60 秒。

• AI 侧配合：AI 收到数据后必须调用 send_result，结果才会出现在 /responses 里。

五、MCP 工具列表（AI 侧可用）

六、例程与测试工具

两个例程都封装了 4 个方法，可直接复制到你的项目里用： send_text(text)、send_image(path)、send_text_image(text, path)、receive_results(after_id, wait_seconds)。

使用例程前，把代码里的 API_KEY 占位符改成你自己的 key（见 config.json 或启动窗口输出）。

附带的测试工具： 双击run_ui.bat 启动 ui_tester.py：图形界面测试工具，可视化发送文字/图片、查看 AI 返回。

七、目录文件说明

mcp_service.py          主程序（单文件，仅标准库）
run.bat                 启动服务（HTTP 模式）
run_ui.bat              启动图形测试工具
ui_tester.py            图形测试工具源码
config.json             配置（首次运行自动生成，已加入 .gitignore）
codebuddy_mcp_config.json  CodeBuddy stdio 配置示例
examples/               Python / Java 客户端例程
messages.jsonl          收到的消息持久化（运行时生成）
responses.jsonl         AI 返回结果持久化（运行时生成）
read_state.json         已读状态（运行时生成）
received_images/        收到的图片（运行时生成）

八、隐私与安全说明

• 服务默认只监听 127.0.0.1，外部设备无法访问。

• config.json（含 api_key）及所有运行时数据文件均已列入 .gitignore，不会被提交到 Git。

• 例程中的 API_KEY 均为占位符，需替换为你本机 config.json 中的实际值。