Moss CLI 与 MCP Server 指南:让 Claude、Cursor 等 AI 工具直接搜索你的知识库

原创2026-10-28 05:38:061,660 阅读

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 上:

这套"预载索引 → 暴露搜索工具 → AI 按需调用"的架构,同样是语音 Agent 场景的地基,下图就是基于 Moss 构建的 LiveKit 语音 Agent 前端界面(源码见 apps/livekit-moss-vercel/):

基于Moss语义搜索构建的语音Agent交互界面

另外,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 应用。

登录后查看全文
moss