用途
ossian-mcp 是 Ossian 的 MCP 服务器适配器。Ossian 本身作为服务器运行，本项目负责把 Ossian 放到 AI 智能体面前，让智能体能够：向组织自有文档提问并拿到答案所依据的段落，以及拥有一个超出单次对话生命周期的持久记忆。使用前需要有一个正在运行的 Ossian 实例，并参考其 README 通过 docker compose up 启动。
主要能力
- 文档问答：ask_documents 在语料库中检索，返回答案及其来源段落。当语料库不支持某个回答时，工具返回拒绝，工具描述要求模型如实报告，而不是回退到通用知识。
- 智能体记忆：recall 搜索智能体被告知的内容，记忆按相关性、重要性和时间新近度排序，并在对话结束后继续存在。
- 记忆与语料库是两个独立的存储：recall 搜索的是智能体被告知的内容，ask_documents 搜索的是组织写下的内容，刻意分开，避免记忆作为引用出现在政策类回答中而与政策本身混淆。
- 工具按访问模式注册：只读模式暴露四个读工具；ingest 和 remember 需要读写模式；forget 需要管理员模式。
使用方式
- 需要运行中的 Ossian 和 API 密钥。可在控制台（Console → API keys）签发密钥。
- 建议给密钥最小作用域：namespace 可将密钥限制在某个切片内。
- OSSIAN_AGENT_ID 用于区分不同智能体的记忆；共享同一 id 的两个智能体会共享记忆。
- 客户端配置片段见 docs/CLIENTS.md，覆盖 Claude Code / Cursor / Codex / VS Code / Windsurf；所有支持的环境变量见 .env.example。
- 服务器通过 stdio 使用 JSON-RPC 通信，等待协议帧。诊断信息输出到 stderr，stdout 只允许协议帧。
安全与默认限制
服务器在 Ossian API 密钥之上额外实施访问模型，策略从环境变量读取并在 src/security.ts 中强制执行：
- OSSIAN_MODE：read-only（默认）→ read-write → admin。只有模式允许其能力的工具才会被注册。
- OSSIAN_ALLOW_FORGET：forget_session 会不可逆地擦除记忆，除管理员模式外还需要此标志。
- OSSIAN_NAMESPACE_ALLOWLIST / OSSIAN_PROTECTED_NAMESPACES：限制可操作的切片，并标记只读不可写入的切片。
- OSSIAN_DRY_RUN：校验并记录写入（ingest / remember / forget）而不实际执行。
- OSSIAN_AUDIT_LOG：每次受保护操作输出一行 JSON 审计日志到 stderr（默认开启）。
- 交互式确认：当客户端支持 MCP elicitation 时，forget_session 会在擦除会话记忆前提示人工批准；不支持该功能的客户端回退到 OSSIAN_ALLOW_FORGET 门控。
主要控制手段仍是 API 密钥：签发能满足需求的最小密钥。详见 SECURITY.md。
适用场景
适用于需要让智能体基于组织内部文档进行有引用回答，并需要跨对话保持记忆的场景。由于默认只读且支持命名空间限制、审计日志与干运行，也适合对写入操作谨慎、需要先验证再放开权限的环境。
限制与注意
- 需要先有运行中的 Ossian 服务与有效 API 密钥，否则无法使用。
- 默认只读，写入与擦除需要显式提升模式；擦除记忆还需额外标志或人工确认。
- 缺失事实暂未提供：具体平台支持范围、收费与价格、性能指标等未在资料中说明。
