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

本文面向：想让 Claude Code 等 AI 工具自动访问 ChatCrystal 知识库的开发者。预计阅读时间：8 分钟

MCP 协议是什么

MCP（Model 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 --- 语义搜索

在知识库中进行语义检索，返回按相关度排序的笔记列表。

参数	类型	说明
`query`	string	搜索查询文本
`limit`	number	最大返回数量，默认 10

get_note --- 获取笔记详情

根据 ID 获取完整笔记内容，包括标题、摘要、关键结论、代码片段和标签。

参数	类型	说明
`id`	number	笔记 ID

list_notes --- 浏览笔记列表

分页浏览知识库中的笔记，支持按标签和关键词筛选。

参数	类型	说明
`tag`	string	按标签筛选
`search`	string	按标题/摘要关键词筛选
`page`	number	页码，默认 1。每页固定 20 条，不可调整

get_relations --- 获取关联笔记

查看某条笔记的关联笔记，包括关联类型和置信度分数。

参数	类型	说明
`noteId`	number	笔记 ID

记忆工具（读写闭环）

recall_for_task --- 任务回忆

根据当前任务上下文，自动回忆相关的历史经验。采用「项目优先 + 全局补充」策略：先从当前项目搜索最相关的记忆，再从全局知识库补充跨项目的通用经验。

参数	类型	说明
`mode`	string	`task`（默认，常规任务回忆）或 `debug`（调试模式，更关注错误签名和历史修复方案）
`task.goal`	string	当前任务目标
`task.task_kind`	string	任务类型：debug / implement / refactor / migration / config / investigate / optimization
`task.project_key`	string	项目标识（可选）
`task.project_dir`	string	项目目录（可选）
`task.cwd`	string	当前工作目录（可选）
`task.branch`	string	当前分支名（可选）
`task.files_touched`	string[]	涉及的文件（可选）
`task.error_signatures`	string[]	错误特征（可选）
`task.related_files`	string[]	关联文件（可选）
`task.source_agent`	string	来源工具：codex / claude / copilot / cursor / trae / unknown（可选）
`options.project_limit`	number	项目级结果上限，默认 5
`options.global_limit`	number	全局结果上限，默认 3
`options.include_relations`	boolean	是否返回关联笔记，默认 true

validate_task_memory --- 预检验证

在写入前预检记忆质量，不产生任何副作用。接受的参数与 write_task_memory 完全相同，返回是否接受、原因和警告信息。推荐在 write_task_memory 之前先调用此工具，避免产生无效写入。

write_task_memory --- 写回知识

将任务中学到的经验写回知识库。有严格的质量门槛：必须包含具体标题、实质性摘要、有意义的结论和可复用的经验教训。一次性的环境检查、版本报告、模糊的泛泛而谈会被拒绝。

参数	类型	说明
`mode`	string	`auto`（自动写回）或 `manual`（手动写回）。`auto` 模式必须提供 `source_run_key`
`source_run_key`	string	会话唯一标识，用于去重（`mode=auto` 时必填）
`scope`	string	`project`（项目级）或 `global`（全局）。`scope=global` 仅在 `mode=manual` 时可用
`task.goal`	string	任务目标
`task.task_kind`	string	任务类型
`memory.title`	string	标题（可选，系统可自动生成）
`memory.summary`	string	经验摘要（必填）
`memory.outcome_type`	string	结果类型：pitfall / fix / pattern / decision
`memory.root_cause`	string	根因分析（可选）
`memory.resolution`	string	解决方案（可选）
`memory.pitfalls`	string[]	坑点列表（可选）
`memory.reusable_patterns`	string[]	可复用模式（可选）
`memory.decisions`	string[]	决策列表（可选）
`memory.key_conclusions`	string[]	关键结论（可选）
`memory.code_snippets`	array	代码片段（含 language、code、description）（可选）
`memory.files_touched`	string[]	涉及的文件（可选）
`memory.error_signatures`	string[]	错误特征（可选）
`memory.tags`	string[]	标签（可选）

