内容
# snipara-mcp
[](https://pypi.org/project/snipara-mcp/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/alopez3006/snipara-mcp/actions/workflows/ci.yml)
`snipara-mcp` 是用于 Snipara 项目大脑的轻量级 stdio MCP 连接器。
**Snipara 是 AI 编码代理的项目大脑。**
当 MCP 客户端需要与 Snipara 的托管项目智能 API 进行通信的本地 stdio 进程时，请使用它。 Snipara 为 Claude Code、Cursor、Codex 和其他 MCP 客户端提供决策、主动工作、代码影响、证明和交接所需的信息。如果您的客户端直接支持流式 HTTP MCP，请优先使用托管端点并跳过本地进程。
## 什么是 Snipara？
Snipara 是用于 AI 辅助软件工作的共享项目智能层。
它为 Claude Code、Cursor、Codex、OpenAI 代理和其他 MCP 兼容的客户端提供项目上下文，这些上下文贯穿会话、用户、工具和模型切换。
您的代理仍使用其自己的 LLM。 Snipara 为其提供正确的项目上下文：源代码支持的文档、审查的内存、共享的指导、工作流连续性和代码图结构。 在类别术语中，它是一个 AI 编码代理上下文、内存和连续性平台。
## 为什么使用 MCP？
MCP 正在成为代理工具的标准适配器层。 `snipara-mcp` 通过该层使 Snipara 可用，而无需强制开发人员进入特定的 IDE、模型或编排框架。
集成应该感觉很小：
```bash
uvx snipara-mcp
```
影响较大：代理可以检索持久的项目上下文，而不是每个会话都从头开始。
## 它解锁了什么
| 需要 | 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_*` 别名，以与较旧的客户端和目录记录向后兼容。
stdio 服务器提供与托管 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.27）
生成的 `snipara_code_symbol_card` 和 `snipara_code_impact` 模式现在将有界的 `semantic_rules` 项目覆盖转发到托管服务。术语是字面字符串，而不是可执行的正则表达式。
### MCP 传输安全底线（2.8.26）
连接器现在需要 MCP Python SDK 1.28.1 或更高版本。这包含了认证主体会话隔离、实验性任务所有权和 WebSocket 主机/源验证的上游修复程序。
### 可配置的代码影响遍历（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` 保留了所有专业兼容性工具的直接发现。 核心工具现在包括完整的选择指导、行为注释和嵌套参数文档，以便代理安全使用。
### 代理可读工具合约（2.8.23）
连接器现在保留了来自托管源代码的详细工具描述和 MCP 行为注释。 摘要、协调、状态、内存和代码图工具解释了它们的先决条件、访问规则、副作用、幂等性、替代方案、参数、输出和常见故障模式，以便代理可以安全地选择它们。 本机输出模式在传输和结构化结果格式升级之前保持延迟。
### 统一对话收件箱审查（2.8.22）
人类团队管理员可以列出与多项目仪表板收件箱显示的相同的内存候选项和 `ProjectDecision` 草稿，创建基于证据的批准/拒绝/需要人工建议，并原子化应用显式授权的快照。 服务在记录权限审计之前重新验证人类团队管理员身份、项目所有权、当前候选项状态和不可变项目快照。 实际凭证仍然可用于拒绝，但从 MCP 输出中删除了它们。
### 会话决策审查（2.8.21）
代理可以列出待处理的 `ProjectDecision` 草稿，提出基于证据的批准/拒绝/需要人工建议，并应用显式授权的快照绑定计划。 应用需要人类项目管理员，如果草稿在规划后更改，则失败关闭； 没有实时通配符批准。
### 结构化 Why 捕获任务提交（2.8.20）
`snipara_end_of_task_commit` 现在接受一个原子的 `why` 块，包含 `decision`、
`rationale`、`alternatives`、`constraints` 和 `observed_outcome`。 结构化候选项在人工审查之前保持待定，未知参数失败关闭，而不是被静默忽略。
### 检索结果控制（2.8.19）
stdio 连接器转发托管服务器的有界检索结果控制，用于 `context_query` 和 `recall`：可选任务相关性、影子或启用重新排序请求，以及严格的上下文属性窗口。 托管服务器仍然是权威的，因此客户端请求可以降低或禁用配置的模式，但不能升级它。
## 架构
```mermaid
flowchart LR
代理["Claude Code, Cursor, Codex, ChatGPT, OpenAI 代理"] --> Stdio["snipara-mcp stdio 进程"]
Stdio --> 托管["托管 Snipara MCP API"]
托管 --> 上下文["上下文引擎"]
托管 --> 内存["项目内存"]
托管 --> 图["代码图"]
上下文 --> 代理LLM["代理自己的LLM"]
内存 --> 代理LLM
图 --> 代理LLM
```
## 托管 HTTP 或 Stdio？
当您的 MCP 客户端支持流式 HTTP 时，请使用托管 HTTP 端点：
```json
{
"mcpServers": {
"snipara": {
"type": "http",
"url": "https://api.snipara.com/mcp/your-project-id-or-slug",
"headers": {
"Authorization": "Bearer snp-your-key"
}
}
}
}
```
当您的客户端期望本地 stdio 命令时，请使用 `snipara-mcp`：
```json
{
"mcpServers": {
"snipara": {
"command": "uvx",
"args": ["snipara-mcp"],
"env": {
"SNIPARA_API_KEY": "snp-your-key",
"SNIPARA_PROJECT_ID": "your-project-id-or-slug"
}
}
}
}
```
决策规则：
- 现代客户端首选 HTTP MCP
- `snipara-mcp` 用于仅 stdio 的客户端或本地兼容性
- `create-snipara` 用于跨客户端和模板的引导设置
## 安装
无需本地安装：
```bash
uvx snipara-mcp
```
Python 包：
```bash
pip install snipara-mcp
```
使用 RLM Runtime 助手集成：
```bash
pip install "snipara-mcp[rlm]"
```
## 快速入门
通过浏览器登录：
```bash
pip install snipara-mcp
snipara login
```
初始化项目：
```bash
snipara init
```
初始化程序检测常见的项目文件，写入 MCP 配置，并可以在您身份验证时上传本地项目文档。
有用选项：
```bash
snipara init --slug my-project
snipara init --dry-run
snipara init --no-upload
snipara init --skip-test
```
## Claude Code
```bash
claude mcp add snipara uvx snipara-mcp
```
然后在您的 shell 中导出凭证：
```bash
export SNIPARA_API_KEY="snp-your-key"
export SNIPARA_PROJECT_ID="your-project-id-or-slug"
```
## Cursor
添加到 `~/.cursor/mcp.json`：
```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_*` 工具（当代码索引可用时）
- 协调：群组、层次任务和状态工具（启用时）
工具可用性可能会因计划、托管部署和项目索引状态而异。
## 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 的托管上下文和内存引擎中。
## 开发
```bash
pip install -e ".[dev]"
pytest
ruff check .
```
生成的工具合约的源代码位于 Snipara 服务器中。当后端工具更改时，请在发布此软件包之前重新生成打包的合约。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
