MCP Server 集成：让 AI Agent 自动调用知识库

本文面向想让 Claude Code 等 AI 工具自动访问 ChatCrystal 知识库的开发者。预计阅读时间8 分钟MCP 协议是什么MCPModel Context Protocol是 Anthropic 提出的开放协议定义了 AI 模型与外部工具之间的通信标准。你可以把它理解为 AI 世界的 USB 接口——任何实现了 MCP 协议的工具都能被任何支持 MCP 的 AI 客户端调用。对开发者来说这意味着Claude Code 可以直接搜索你的知识库不需要你手动复制粘贴AI Agent 可以在对话开始时自动回忆历史经验避免重复踩坑任务完成后AI 可以把新学到的知识写回知识库形成闭环ChatCrystal 实现了 MCP Server暴露 7 个工具让 AI Agent 能读也能写。ChatCrystal 的 7 个 MCP 工具只读工具查询知识search_knowledge— 语义搜索在知识库中进行语义检索返回按相关度排序的笔记列表。参数类型说明querystring搜索查询文本limitnumber最大返回数量默认 10get_note— 获取笔记详情根据 ID 获取完整笔记内容包括标题、摘要、关键结论、代码片段和标签。参数类型说明idnumber笔记 IDlist_notes— 浏览笔记列表分页浏览知识库中的笔记支持按标签和关键词筛选。参数类型说明tagstring按标签筛选searchstring按标题/摘要关键词筛选pagenumber页码默认 1。每页固定 20 条不可调整get_relations— 获取关联笔记查看某条笔记的关联笔记包括关联类型和置信度分数。参数类型说明noteIdnumber笔记 ID记忆工具读写闭环recall_for_task— 任务回忆根据当前任务上下文自动回忆相关的历史经验。采用「项目优先 全局补充」策略先从当前项目搜索最相关的记忆再从全局知识库补充跨项目的通用经验。参数类型说明modestringtask默认常规任务回忆或debug调试模式更关注错误签名和历史修复方案task.goalstring当前任务目标task.task_kindstring任务类型debug / implement / refactor / migration / config / investigate / optimizationtask.project_keystring项目标识可选task.project_dirstring项目目录可选task.cwdstring当前工作目录可选task.branchstring当前分支名可选task.files_touchedstring[]涉及的文件可选task.error_signaturesstring[]错误特征可选task.related_filesstring[]关联文件可选task.source_agentstring来源工具codex / claude / copilot / cursor / trae / unknown可选options.project_limitnumber项目级结果上限默认 5options.global_limitnumber全局结果上限默认 3options.include_relationsboolean是否返回关联笔记默认 truevalidate_task_memory— 预检验证在写入前预检记忆质量不产生任何副作用。接受的参数与write_task_memory完全相同返回是否接受、原因和警告信息。推荐在write_task_memory之前先调用此工具避免产生无效写入。write_task_memory— 写回知识将任务中学到的经验写回知识库。有严格的质量门槛必须包含具体标题、实质性摘要、有意义的结论和可复用的经验教训。一次性的环境检查、版本报告、模糊的泛泛而谈会被拒绝。参数类型说明modestringauto自动写回或manual手动写回。auto模式必须提供source_run_keysource_run_keystring会话唯一标识用于去重modeauto时必填scopestringproject项目级或global全局。scopeglobal仅在modemanual时可用task.goalstring任务目标task.task_kindstring任务类型memory.titlestring标题可选系统可自动生成memory.summarystring经验摘要必填memory.outcome_typestring结果类型pitfall / fix / pattern / decisionmemory.root_causestring根因分析可选memory.resolutionstring解决方案可选memory.pitfallsstring[]坑点列表可选memory.reusable_patternsstring[]可复用模式可选memory.decisionsstring[]决策列表可选memory.key_conclusionsstring[]关键结论可选memory.code_snippetsarray代码片段含 language、code、description可选memory.files_touchedstring[]涉及的文件可选memory.error_signaturesstring[]错误特征可选memory.tagsstring[]标签可选配置方法前置条件已安装 ChatCrystal CLInpm install -g chatcrystalChatCrystal 服务正在运行crystal serveClaude Code 配置编辑 Claude Code 的settings.json通常位于~/.claude/settings.json{mcpServers:{chatcrystal:{command:crystal,args:[mcp]}}}配置完成后重启 Claude CodeMCP Server 会自动启动。自定义服务地址如果 ChatCrystal 服务不在默认的http://localhost:3721可以指定地址{mcpServers:{chatcrystal:{command:crystal,args:[mcp,--base-url,http://192.168.1.100:3721]}}}使用场景场景 1Claude Code 自动搜索知识库配置好 MCP 后你在 Claude Code 里不需要做任何额外操作。直接用自然语言提问Claude 会自动判断是否需要搜索知识库 我之前处理 CORS 问题的方案是什么Claude 会自动调用search_knowledge工具从知识库里找到相关笔记然后引用笔记内容回答你。整个过程无需手动干预。 Fastify 和 Express 的性能对比数据我之前整理过帮我找一下Claude 会搜索「Fastify Express 性能对比」找到之前的架构讨论笔记并展示关键数据。场景 2新对话自动回忆历史经验这是recall_for_task的核心场景。当 Claude Code 开始一个新任务时它可以通过这个工具自动回忆之前处理类似任务的经验。例如当你让 Claude Code 调试一个数据库连接超时的问题它会调用recall_for_task传入任务描述和错误特征ChatCrystal 先从当前项目搜索相关记忆项目优先再从全局知识库补充跨项目经验全局补充Claude 拿到历史经验后直接应用到当前任务你不需要告诉 Claude「我之前遇到过类似问题」它会自己查。场景 3任务完成后写回知识当 Claude Code 完成一个有价值的任务后可以通过write_task_memory把经验写回知识库踩过的坑pitfall某个配置项的默认值会导致问题修复方案fix具体的解决步骤和代码设计模式pattern可复用的代码结构或架构方案技术决策decision为什么选 A 不选 B以及权衡过程写入前 Claude 会先调用validate_task_memory预检质量确保不是一次性噪音。质量门槛要求标题具体不泛泛摘要有实质内容结论可操作、可复用是真正的经验教训不是进度日志低质量的写回请求会被记录为 receipt收据不会污染知识库。stdio vs HTTP为什么用 stdioChatCrystal MCP Server 使用stdio标准输入/输出传输而不是 HTTP。这意味着MCP Server 作为 Claude Code 的子进程启动通过 stdin/stdout 通信不占用网络端口生命周期由 Claude Code 管理退出 Claude Code 时自动清理为什么不用 HTTP安全性stdio 不暴露网络接口不存在未授权访问的风险简洁性不需要管理端口、处理 CORS、配置防火墙可靠性进程级通信没有网络超时、连接断开等问题符合惯例Claude Code 的 MCP 生态默认使用 stdio架构示意Claude Code └─ crystal mcp (子进程, stdio) └─ CrystalClient (HTTP) └─ ChatCrystal Server (localhost:3721) └─ SQLite vectraMCP Server 本身不做数据存储它只是一个桥接层通过 HTTP 调用 ChatCrystal 的 REST API。真正的知识库在 ChatCrystal Server 里。验证 MCP 连接方法一检查 Claude Code 工具列表在 Claude Code 中输入/tools查看是否出现了chatcrystal前缀的工具chatcrystal:search_knowledge chatcrystal:get_note chatcrystal:list_notes chatcrystal:get_relations chatcrystal:recall_for_task chatcrystal:validate_task_memory chatcrystal:write_task_memory如果看到这 7 个工具说明 MCP 连接成功。方法二直接测试在 Claude Code 里问一个你知识库里有的问题 搜索一下知识库里关于 Fastify 的笔记如果 Claude 能返回结果说明整个链路MCP Server - ChatCrystal Server - 数据库 - 向量检索都通了。方法三检查服务状态crystal status确认 ChatCrystal Server 正在运行且数据库中有笔记数据。常见问题Claude Code 看不到 MCP 工具确认settings.json配置正确JSON 格式无误确认crystal命令在 PATH 中which crystal重启 Claude CodeMCP 工具调用报错确认 ChatCrystal Server 正在运行crystal status检查服务端口是否正确默认 3721如果用了自定义地址确认--base-url参数正确搜索结果为空确认已导入对话crystal import确认已生成笔记crystal notes list确认 Embedding 模型配置正确crystal config testwrite_task_memory 被拒绝这是正常的质量控制。被拒绝的内容仍然会作为 receipt 记录不会丢失。要提高通过率确保写回的内容包含具体的、可复用的经验而不是泛泛的描述。下一步用知识库找回 3 天前的调试方案 — 语义搜索实战LLM 和 Embedding 不能混用 — 配置正确的模型零基础搭建 — 从零开始搭建 ChatCrystal项目地址github.com/ZengLiangYi/ChatCrystal