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

夜雪闻竹2026-05-23 10:36

本文面向：想让 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 会自动判断是否需要搜索知识库：

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

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

复制代码 
> Fastify 和 Express 的性能对比数据我之前整理过，帮我找一下

Claude 会搜索「Fastify Express 性能对比」，找到之前的架构讨论笔记并展示关键数据。

场景 2：新对话自动回忆历史经验

这是 recall_for_task 的核心场景。当 Claude Code 开始一个新任务时，它可以通过这个工具自动回忆之前处理类似任务的经验。

例如，当你让 Claude Code 调试一个数据库连接超时的问题，它会：

  1. 调用 recall_for_task，传入任务描述和错误特征
  2. ChatCrystal 先从当前项目搜索相关记忆（项目优先）
  3. 再从全局知识库补充跨项目经验（全局补充）
  4. 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？

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

架构示意：

复制代码 
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 前缀的工具：

复制代码 
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 -> 数据库 -> 向量检索）都通了。

方法三：检查服务状态

bash 复制代码 
crystal status

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

常见问题

Claude Code 看不到 MCP 工具

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

MCP 工具调用报错

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

搜索结果为空

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

write_task_memory 被拒绝

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

下一步

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

相关推荐
半拉老头1 小时前
用360安全浏览器插件图片助手批量下载图片
windows
2501_938140072 小时前
做内容很省心，2026好用AI笔记，支持抖音小红书视频无水印保存
人工智能
sell-cloud4 小时前
Prompt Engineering要凉了？Fable 5.5能“猜“意图，但银行正在封杀AI Agent——企业AI的真正护城河是什么
人工智能·prompt
Navicat中国6 小时前
Navicat 18 内置 AI 助手让数据库开发从繁琐操作迈向智能协作
大数据·人工智能·数据库开发
4SAPI6 小时前
多模型请求路由怎么设计？成本、速度和能力如何平衡
人工智能·python·gateway·php
魔乐社区6 小时前
翼芯・智算测试与适配优化专区，让国产算力“选得准、跑得通、用得好“
人工智能·开源·大模型
XCDoris8 小时前
郴州logo设计机构
大数据·人工智能·python
Goboy9 小时前
一个人带三个Agent,我用全新TRAE从0到1搭了个资讯周刊站
人工智能·trae
俊哥V9 小时前
每日 AI 研究简报 · 2026-10-19
人工智能·ai
AI_AGENT_DEV_AI9 小时前
AI英语教培智能体的开发
人工智能
热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05几个好用的ip纯净度检测网站06「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会07苹果iPA游戏软件资源下载网站08蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接09Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）10昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战