Snipara

snipara-mcp

snipara-mcp 是一个轻量级 stdio MCP 连接器，用于连接 Snipara Project Brain。

Snipara 是面向 AI 编码 Agent 的项目大脑。

当 MCP 客户端需要一个本地 stdio 进程来连接 Snipara 托管的项目智能 API 时，可使用它。Snipara 能在 Claude Code、Cursor、Codex 和其他 MCP 客户端编辑代码前，为它们提供所需的决策、当前工作、代码影响、依据和交接信息。如果客户端原生支持可流式传输的 HTTP MCP，建议优先使用托管端点，并跳过本地进程。

什么是 Snipara？

Snipara 是面向 AI 辅助软件开发的共享项目智能层。

它为 Claude Code、Cursor、Codex、OpenAI Agents 和其他兼容 MCP 的客户端提供项目上下文，让上下文能够跨会话、用户、工具和模型切换持续保留。

Agent 仍使用自己的大模型。Snipara 为其提供恰当的项目上下文：有源代码依据的文档、经过审核的记忆、共享指导、工作流连续性和代码图结构。从类别上看，它是一个 AI 编码 Agent 上下文、记忆与连续性平台。

为什么选择 MCP？

MCP 正逐渐成为 Agent 工具的标准适配层。snipara-mcp 通过该层提供 Snipara，无需让开发者受限于特定 IDE、模型或编排框架。

集成应当尽可能简单：

uvx snipara-mcp

其影响却更大：Agent 可以获取持久的项目上下文，而不必每次会话都从零开始。

它能解锁什么

需求	Snipara MCP 工具组
向项目文档提问并获得有来源依据的答案	snipara_context_query、snipara_get_chunk
回忆持久的决策和经验	snipara_recall
查看团队收件箱	snipara_inbox_review_queue、snipara_inbox_review_plan、snipara_inbox_review_apply
任务完成后保存可复用的记忆	snipara_remember_if_novel、snipara_end_of_task_commit
复用团队标准和共享指导	snipara_shared_context
检查代码的结构关系	snipara_code_callers、snipara_code_imports、snipara_code_neighbors
规划高风险代码变更	在计划容量范围内使用 snipara_code_symbol_card、snipara_code_impact

公共 MCP 客户端必须使用 snipara_* 名称。rlm_* 兼容别名已于 2026-08-16 从分发契约中移除， 仅保留为内部处理程序标识符。此契约清理计划在下一次软件包发布时分阶段推出；使用旧名称的客户端必须在升级前迁移。

stdio 服务向外公布的默认 Agent 契约与托管 MCP 端点相同，且精简。仅当客户端需要 直接发现所有专用兼容工具时，才设置 SNIPARA_TOOL_PROFILE=full；隐藏工具仍可通过 明确指定名称调用，也可通过 snipara_help 发现。

默认发现界面包含 13 个功能明确的工具： snipara_context_query、snipara_ask、snipara_search、snipara_read、 snipara_stats、snipara_help、snipara_get_chunk、snipara_recall、 snipara_remember_if_novel、snipara_end_of_task_commit、 snipara_inbox_review_queue、snipara_inbox_review_plan 和 snipara_inbox_review_apply。

最小安全变更审查（2.8.30）

打包的 snipara_context_query 和 snipara_code_impact 契约现已支持 minimum_change_mode="review"。启用后，回答包和影响分析响应会附带非阻塞、证据优先的审查结果，涵盖现有功能、标准库／原生选项、已安装依赖、最小安全差异以及验证范围的保留情况。在项目证据足以校准更强的强制措施前，该策略仅作建议，且默认关闭。

调用方可提供带有 runtime、manifest、lockfile、git_diff 或 test_runner 等具名来源的、有界 minimum_change_evidence。 未经验证的 confirmed 声明仍会显示为 asserted；只有通过版本校验且指纹匹配的适配器回执才使用 confirmed。已验证的适配器包括用于直接已安装依赖的 lockfile_manifest，以及用于连贯本地最小安全差异检查的 git_diff。 响应还会提供非阻塞的保留保护项，涵盖验证、错误、身份验证／安全性、无障碍、公共契约和测试。

语义规则契约（2.8.27）

生成的 snipara_code_symbol_card 和 snipara_code_impact 架构现已将有界的 semantic_rules 项目覆盖项转发给托管服务。术语是字面字符串，而非可执行正则表达式。

MCP 传输安全基线（2.8.26）