配置方法

前置条件

已安装 ChatCrystal CLI：npm install -g chatcrystal
ChatCrystal 服务正在运行：crystal serve

Claude Code 配置

编辑 Claude Code 的 settings.json（通常位于 ~/.claude/settings.json）：

json 复制代码

{
  "mcpServers": {
    "chatcrystal": {
      "command": "crystal",
      "args": ["mcp"]
    }
  }
}

配置完成后重启 Claude Code，MCP Server 会自动启动。

自定义服务地址

如果 ChatCrystal 服务不在默认的 http://localhost:3721，可以指定地址：

json 复制代码

{
  "mcpServers": {
    "chatcrystal": {
      "command": "crystal",
      "args": ["mcp", "--base-url", "http://192.168.1.100:3721"]
    }
  }
}

使用场景

场景 1：Claude Code 自动搜索知识库

配置好 MCP 后，你在 Claude Code 里不需要做任何额外操作。直接用自然语言提问，Claude 会自动判断是否需要搜索知识库：

markdown 复制代码

> 我之前处理 CORS 问题的方案是什么？

Claude 会自动调用 search_knowledge 工具，从知识库里找到相关笔记，然后引用笔记内容回答你。整个过程无需手动干预。

markdown 复制代码

> 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：为什么用 stdio

ChatCrystal MCP Server 使用 stdio（标准输入/输出）传输，而不是 HTTP。

这意味着：

MCP Server 作为 Claude Code 的子进程启动
通过 stdin/stdout 通信，不占用网络端口
生命周期由 Claude Code 管理，退出 Claude Code 时自动清理

为什么不用 HTTP？

安全性：stdio 不暴露网络接口，不存在未授权访问的风险
简洁性：不需要管理端口、处理 CORS、配置防火墙
可靠性：进程级通信，没有网络超时、连接断开等问题
符合惯例：Claude Code 的 MCP 生态默认使用 stdio

架构示意：

scss 复制代码

Claude Code
  └─ crystal mcp (子进程, stdio)
       └─ CrystalClient (HTTP)
            └─ ChatCrystal Server (localhost:3721)
                 └─ SQLite + vectra

MCP Server 本身不做数据存储，它只是一个桥接层，通过 HTTP 调用 ChatCrystal 的 REST API。真正的知识库在 ChatCrystal Server 里。

验证 MCP 连接

方法一：检查 Claude Code 工具列表

在 Claude Code 中输入 /tools，查看是否出现了 chatcrystal 前缀的工具：

makefile 复制代码

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 里问一个你知识库里有的问题：

markdown 复制代码

> 搜索一下知识库里关于 Fastify 的笔记

如果 Claude 能返回结果，说明整个链路（MCP Server -> ChatCrystal Server -> 数据库 -> 向量检索）都通了。

方法三：检查服务状态

bash 复制代码

crystal status

确认 ChatCrystal Server 正在运行，且数据库中有笔记数据。

常见问题

Claude Code 看不到 MCP 工具

确认 settings.json 配置正确，JSON 格式无误
确认 crystal 命令在 PATH 中：which crystal
重启 Claude Code

MCP 工具调用报错

确认 ChatCrystal Server 正在运行：crystal status
检查服务端口是否正确（默认 3721）
如果用了自定义地址，确认 --base-url 参数正确

搜索结果为空

确认已导入对话：crystal import
确认已生成笔记：crystal notes list
确认 Embedding 模型配置正确：crystal config test

write_task_memory 被拒绝

这是正常的质量控制。被拒绝的内容仍然会作为 receipt 记录，不会丢失。要提高通过率，确保写回的内容包含具体的、可复用的经验，而不是泛泛的描述。

下一步

用知识库找回 3 天前的调试方案 --- 语义搜索实战
LLM 和 Embedding 不能混用 --- 配置正确的模型
零基础搭建 --- 从零开始搭建 ChatCrystal

项目地址：github.com/ZengLiangYi...