ossian-mcp

ossian-mcp

适用于 Ossian 的 MCP 服务——向组织自己的文档提问，获取答案所依据的段落，并为 Agent 提供一种能在对话结束后继续保留的记忆。

Ossian 是服务端；本项目是将其接入 Agent 的适配器。你需要一个正在运行的 Ossian 实例供其连接——请参阅其 README，了解如何运行 docker compose up。

它能为 Agent 提供什么

工具受访问模式控制（参见默认安全）——服务默认以只读模式启动，仅开放四个读取工具，提升模式后才会开放其他工具。

工具	用途	所需模式
ask_documents	根据语料库回答并提供引用；无法回答时会明确说明	只读
list_namespaces	查看有哪些分区，以及各分区包含多少内容	只读
list_documents	查看有哪些内容可供回答，以及哪些内容仍在摄取中	只读
recall	检索当前相关内容，并按相关性、重要性和时效性排序	只读
add_document_from_url	将公开网页导入语料库	读写
remember	记录值得保留的偏好、事实或决定	读写
forget_session	删除某次对话的记忆（不可撤销）	管理员 + OSSIAN_ALLOW_FORGET

安装

npm install -g ossian-mcp

你需要一个正在运行的 Ossian 实例和一个 API 密钥。可从控制台（控制台 → API 密钥）创建密钥，或运行：

curl -X POST "$OSSIAN_URL/api/admin/api-keys" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"mcp","roles":["ossian-user"],"namespace":"handbooks"}'

请为密钥授予满足需求的最小权限范围。namespace 会将密钥限制在一个分区内，因此即使密钥泄露，也只能读取对应 Agent 所需的内容。

配置

{
  "mcpServers": {
    "ossian": {
      "command": "ossian-mcp",
      "env": {
        "OSSIAN_URL": "http://localhost:8081",
        "OSSIAN_API_KEY": "osk_...",
        "OSSIAN_AGENT_ID": "support-bot",
        "OSSIAN_MODE": "read-only"
      }
    }
  }
}

OSSIAN_AGENT_ID 用于区分不同 Agent 的记忆；两个 Agent 使用相同 ID 时会共享记忆，有时这是你想要的，但通常不是。

请参阅 docs/CLIENTS.md，查看 Claude Code / Cursor / Codex / VS Code / Windsurf 的配置示例；每个受支持的变量请参阅 .env.example。

默认安全

该服务在 Ossian API 密钥之上实施访问控制，进一步强化安全，弥补密钥自身角色和命名空间限制之外的不足。服务从环境变量读取策略（.env.example），并在 src/security.ts 中执行策略：

• OSSIAN_MODE — read-only（默认）→ read-write → admin。只有模式允许相应功能时才会注册工具。只读模式开放四个工具；摄取和记忆需要 read-write；删除记忆需要 admin。
• OSSIAN_ALLOW_FORGET — forget_session 会不可逆地删除记忆，因此除 admin 模式外，还必须启用此标志。
• OSSIAN_NAMESPACE_ALLOWLIST / OSSIAN_PROTECTED_NAMESPACES — 限制可操作的分区，并标记可读取但禁止向其中摄取内容的分区。
• OSSIAN_DRY_RUN — 验证并记录写入操作（摄取 / 记忆 / 删除），但不实际执行。
• OSSIAN_AUDIT_LOG — 每次受控操作都会在 stderr 中输出一条 JSON 审计日志（默认开启）。
• 交互式确认 — 如果客户端支持 MCP 交互式询问，forget_session 会提示用户批准后再删除会话记忆；不支持交互式询问的客户端则会使用 OSSIAN_ALLOW_FORGET 限制作为后备机制。

主要的控制措施仍然是 API 密钥：请创建满足需求的最小权限密钥。请参阅 SECURITY.md。

两件值得了解的事

“未找到”也是一种回答。 ask_documents 在语料库中没有内容可以支持回答时会拒绝回答，而且工具描述会告诉模型报告这一点，而不是转而使用通用知识。将编造的答案当作公司政策呈现，正是整个系统要防止的失败情形——不要在自己的提示词中掩盖这一点。

记忆不是语料库。 recall 会搜索告知 Agent 的内容；ask_documents 会搜索组织记录的内容。它们有意分属不同的存储：如果记忆作为引文出现在政策回答中，就会与政策本身无法区分。

开发

npm install
npm run build
OSSIAN_URL=http://localhost:8081 OSSIAN_API_KEY=osk_… node dist/index.js

它通过 stdio 使用 JSON-RPC，因此会一直等待数据帧。手动驱动它的方法如下：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

诊断信息会有意输出到 stderr——任何写入 stdout 的非协议数据帧都会破坏数据流，造成的故障看起来像是客户端无法解析，而不是服务端打印了日志行。

许可证

Apache-2.0