连接器现要求使用 MCP Python SDK 1.28.1 或更高版本。此版本纳入了上游针对 已验证主体的会话隔离、实验性任务所有权以及 WebSocket Host／Origin 验证的修复。

可配置的代码影响遍历（2.8.25）

打包后的 snipara_code_impact 契约现已公开 depth（1-6）、 direction（in、out 或 both）和可选的 edge_kinds。这使连接器契约与托管影响链以及 Companion 的混合式本地/托管遍历控制保持一致。

无需凭据即可发现工具并使用精简契约（2.8.24）

MCP 客户端和目录检查器现在可以在配置凭据前完成 initialize 和 tools/list。在完成身份验证并选择项目前，所有实际工具调用仍会安全失败。默认的 tools/list 响应会公开与托管 Snipara 相同的 13 个核心工具，而 SNIPARA_TOOL_PROFILE=full 则保留对所有专业兼容工具的直接发现能力。核心工具现已包含完整的选择指南、行为注释和嵌套参数文档，便于 Agent 安全使用。

面向 Agent 的工具契约（2.8.23）

连接器现会保留托管权威数据源中的详细工具说明和 MCP 行为注释。摘要、协调、状态、记忆和代码图谱工具会说明其前置条件、访问规则、副作用、幂等性、替代方案、参数、输出和常见故障模式，帮助 Agent 安全地选择工具。原生输出架构仍暂缓启用，直到传输方式与结构化结果格式一并升级。

统一的对话式收件箱审核（2.8.22）

人工团队管理员可以列出多项目仪表板收件箱中显示的相同记忆候选项和 ProjectDecision 草稿，创建有证据支持的批准/拒绝/需要人工审核建议，并原子化地应用明确授权的快照。在记录权限审计前，服务会重新验证人工团队管理员身份、项目所有权、当前候选项状态和不可变的项目快照。真实凭据仍可用于拒绝操作，但会从 MCP 输出中脱敏。此前仅针对 ProjectDecision 的工具仍作为专业兼容工具提供。

对话式决策审核（2.8.21）

Agent 可以列出待处理的 ProjectDecision 草稿，提出有证据支持的批准/拒绝/需要人工审核建议，并应用明确授权且绑定快照的计划。应用计划需要人工项目管理员授权；如果草稿在规划后发生变化，操作会安全失败；不支持对当前所有项目进行通配批准。

结构化 Why 捕获任务提交（2.8.20）

snipara_end_of_task_commit 现在接受包含 decision、rationale、alternatives、constraints 和 observed_outcome 的原子 why 块。结构化候选项会保持待审核状态，直到人工审核；未知参数会安全失败，而不会被静默忽略。

检索结果控制（2.8.19）

stdio 连接器会转发托管服务端对 context_query 和 recall 的有限检索结果控制：可选的任务关联、影子或启用重排请求，以及严格的上下文归因时间窗口。托管服务端仍具有最终决定权，因此客户端请求可以降低或关闭已配置的模式，但不能提升该模式。

架构

flowchart LR
    Agents["Claude Code, Cursor, Codex, ChatGPT, OpenAI agents"] --> Stdio["snipara-mcp stdio process"]
    Stdio --> Hosted["Hosted Snipara MCP API"]
    Hosted --> Context["Context engine"]
    Hosted --> Memory["Project memory"]
    Hosted --> Graph["Code graph"]
    Context --> AgentLLM["Agent's own LLM"]
    Memory --> AgentLLM
    Graph --> AgentLLM

使用托管 HTTP 还是 Stdio？

当 MCP 客户端支持流式 HTTP 时，请使用托管 HTTP 端点：

{
  "mcpServers": {
    "snipara": {
      "type": "http",
      "url": "https://api.snipara.com/mcp/your-project-id-or-slug",
      "headers": {
        "Authorization": "Bearer snp-your-key"
      }
    }
  }
}

当客户端需要本地 stdio 命令时，请使用 snipara-mcp：

{
  "mcpServers": {
    "snipara": {
      "command": "uvx",
      "args": ["snipara-mcp"],
      "env": {
        "SNIPARA_API_KEY": "snp-your-key",
        "SNIPARA_PROJECT_ID": "your-project-id-or-slug"
      }
    }
  }
}

选择规则：

• 现代客户端优先使用 HTTP MCP
• 仅支持 stdio 的客户端或本地兼容场景使用 snipara-mcp
• 如需跨客户端和模板进行引导式设置，请使用 create-snipara

