CodeBuddy 配置 MCP 服务：从本地启动到工具调用逐步排错

CodeBuddy 配置 MCP 服务，关键是先让服务器完成协议握手，再验证工具调用，而不是把一个普通函数路径填进设置。本文用标准输入输出连接一个本地文字统计工具，拆开检查启动、发现工具和返回结果三个环节。

CodeBuddy 接入 MCP先验证工具真的能调用

你可能遇到过这样的情况：配置没有语法错误，界面却显示连接失败；或者服务器已经变绿，助手仍然没有使用工具。两者需要检查的地方并不相同。本文从一个不读文件、不访问网络的最小服务开始，给出 Windows 配置、预期结果和故障定位顺序。编程狮把范围限定为 CodeBuddy IDE 的本地 MCP 接入，不把云端部署、鉴权网关和多工具编排混在第一步里。

一、先分清客户端、服务进程和工具函数

MCP 是客户端与服务端交换能力和调用结果的协议。CodeBuddy 在这里是客户端，Python 程序是服务端，文字统计函数只是服务端公开的一项工具。普通脚本能够运行，不等于它已经实现初始化、工具列表和调用响应。

本例采用 stdio 传输：客户端启动子进程，通过进程的标准输入和标准输出收发协议消息。这意味着配置中的 command 是启动程序，不是模型名称；args 是传给该程序的参数，不是聊天提示词。JSON 里的路径必须指向实际存在的解释器和脚本。

另一个重要边界是数据流。本地运行只说明工具进程在本机，不保证工具返回的内容永远不离开电脑。返回值可能进入助手的上下文。初次测试不要使用真实客户资料、密钥或私人文件，先用无敏感信息的字符串确认连通性。可以先阅读 CodeBuddy 文档熟悉 IDE 里的配置区域。

二、写一个真正提供 MCP 能力的最小服务

以下示例面向 Python 3.10 及以上和 MCP Python SDK 1.x。建立一个独立目录，在该目录创建虚拟环境并安装依赖。Windows PowerShell 执行：

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install "mcp>=1.12,<2"

如果系统没有 py 启动器，就把第一行的 py 换成已安装 Python 的完整路径。虚拟环境创建失败时不要继续填 IDE 配置，否则后续所有问题都会被包装成“连接失败”。安装完成后，保存下面的文件为 server.py：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("text-lab")

@mcp.tool()
def word_count(text: str) -> dict:
    """统计 Unicode 码点数，以及按空白分隔的片段数；不是中文分词。"""
    return {
        "characters": len(text),
        "segments": len(text.split()),
    }

if __name__ == "__main__":
    mcp.run(transport="stdio")

这个工具的两个字段有意区分含义。characters 使用 Python 字符串长度，包含空格，计算的是 Unicode 码点，不是所有情况下的视觉字形数量；segments 按空白切分，不把连续中文拆成词。输入“你好 MCP”时，预期结果为六个码点、两个片段。提前写清口径，可以避免调用成功后又把结果误判成算法错误。

用虚拟环境中的解释器运行 server.py，程序等待输入而没有出现普通提示符，这是 stdio 服务的正常表现之一，但它仍不等于握手成功。先确认没有导入异常，再停止手动启动的进程，让 IDE 按配置管理自己的子进程。

不要在服务器里用 print 输出“启动成功”。标准输出是协议通道，额外文字会破坏消息解析。调试日志应写入标准错误流，或使用明确指向标准错误的日志处理器。工具需要返回的信息通过 return 交给 SDK 编码，不要自行拼接协议字符串。

三、填入绝对路径，再按三个层级验收

在 CodeBuddy IDE 对话区域的设置中进入 MCP，选择添加服务器并录入 JSON。下面假定目录是 C:\mcp-text-lab，实际使用时把两处路径一起改成你自己的目录：

{
  "mcpServers": {
    "text-lab": {
      "type": "stdio",
      "command": "C:\\mcp-text-lab\\.venv\\Scripts\\python.exe",
      "args": ["C:\\mcp-text-lab\\server.py"]
    }
  }
}

反斜杠在 JSON 字符串中要转义。不要把解释器与脚本拼进 command，也不要依赖终端里已激活的虚拟环境：IDE 启动的子进程不一定继承那个终端的状态。完整路径能减少“终端可以、客户端不行”的差异。参数含空格时，仍把每个参数作为独立数组元素，不要额外塞入一层 shell 引号。

接下来依次验收：第一，看服务器状态是否正常；第二，看工具列表里是否出现 word_count；第三，在 Try to Run 或支持工具调用的 Craft Agent 中，明确要求调用它统计“你好 MCP”，检查返回值是否符合前面的口径。三层分别对应连接、能力发现和执行，不能用绿色图标代替最后一步。

相关入口可以对照 CodeBuddy IDE 配置 MCP。界面文字可能随版本调整，但这三个验收层级不变。先用明确点名工具的请求排查，再测试自然语言是否能让助手合理选择它。

四、连接失败时，按错误发生的位置缩小范围

表现	优先检查	不要先做什么
进程根本没起来	command 文件是否存在、执行权限	更换模型
提示模块不存在	是否使用装了依赖的那个解释器	在另一个环境反复安装
启动后立即断开	异常日志、标准输出杂音	把错误日志当协议返回
已连接但没有工具	装饰器注册、启动文件、工具列表	只改工具描述
工具存在但未被调用	当前模式、调用许可、提示是否明确	宣称服务一定故障

每次只改一个变量，然后重复同一个输入。把解释器路径、SDK 版本、连接状态、工具是否出现和调用结果记在一张记录里，才知道哪一次修改真正有效。不要把包含密钥的完整环境变量列表粘贴给别人。

若未来增加文件读取工具，应单独设计允许目录和大小限制，而不是给这个示例直接加一个任意路径参数。若工具会写文件或访问收费接口，应让调用范围与用户授权一致。MCP 提供连接方式，不自动替你完成权限设计。

本地 SDK 的协议测试只能证明服务器实现可以被合规客户端发现和调用。CodeBuddy 的实际界面、账户权限和工具审批仍需在你的客户端验收；不能把前者包装成后者已经成功。协议实现参考 MCP Python SDK 官方仓库，IDE 操作参考 CodeBuddy 官方 MCP 指南。

工具函数必须通过协议暴露

总结

CodeBuddy 配置 MCP 服务可以按“解释器能启动、协议能握手、工具能发现、结果能核对”逐项推进。最小文字工具的价值不是功能多，而是让每次失败都能对应到明确的一层。

等这个输入稳定通过，再逐步加入业务能力。保留一个无网络、无敏感数据的测试工具，升级 SDK 或迁移电脑之后还可以用它区分环境问题与业务问题。

延伸学习

用 Python 3 教程补齐函数、虚拟环境与异常处理基础。
阅读 AI 编程技能教程，理解可复用工作步骤与外部工具的区别。
参考 MCP 与语音客服实践笔记，观察工具接入更大应用时的数据流。

常见问题

Q：为什么运行服务器后终端一直没有输出？

A：stdio 服务会等待客户端消息，不会像普通脚本一样打印菜单。没有异常只是第一步，还要让 MCP 客户端完成初始化和工具调用。

Q：可以把 API 密钥写进这个 JSON 吗？

A：本例不需要密钥。真实服务优先使用受控的环境变量或产品提供的密钥管理方式，不把密钥提交到仓库或截图分享。

Q：绿色状态是不是代表助手一定会调用工具？

A：不是。还取决于工具是否被发现、当前模式是否支持调用、审批设置以及请求内容。先明确点名工具验证，再检查自动选择行为。