基于MCP协议实现AI助手个性化：Terminal Buddies项目实战解析

1. 项目概述当你的终端伙伴遇见AI助手如果你和我一样每天有大量时间泡在终端和代码编辑器里那么一个能带来些许乐趣和陪伴感的“数字伙伴”或许能点亮枯燥的编码时光。Terminal Buddies 正是这样一个巧妙结合了复古 ASCII 艺术、轻量级游戏化元素和现代 AI 开发工具链的项目。它的核心是一个 MCP 服务器能将你在 terminalbuddies.com 网站上“孵化”出的一个独一无二的 ASCII 伙伴无缝注入到你的 AI 编码助手如 Claude Code、Cursor 等的会话中。简单来说这不仅仅是一个会动的 ASCII 字符画。你孵化出的每个“伙伴”都拥有自己的物种、稀有度、属性和鲜明的“人格”描述。通过这个 MCP 服务器你的 AI 助手在每次与你对话时都能“认识”你的伙伴。这意味着当你向 Claude 提问“如何优化这个循环”时它不仅能从技术角度回答还可能根据你伙伴那“充满混乱特工”的人格调侃一句“看来 Sparky你的龙伙伴的混沌属性又发作了让我们来驯服这段代码吧。” 这种微妙的上下文注入让工具的使用体验变得更具个性化和趣味性。这个项目巧妙地站在了几个趋势的交汇点一是 MCP 协议的兴起它正在成为连接 AI 助手与外部工具和上下文的事实标准二是开发者对个性化、趣味性工作流的追求。它没有复杂的依赖核心就是一个 Node.js 脚本但其设计思路却非常值得借鉴——如何将轻量级的游戏化数据通过标准协议转化为能影响 AI 行为的上下文信息。2. 核心原理与架构拆解MCP 如何让 AI “认识”你的伙伴要理解 Terminal Buddies MCP 服务器的工作原理我们需要先拆解两个核心部分MCP 协议本身以及这个服务器如何利用该协议。2.1 MCP 协议AI 助手的“感官”与“手脚”MCP 并非一个具体的软件而是一个开放协议。你可以把它想象成 AI 助手的“插件系统”或“外设驱动标准”。在没有 MCP 之前每个 AI 助手如 Claude Code、Cursor AI都需要自己开发对接各种工具如文件系统、数据库、API的能力这导致了功能重复和生态封闭。MCP 定义了一套标准化的通信方式通常基于 JSON-RPC over stdio允许独立的“服务器”向 AI 助手“客户端”提供两种核心资源工具可以调用的函数。例如一个“查询天气”的 MCP 服务器会提供一个get_weather工具。AI 助手在认为需要时会调用这个工具并获取结果。上下文/指令静态的提示信息或动态的上下文数据。这些信息会在会话开始时或定期注入到 AI 助手的系统提示中直接影响其“认知”和行为模式。Terminal Buddies 的服务器同时利用了这两者这是其设计精巧之处。2.2 Terminal Buddies MCP 服务器的双通道设计这个用 Node.js 编写的服务器在启动并与 AI 客户端建立连接后会执行以下关键操作通道一注入静态人格指令这是最核心的部分。服务器会读取你放置在特定目录下的buddy.json文件。这个文件里包含了你的伙伴的所有元数据名字、物种、人格描述、属性值等。服务器会将这些信息格式化为一段清晰的自然语言描述然后通过 MCP 的instructions或context协议取决于实现发送给 AI 客户端。注意这段指令是“静默”注入的。它不会作为一条可见消息出现在聊天记录里而是成为 AI 助手系统提示的一部分。这就好比你在和某人聊天前先悄悄告诉他“和你聊天的人养了一条叫 Sparky 的龙它性格混乱喜欢恶作剧。” 这会让 AI 的回复自然地带上相关的色彩。通道二提供动态查询工具除了静态注入服务器还暴露了三个工具函数供 AI 助手在对话中主动调用get_buddy_info: 获取伙伴的完整档案。当用户问“我的伙伴是谁”时AI 可以调用此工具来回答。check_buddy_level: 检查伙伴的等级、经验值和会话计数。这里涉及一个简单的游戏化逻辑伙伴会随着你的编码会话而升级。buddy_mood: 检查伙伴当前的心情。心情可能根据等级、互动频率等因素动态变化例如升级后会进入“兴奋”状态。这种“静态指令动态工具”的组合既保证了伙伴人格对 AI 的持续影响又允许在对话中进行具体的、数据驱动的交互设计层次非常清晰。2.3buddy.json数字伙伴的“基因文件”这个 JSON 文件是整个项目的灵魂和数据源。它从 terminalbuddies.com 网站生成并下载结构设计得既有趣又实用{ version: 1, source: terminalbuddies.com, buddy: { name: Sparky, personality: Agent of chaos. Your git history fears this one., hatchedAt: 1711900000000, traits: { species: dragon, rarity: rare, eye: ×, hat: wizard, shiny: false, stats: { DEBUGGING: 39, PATIENCE: 24, CHAOS: 80, WISDOM: 1, SNARK: 16 } } } }人格描述personality字段是 AI 理解伙伴性格的关键。像“混沌特工”这样的描述会直接引导 AI 生成更具幽默感或戏剧性的回复。属性值stats下的数值如CHAOS: 80为未来的功能扩展留下了空间。理论上服务器或 AI 可以依据这些数值调整回复的“混乱”程度甚至影响代码建议的风格比如高混乱值可能对应更激进的重构建议当然目前这更多是一种趣味设定。可扩展性traits对象包含了物种、装饰等这种结构易于未来添加新的特征或互动维度。3. 全平台部署与配置实战项目的官方一键安装脚本非常方便但作为开发者理解其手动安装和跨平台配置的细节能让你在遇到问题时游刃有余也能更灵活地定制。下面我将分工具详细拆解。3.1 基础环境准备与手动安装无论使用哪个 AI 工具第一步都是获取 MCP 服务器本身。步骤 1创建服务器目录并获取源码官方脚本会创建~/.claude/buddy-mcp/目录但你可以根据喜好或工具要求放在任何地方。手动安装过程揭示了其简单本质# 选择一个基准目录这里以 ~/.config 为例 mkdir -p ~/.config/buddy-mcp cd ~/.config/buddy-mcp # 下载服务器核心文件 curl -sL https://terminalbuddies.com/mcp/server.mjs -o server.mjs curl -sL https://terminalbuddies.com/mcp/package.json -o package.json # 安装唯一的依赖modelcontextprotocol/sdk npm install实操心得server.mjs是 ES Module 格式.mjs后缀确保你的 Node.js 版本在 18 以上以获得最好的支持。如果遇到Cannot use import statement outside a module错误检查文件后缀和package.json中是否设置了type: module。步骤 2获取你的伙伴数据访问 terminalbuddies.com 点击页面上的蛋进行孵化。这是一个有趣的瞬间你会随机获得一个带有各种属性的 ASCII 伙伴。孵化后找到“Use in Terminal”或类似的按钮下载buddy.json文件。步骤 3放置配置文件将下载的buddy.json文件移动到上一步创建的服务器目录中例如~/.config/buddy-mcp/buddy.json。服务器在启动时会自动读取同目录下的这个文件。3.2 配置主流 AI 开发工具MCP 的优势在于其协议的统一性但每个客户端工具的配置方式略有不同。以下是针对不同工具的详细配置指南。Claude CodeClaude Code 是目前对 MCP 支持最直接的工具之一。配置通过命令行完成# 假设你的 server.mjs 在 ~/.config/buddy-mcp/ claude mcp add buddy -- node ~/.config/buddy-mcp/server.mjs这条命令会向 Claude Code 注册一个名为 “buddy” 的 MCP 服务器。你可以通过claude mcp list查看已注册的服务器使用claude mcp remove buddy来移除。注意事项claudeCLI 工具需要已正确安装并登录。确保node命令在你的系统 PATH 中。如果服务器路径包含空格需要使用引号包裹。CursorCursor 的配置通过项目或全局的 JSON 配置文件完成。通常你需要在项目根目录或全局配置目录下创建或修改.cursor/mcp.json文件{ mcpServers: { buddy: { command: node, args: [/absolute/path/to/your/.config/buddy-mcp/server.mjs], env: {} } } }重要提示Cursor 的配置对路径非常敏感。强烈建议使用绝对路径而不是~符号。~在 Shell 中会被展开但在 JSON 配置文件中它只是一个普通字符可能导致 “No such file or directory” 错误。你可以通过echo ~/.config/buddy-mcp/server.mjs在终端获取绝对路径。VS Code with Continue / Cline如果你在 VS Code 中使用 Continue 或 Cline 插件配置方式如下在项目根目录或全局配置路径如~/.continue/config.json中找到或创建配置文件。在mcpServers数组中添加配置{ mcpServers: [ { name: buddy, command: node, args: [/absolute/path/to/your/.config/buddy-mcp/server.mjs] } ] }配置完成后通常需要重启 VS Code 或重新加载 Continue 插件以使配置生效。Gemini CLIGoogle 的 Gemini CLI 工具同样支持 MCP。其配置文件通常位于~/.gemini/settings.json{ mcpServers: { buddy: { command: node, args: [/absolute/path/to/your/.config/buddy-mcp/server.mjs] } } }Windsurf / Zed这些较新的编辑器也正在加入 MCP 生态。它们的配置方式通常类似在设置中寻找 “MCP Servers” 或 “AI Context” 相关选项并以 JSON 格式添加服务器定义。请查阅各自的最新文档因为配置界面可能还在演进中。3.3 验证与测试安装配置完成后如何验证 Terminal Buddy 是否在正常工作直接测试服务器你可以在终端手动运行服务器虽然它不会输出太多信息因为它使用 stdio 通信但可以检查是否有报错cd ~/.config/buddy-mcp node server.mjs # 正常情况下它会启动并等待连接没有输出。按 CtrlC 退出。在 AI 会话中验证这是最直接的验证方式。在你的 AI 工具中开启一个新会话然后尝试提问“我的终端伙伴是谁”“Sparky 今天心情怎么样”“我的伙伴有什么特点”如果配置成功AI 助手应该能调用get_buddy_info或buddy_mood工具并给出基于buddy.json内容的回答。例如它可能会回复“你的伙伴是 Sparky一只稀有的龙戴着巫师帽。它被描述为‘混沌特工’你的 git 历史都会怕它。目前它的心情看起来是‘专注’正在监督你写代码呢。”4. 高级玩法与自定义探索基础功能只是开始。作为一个开源项目Terminal Buddies MCP 为我们提供了自定义和扩展的绝佳样板。4.1 伙伴的切换与多伙伴管理官方支持很简单孵化新伙伴下载新的buddy.json覆盖旧文件然后重启你的 AI 工具会话即可。但我们可以做得更优雅。方案一符号链接切换创建一个专门的目录存放所有伙伴的 JSON 文件然后通过符号链接动态指向当前活跃的伙伴。# 创建存储目录 mkdir -p ~/.buddies-collection # 将下载的 buddy_sparky.json, buddy_fluffy.json 等移入此目录 # 在 MCP 服务器目录创建指向当前伙伴的符号链接 cd ~/.config/buddy-mcp ln -sf ~/.buddies-collection/buddy_sparky.json buddy.json # 编写一个简单的切换脚本 switch-buddy.sh #!/bin/bash # 用法: ./switch-buddy.sh sparky cd ~/.config/buddy-mcp ln -sf ~/.buddies-collection/buddy_$1.json buddy.json echo Switched to buddy: $1这样你可以通过一条命令在不同伙伴间切换无需移动文件。方案二修改服务器以支持环境变量如果你懂一点 Node.js可以修改server.mjs让其从环境变量或命令行参数读取 JSON 文件路径。// 在 server.mjs 开头附近修改读取 buddy.json 的部分 import { readFile } from fs/promises; const buddyPath process.env.BUDDY_JSON_PATH || ./buddy.json; const buddyData JSON.parse(await readFile(buddyPath, utf-8));然后启动服务器时指定路径BUDDY_JSON_PATH~/.buddies-collection/buddy_fluffy.json node server.mjs在 Claude Code 中注册时也需要带上环境变量这稍微复杂一些可能需要封装一个启动脚本。4.2 解读与扩展buddy.json的游戏化逻辑buddy.json中的stats和traits目前主要用于展示但我们可以设想或实现一些有趣的扩展基于属性的回复风格化修改 MCP 服务器注入的指令。例如如果CHAOS值很高可以在指令中添加“用户伙伴的混沌属性极高请在提供代码建议时偶尔加入一些大胆、非常规但可能有效的方案并用幽默的口吻提醒其潜在风险。”动态心情算法当前的buddy_mood工具可能只是随机或基于固定规则返回心情。你可以实现一个简单算法心情 基础值 等级提升带来的兴奋度 - 长时间未互动产生的疲劳度。将算法写入服务器让伙伴的反馈更具动态性。会话统计与升级check_buddy_level工具背后可以连接一个简单的本地数据库如一个level.json文件记录会话次数、时长。实现一个经验值系统每完成一个编码会话例如AI 助手检测到用户说“谢谢”或一段时间无活动就增加一点经验。积累到一定经验后升级并在下次调用工具时返回升级信息。4.3 开发自己的 MCP 服务器以此为蓝本Terminal Buddies 的服务器代码在 terminalbuddies.com 网站上可直接查看是一个极佳的学习 MCP 服务器开发的入门范例。它的结构清晰导入 SDKimport { Server } from modelcontextprotocol/sdk定义工具使用server.setRequestHandler为tools/list和tools/call请求注册处理函数。定义指令使用server.setRequestHandler为context/get或instructions/list请求注册处理函数返回包含伙伴信息的文本。启动服务器调用server.connect使用 stdio 传输层。如果你想创建自己的 MCP 服务器例如一个注入当前项目 Git 状态、TODO 列表或系统监控信息的服务器完全可以以此为模板替换掉读取buddy.json和定义相关工具的逻辑即可。这比从头开始要容易得多。5. 常见问题排查与优化技巧在实际部署和使用过程中你可能会遇到一些问题。以下是一些常见情况的排查思路和解决方案。5.1 服务器连接失败或 AI 助手无法识别问题现象可能原因排查步骤与解决方案AI 助手完全不理睬关于伙伴的提问。1. MCP 服务器未成功启动或注册。2. 配置文件路径错误。3. AI 工具不支持或未启用 MCP。1.检查注册运行claude mcp list或查看对应工具的 MCP 设置页面确认 “buddy” 服务器在列表中且状态正常。2.检查路径确保配置文件中args里的路径是绝对路径并且server.mjs文件确实存在且可读。3.检查 Node在配置的路径下手动运行node server.mjs看是否有语法错误或依赖缺失Error: Cannot find module。确保 Node.js 版本 18。4.查看日志某些工具如 Continue有开发者控制台或日志输出查看是否有 MCP 连接错误信息。AI 助手回应“我不知道你的伙伴”或回答与buddy.json内容不符。1.buddy.json文件缺失或格式错误。2. MCP 服务器读取文件失败。3. 指令注入未生效。1.确认文件检查buddy.json是否位于服务器同一目录且文件名拼写正确。2.验证 JSON使用cat buddy.json | python -m json.tool或jq . buddy.json命令检查 JSON 格式是否正确。3.重启会话MCP 的指令通常在新会话开始时注入。尝试关闭当前 AI 聊天窗口重新开启一个新会话再提问。4.测试工具直接问“调用 get_buddy_info 工具看看我的伙伴信息”如果 AI 能调用并返回正确信息说明工具通道正常可能指令通道配置有异。配置后启动 AI 工具报错。配置文件语法错误JSON 格式错误。使用在线 JSON 校验器或jq工具检查你的mcp.json、config.json等配置文件。特别注意尾随逗号、引号不匹配等问题。5.2 性能与使用体验优化服务器启动延迟MCP 服务器通常在 AI 助手启动时被拉起。如果感觉启动变慢可能是因为 Node.js 冷启动和npm install依赖解析。确保node_modules已安装好且服务器目录不在网络驱动器或速度很慢的存储上。多项目配置如果你在不同项目中使用不同的 AI 助手配置例如有的项目用 Cursor有的用 VS CodeContinue建议将buddy-mcp目录放在用户主目录如~/.config/下并在各项目的 MCP 配置中都指向这个同一绝对路径。这样可以避免重复下载和安装也方便统一管理buddy.json。版本管理server.mjs可能会更新。你可以定期手动curl下载新版覆盖旧文件。更工程化的做法是将~/.config/buddy-mcp/初始化为一个 Git 仓库添加远程指向项目的原始地址如果开源方便拉取更新。注意不要提交node_modules和buddy.json可将它们加入.gitignore。5.3 安全与隐私考量这是一个本地优先的项目所有数据buddy.json、服务器脚本都运行在你的本地机器上不与任何远程服务器通信除了最初从 terminalbuddies.com 下载文件。这是一个巨大的优点。buddy.json内容它包含你伙伴的名字和人格描述。这些信息会被注入到发送给 AI 服务提供商如 Anthropic, OpenAI的提示词中。请勿在其中放入任何真实的个人敏感信息。服务器脚本建议从官方源terminalbuddies.com下载脚本并可以简单浏览一下server.mjs的内容确认其功能如所述只进行文件读取和 MCP 通信。6. 跨界思考从趣味工具到生产力增强的启示Terminal Buddies 初看是一个小巧的趣味项目但它清晰地展示了一种强大的模式通过标准化协议MCP将外部上下文和工具能力无缝集成到 AI 工作流中。对于开发者而言它的启示远不止于一个会说话的 ASCII 宠物个性化 AI 交互的样板你可以依葫芦画瓢创建一个注入你个人编程偏好、常用代码片段、项目特定规则的 MCP 服务器让 AI 助手从一开始就更懂你。轻量级游戏化激励将枯燥的编码活动如解决 Bug、完成模块与伙伴的成长、心情挂钩能提供一种微妙的积极反馈。你可以扩展这个思路为代码审查、测试通过等事件设计奖励机制。探索 MCP 生态的起点这个项目是理解 MCP 实际运作的绝佳“Hello World”。通过拆解它你能快速掌握如何开发一个能提供“指令”和“工具”的服务器这是连接 AI 与任何本地或网络服务的基础。它可能不会直接让你的代码运行更快但它让开发者与工具之间的交互多了一层温度和趣味。在效率至上的工具链中这一点点“无用之用”的快乐有时恰恰是保持创造力和持久热情的重要火花。