安装

无需本地安装：

uvx snipara-mcp

Python 包：

pip install snipara-mcp

集成 RLM Runtime 辅助工具：

pip install "snipara-mcp[rlm]"

快速入门

通过浏览器登录：

pip install snipara-mcp
snipara login

初始化项目：

snipara init

初始化程序会检测常见项目文件、写入 MCP 配置，并可在你完成身份验证后上传本地项目文档。

实用选项：

snipara init --slug my-project
snipara init --dry-run
snipara init --no-upload
snipara init --skip-test

Claude Code

claude mcp add snipara uvx snipara-mcp

然后在 shell 中导出凭据：

export SNIPARA_API_KEY="snp-your-key"
export SNIPARA_PROJECT_ID="your-project-id-or-slug"

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "snipara": {
      "command": "uvx",
      "args": ["snipara-mcp"],
      "env": {
        "SNIPARA_API_KEY": "snp-your-key",
        "SNIPARA_PROJECT_ID": "your-project-id-or-slug"
      }
    }
  }
}

环境

变量	必需	说明
SNIPARA_API_KEY	是，除非使用 snipara login	Snipara API 密钥
SNIPARA_PROJECT_ID	是，除非使用 SNIPARA_PROJECT_SLUG	项目标识符
SNIPARA_PROJECT_SLUG	是，除非使用 SNIPARA_PROJECT_ID	项目 slug
SNIPARA_API_URL	否	默认为 https://api.snipara.com
SNIPARA_TOOL_PROFILE	否	默认值为 core；full 会公开专业工具架构

snipara login 创建的 OAuth 令牌存储在 ~/.snipara/tokens.json 中。 如果设置了项目 ID 或 slug，连接器会选择匹配的令牌，不会悄悄回退到其他项目。

你将获得什么

该连接器提供与托管后端相同的精简默认 MCP 契约。打包的完整兼容接口由服务端真实来源生成，可通过 SNIPARA_TOOL_PROFILE=full 使用。

常见工具组：

• 检索：snipara_context_query、snipara_search、snipara_get_chunk、 snipara_load_document
• 持久记忆：snipara_recall、snipara_remember、 snipara_memory_compact
• 了解所有者信息的引导：snipara_session_memories、 snipara_owner_profile_get、snipara_owner_profile_update
• 共享上下文：snipara_shared_context、集合和模板工具
• 文档上传：snipara_upload_document、snipara_sync_documents
• 项目设置：客户端、项目和业务上下文工作区工具
• 运维：snipara_settings、snipara_index_health、snipara_reindex
• 代码图谱：代码索引可用时使用的 snipara_code_* 工具
• 协调：启用时提供的 swarm、分层任务和状态工具

工具的可用性可能因计划、托管部署和项目索引状态而异。

CLI 命令

命令	说明
snipara login	浏览器登录和令牌设置
snipara init	在当前项目中初始化 Snipara
snipara logout	清除已存储的令牌
snipara status	显示身份验证和项目状态
snipara-mcp	运行 MCP stdio 服务

仍支持 snipara-init、snipara-mcp-login、 snipara-mcp-logout 和 snipara-mcp-status 等旧别名。

与其他仓库的关系

仓库	作用
alopez3006/snipara-mcp	当前生成的公开连接器镜像
Snipara/snipara-companion	本地工作流、影响分析、验证和交接 CLI
Snipara/snipara-memory	开放记忆原语和架构

snipara-mcp 有意保持轻量。它应该易于安装、易于审查，运行起来也不繁琐。繁重的工作仍由 Snipara 的托管上下文和记忆引擎承担。

开发

pip install -e ".[dev]"
pytest
ruff check .

生成的工具契约的真实来源位于 Snipara 服务端。后端工具发生变化时，请在发布此软件包之前重新生成打包的契约。

许可证

MIT。参见 LICENSE。

带有界查询计划的概念研究（2.8.39）

snipara_context_query 接受由 Agent 编写的最多四个可选 retrieval_queries。请用源语言描述具体机制、功能、限制和反面证据。在 query 中保留原始问题，并保留命名实体。托管服务会在一个严格的 max_tokens 预算内合并排名后的来源，包括 Answer Packs 和分块引用。维度是待验证的假设，而非事实；未经支持的主张仍属未知。服务不会运行自己的大模型来生成计划。省略此可选字段时，现有调用仍兼容。