Moss CLI 与 MCP Server 指南:让 Claude、Cursor 等 AI 工具直接搜索你的知识库
Moss CLI 与 MCP Server 指南:让 Claude、Cursor 等 AI 工具直接搜索你的知识库
Moss 是一个面向生产级 AI 系统的毫秒级语义搜索(Semantic Search)运行时——无需向量数据库,一次查询 10ms 内返回结果。本文带你用它的两大内置能力:Moss CLI 与 Moss MCP Server,让 Claude、Cursor、Windsurf 等 AI 工具直接搜索你私有的知识库、FAQ 和产品文档,全程无需搭建 RAG 框架。
为什么你的 AI 工具需要一个 Moss 知识库 💡
用 AI 编程助手或对话 Agent 时,最常见的尴尬是:它不懂你的内部文档、业务规则和产品手册。传统的解法是搭一套 RAG 流水线——向量数据库、Embedding 服务、检索框架……组件一多,新手就很难入手。
Moss 的做法是把检索内嵌进你的进程:
- 无网络往返:索引加载后查询完全在本地内存完成,P50 延迟仅 3.1ms
- 内置 Embedding 模型(
moss-minilm),不需要额外配置模型 API - 混合搜索:语义 + 关键词一次查询搞定,还支持元数据过滤
官方基准测试(10 万文档、750 次查询)中,Moss 平均 3.3ms,而 Pinecone 为 485.8ms、Qdrant 为 596.5ms、ChromaDB 为 358.0ms。脚本可以在 benchmarks/run_all.py 中自行复现。
对于和人类对话的 Agent(语音客服、Copilot 等),几毫秒和几百毫秒的差异,就是"流畅"和"卡顿"的区别。
认识两把武器:moss-cli 与 MCP Server
Moss 官方提供了两种"不写代码就用搜索"的方式,详见 ROADMAP.md:
| 工具 | 定位 | 适合场景 |
|---|---|---|
| moss-cli | 终端命令行工具 | 管理索引、跑查询、验证数据,无需写代码 |
MCP Server(@moss-tools/mcp-server) |
Model Context Protocol 服务 | 让 Claude、Cursor、Windsurf 等 MCP 兼容的 AI 工具调用搜索 |
一句话理解:CLI 给你用,MCP Server 给 AI 用。
三步接入:把 Moss MCP Server 连上 Claude / Cursor 🚀
第 1 步:准备凭据
在 Moss 平台注册后,你会拿到 MOSS_PROJECT_ID 和 MOSS_PROJECT_KEY,后续所有操作(CLI、SDK、MCP)都靠这两个环境变量认证。
第 2 步:建一个知识索引
文档的最小结构是 {"id": "...", "text": "..."}。仓库中的 apps/agora-moss/create_index.py 展示了一个典型流程:读取 apps/agora-moss/moss_docs.json 样例文档,一次性创建索引并上传。你也可以参考 examples/python/load_and_query_sample.py 用几行 Python 完成同样的事。
第 3 步:在 MCP 客户端注册服务
在 Claude、Cursor 等工具的 MCP 配置(mcpServers)中加入:
{
"moss": {
"command": "npx",
"args": ["-y", "@moss-tools/mcp-server"],
"env": {
"MOSS_PROJECT_ID": "<你的项目 ID>",
"MOSS_PROJECT_KEY": "<你的项目 Key>"
}
}
}
这段配置与官方 Zo computer 技能安装器 packages/zo-computer/zo-skill/install.sh 中自动写入的 MCP 服务完全一致。配置完成后,AI 工具就能直接调用 Moss 暴露的搜索工具。
常用操作速查:索引管理与语义搜索命令 🔍
MCP Server 和 CLI 提供的核心操作是同一套,完整的命令清单可以参考 packages/zo-computer/zo-skill/scripts/moss.sh:
| 操作 | 说明 | 典型调用 |
|---|---|---|
list-indexes |
列出全部索引 | 连接成功后的第一个验证命令 |
create-index <name> <docs-json> |
创建索引并写入初始文档 | 建库一步到位 |
add-docs <name> <docs-json> |
追加文档 | 增量更新知识库 |
load-index <name> |
把索引预载到内存 | 搜索前必做,之后查询进入 <10ms 区间 |
search <name> <query> [top_k] |
语义搜索 | 核心能力 |
get-docs / delete-docs / delete-index |
文档与索引的增删查 | 日常维护 |
💡 关键习惯:对任何索引首次搜索前先执行
load-index。索引在内存里,搜索才真正"快"。
接入后,你可以在 Cursor 的对话框里直接问"查一下我们的退款政策",AI 会自动调用 MCP 工具拿到知识库原文,而不是凭空编造答案。
仓库中的真实案例:MCP Server 如何落地 🛠
想看"生产级"的写法,仓库里有一个完整的 FastMCP 示例——apps/agora-moss/ 把 Moss 搜索包装成 search_knowledge_base 工具,通过 streamable-HTTP 挂载到 Agora 语音 Agent 上:
- 服务入口:apps/agora-moss/server.py,用
uvicorn server:app即可启动 - 核心适配器:packages/agora-moss/src/agora_moss/search.py 中定义了
search_knowledge_base(query)工具,服务启动时会先在 lifespan 中预载索引,索引没加载完不接查询——这个细节值得抄进你自己的 MCP Server
这套"预载索引 → 暴露搜索工具 → AI 按需调用"的架构,同样是语音 Agent 场景的地基,下图就是基于 Moss 构建的 LiveKit 语音 Agent 前端界面(源码见 apps/livekit-moss-vercel/):
另外,packages/zo-computer/zo-skill/README.md 演示了另一种玩法:一条命令把 Moss 搜索装成 AI 平台的"技能",让 Agent 在新对话开始时自动列出索引、预载并主动检索,把知识库上下文织进每一次回答。
最佳实践:让搜索又快又准 ✅
- 凭据走环境变量:
MOSS_PROJECT_ID、MOSS_PROJECT_KEY通过.env或 MCP 的env字段注入,不要硬编码 - 先 load 再 search:所有"快"都来自内存索引,跳过预载等于放弃 <10ms
- 混合搜索调优:
top_k控制返回条数,alpha调节语义与关键词的比重(见 packages/agora-moss/src/agora_moss/search.py),专有名词多的知识库可以适当提高关键词权重 - 文档结构保持简单:
id + text就够用,元数据可用于后续过滤($eq、$in等操作符) - 增量维护:FAQ 更新用
add-docs追加即可,不必重建整个索引
写在最后
Moss 的哲学是把"检索"从沉重的基建变成一行配置:CLI 让你三分钟验证想法,MCP Server 让 AI 工具开箱即用地搜索你的知识。配合 sdks/ 下的 Python、TypeScript SDK,你可以先从"给 Claude 配一个搜索工具"起步,再逐步演进到完整的 Agent 应用。
