内容
<!-- mcp-name: ai.sovantica/engrava -->
# Engrava MCP
[](https://github.com/sovantica/engrava-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/engrava-mcp/)
[](https://pypi.org/project/engrava-mcp/)
[](https://opensource.org/licenses/MIT)
**模型上下文协议（MCP）服务器，为 Engrava 提供服务** — 通过标准输入/输出将代理内存数据库暴露给任何MCP客户端（Claude Desktop、Claude Code、Cursor、Windsurf、VS Code等）。
`engrava-mcp` 是一个独立的可运行包，它使用 Engrava 的公共API。它是运行 Engrava 作为内存服务器的唯一方式；`engrava` 库本身不包含 MCP 代码。
```bash
uvx engrava-mcp # 运行服务器（无需安装步骤）
# 或
pip install engrava-mcp
engrava-mcp # 由您的MCP客户端通过标准输入/输出启动
```
安装 `engrava-mcp` 会间接安装 `engrava`，因此您也可以在同一个环境中使用 `import engrava` 库。
## 兼容性
`engrava-mcp` 跟随 Engrava 的版本： **`engrava-mcp X.Y.z` 针对 `engrava X.Y`**，并且需要 `engrava >=X.Y,<X.(Y+1)`。这是一个单向版本镜像，为了可读性 — **不是** 锁步：Engrava 版本有其自己的节奏，而 `engrava-mcp` 的补丁版本发布是独立的。
| engrava-mcp | 与 engrava 兼容 |
|---|---|
| `0.5.x` | `>=0.5,<0.6` |
依赖范围是真实的来源。正常的安装会自动解析一个兼容的 `engrava`；如果您自己锁定 `engrava`，请将其保持在该范围内。如果对于较新的 `engrava`（例如新的 `engrava 0.6`）尚不存在匹配的 `engrava-mcp`，则该配对 **尚未验证/支持** — 而不是损坏；请在匹配的 `engrava-mcp` 发布之前继续使用支持的配对。
## 我需要哪个包？
| 目标 | 安装 |
|---|---|
| 在您的代码中使用 Engrava Python API（在您的代码中使用内存数据库） | `pip install engrava` |
| 将 Engrava 作为内存服务器运行给 MCP 客户端 | `uvx engrava-mcp`（或 `pip install engrava-mcp`） |
没有第三个选项。
## 从 `engrava[mcp]` 迁移
服务器曾经作为 `engrava[mcp]` 额外功能和 `engrava` 中的 `engrava-mcp` 命令包含在 Engrava 中。从 Engrava 0.5.0 开始，它改用此存储库。
| 之前 | 之后 |
|---|---|
| `pip install "engrava[mcp]"` | `pip install engrava-mcp`（或 `uvx engrava-mcp`） |
| `engrava-mcp`（由 engrava 安装） | `engrava-mcp`（由此包安装） |
| 客户端 `mcp.json`: `"command": "engrava-mcp"` | 客户端 `mcp.json`: `"command": "uvx", "args": ["engrava-mcp"]` |
- **注意：** `pip install "engrava[mcp]"` 对于 Engrava 0.5 **不会失败** — pip 忽略现在未知的额外功能并悄悄安装裸 `engrava`，因此它看起来像服务器已安装，但实际上并未安装。请改为安装 `engrava-mcp`。
- 更新任何固定的需求字符串（`engrava[mcp]>=...`）以依赖于 `engrava-mcp`，而不仅仅是重新安装。
- **您的存储配置保持不变** — 相同的 `engrava.yaml` / 环境变量完全按照以前的方式工作（参见[配置](#配置)）。
## 配置
服务器通过环境变量解析其存储，按照优先级顺序：
| 变量 | 含义 |
|---|---|
| `ENGRAVA_MCP_CONFIG` | `.engrava.yaml` 的路径。具有完整的配置 — 嵌入提供者、向量后端、日志、TTL。 **推荐。** |
| `ENGRAVA_DB_PATH` | 裸 SQLite 数据库文件的路径。零配置快速启动；没有配置嵌入提供者，因此语义（向量）搜索是惰性的 — 仍然支持全文搜索、图、MindQL 和审计轨迹。 |
| `ENGRAVA_MCP_READ_ONLY` | 当设置为 `1` / `true` / `yes` 时，不会注册写入工具，因此服务器公开一个只读界面。 |
**推荐：** 给 MCP 服务器提供与您的应用程序相同的 `engrava.yaml`。`yaml` 是声明嵌入提供者（及其模型/密钥）的地方，服务器需要在搜索时嵌入一个新查询以进行语义搜索。如果只设置了 `ENGRAVA_DB_PATH`，服务器会记录一个启动警告，指出语义搜索是惰性的，并指向 `ENGRAVA_MCP_CONFIG`。
### 示例 `engrava.yaml`
```yaml
db_path: ./memory.db
embeddings:
provider: openai # 或：ollama, sentence-transformer, huggingface
model: text-embedding-3-small
api_key: ${OPENAI_API_KEY}
```
## 客户端设置
通过标准输入/输出将您的 MCP 客户端指向服务器。例如，一个典型的 `mcp.json` 条目：
```json
{
"mcpServers": {
"engrava": {
"command": "uvx",
"args": ["engrava-mcp"],
"env": {
"ENGRAVA_MCP_CONFIG": "/absolute/path/to/engrava.yaml"
}
}
}
}
```
使用 `ENGRAVA_DB_PATH` 代替 `ENGRAVA_MCP_CONFIG` 进行零配置快速启动，并添加 `"ENGRAVA_MCP_READ_ONLY": "1"` 进行应用程序写入/代理读取部署。
### 在没有 uvx 的情况下运行
```bash
engrava-mcp # 控制台脚本
python -m engrava_mcp # 模块运行
python -m engrava_mcp.server # 模块运行（直接运行服务器模块）
```
## 可选提供者
默认安装支持向量后端和基于 HTTP 的嵌入提供者（OpenAI / Ollama），一旦在 `yaml` 中配置。较重的提供者是可选的额外功能，与 Engrava 自己的额外功能镜像：
```bash
uvx --from "engrava-mcp[local]" engrava-mcp # 句子转换器（本地模型）
uvx --from "engrava-mcp[hf]" engrava-mcp # HuggingFace 推理 API
uvx --from "engrava-mcp[openai]" engrava-mcp # OpenAI 兼容的嵌入依赖项
uvx --from "engrava-mcp[ollama]" engrava-mcp # Ollama 嵌入依赖项
```
## 界面
- **工具（11）：** `get_thought`、`search_memory`、`search_keywords`、`list_memory`、`query_memory`、`memory_stats`（读取）；`store_thought`、`update_thought`、`link_thoughts`、`delete_thought`、`delete_edge`（写入，由 `ENGRAVA_MCP_READ_ONLY` 控制）。
- **资源（3）：** `engrava://thought/{thought_id}`、`engrava://stats`、`engrava://recent`。
- **提示（3）：** `summarize_recent_memory`、`find_related`、`reflect_on_topic`。
`query_memory` 仅接受 MindQL `FIND` 查询；原始 SQL 和所有其他命令都被拒绝。
## 开发
```bash
pip install -e ".[dev]"
ruff check src/ tests/
ruff format --check src/ tests/
mypy --strict src/
pytest --cov --cov-fail-under=90
```
## 许可证
MIT
