内容
# mindgraph-mcp
[](https://www.npmjs.com/package/mindgraph-mcp)
[](LICENSE)
MindGraph 模型上下文协议（MCP）服务器 - 将您持久化、结构化的知识图谱连接到 Claude Desktop、Claude Code 和任何兼容 MCP 的客户端。
## 安装
最快的安装方式是交互式设置：
```bash
npx mindgraph-mcp init
```
该过程将引导您完成以下步骤：
1. 通过浏览器登录（或粘贴现有的 API 密钥）。
2. 选择您的客户端 - Claude Desktop、Claude Code 或两者。
3. 服务器将自动配置；重启您的客户端以激活。
您还没有 MindGraph 账户吗？请先在 [mindgraph.cloud](https://mindgraph.cloud) 注册。
### 手动安装
```bash
# Claude Desktop
npx mindgraph-mcp install --api-key mg_your_key_here
# Claude Code
npx mindgraph-mcp install-code --api-key mg_your_key_here
```
或者，您也可以手动将以下内容添加到 Claude Desktop 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS）：
```json
{
"mcpServers": {
"mindgraph": {
"command": "npx",
"args": ["-y", "mindgraph-mcp@latest"],
"env": {
"MINDGRAPH_API_KEY": "mg_your_key_here"
}
}
}
}
```
## 您将获得
**8 种工具**，涵盖整个知识图谱工作流程：
| 工具 | 用途 |
|------|---------|
| `mindgraph_capture` | 实体、观察、来源、片段、概念、日志条目 |
| `mindgraph_reason` | 主张与证据、开放问题、假设、理论、异常 |
| `mindgraph_commit` | 目标、项目、决策、选项、里程碑和已记录的决策上下文链接 |
| `mindgraph_plan` | 计划、任务、程序、治理策略、风险评估、执行 |
| `mindgraph_retrieve` | 上下文检索，带有边界图扩展、搜索、最小成本遍历、文档索引 |
| `mindgraph_ingest` | 块/文档/会话摄入，带有 LLM 驱动的提取 |
| `mindgraph_synthesize` | 项目范围的跨文档合成 - 挖掘信号、启动文章生成作业 |
| `mindgraph_ontology` | 操作本体（第 7 层）- 类型化领域对象、自然语言查询，带有出处、提取提案审查（批准/拒绝）、对象链接 |
此外，**动态生成的读取工具**：当租户的活动模式声明对象类型时，服务器将为每种类型渲染 `search_<objs>` / `get_<obj>` / `summarize_<obj>` 工具（来自云的 `GET /v1/ontology/tools` 清单）在会话开始时。`summarize_<obj>` 返回对象 - 无论是从连接的 SQL 数据库映射还是从文档中提取 - 以及其认知上下文（主张、风险、决策、证据）。
**7 个提示模板**，适用于常见的工作流程：
`graph-summary`、`active-goals`、`open-questions`、`review-contradictions`、`knowledge-about`、`daily-briefing`、`capture-conversation`。
**资源**（静态 + 动态 URI）：
- `mindgraph://stats`、`mindgraph://goals`、`mindgraph://questions`、`mindgraph://contradictions`、`mindgraph://decisions`
- `mindgraph://node/{uid}` - 具有所有出边和入边的节点
- `mindgraph://search/{query}` - BM25 搜索结果
- `mindgraph://layer/{layer}` - 认知层中的所有节点（现实、认识、意图、行动、记忆、代理）
## 命令行界面
```text
mindgraph-mcp 启动 MCP 服务器（stdio 传输）
mindgraph-mcp init 交互式设置
mindgraph-mcp install 安装到 Claude Desktop 配置
mindgraph-mcp install-code 安装到 Claude Code
mindgraph-mcp uninstall 从 Claude Desktop 配置中删除
mindgraph-mcp uninstall-code 从 Claude Code 中删除
mindgraph-mcp status 显示安装状态
```
选项：`--api-key <key>`、`--base-url <url>`、`--help`。
## 环境
| 变量 | 默认值 | 用途 |
|----------|---------|---------|
| `MINDGRAPH_API_KEY` | *(必填)* | 您的 MindGraph API 密钥 (`mg_…`) |
| `MINDGRAPH_BASE_URL` | `https://api.mindgraph.cloud` | 自托管部署的覆盖 |
| `MINDGRAPH_AGENT_ID` | `mcp` | 写入的每个节点/边的出处，用于多个代理之间的溯源 |
| `MINDGRAPH_ORG_ID` | *(未设置)* | 将操作固定到特定组织，当密钥可以访问多个组织时 |
## 在 Claude 中的使用
安装完成后，自然地向 Claude 询问您的知识图谱：
> “我上周捕获了关于气候政策的内容是什么？”
> “总结我的活跃目标和开放决策。”
> “摄入此 PDF 并提取主要主张。”
> “查找多个项目文档中提到的实体，然后启动合成。”
服务器自动在每次写入时注入 `agent_id: "mcp"`，这样您就可以知道哪些节点来自您的 MCP 会话。
## 架构
该 MCP 服务器是 [mindgraph](https://www.npmjs.com/package/mindgraph) TypeScript SDK 的薄封装。它将认知层抽象（现实、认识、意图、行动、记忆、代理）公开为综合工具，而不是每个端点的工具，这使得模型可以进行高质量的工具选择。
搜索策略是 **关键词优先**：`mindgraph_retrieve` 默认 `action: "context"`，它从 BM25/混合召回中播种边界最便宜的图扩展。只有当关键词失败时，才升级到 `semantic` 或 `hybrid`。当需要直接检索时，设置 `graph_expansion_limit: 0`。
## 开发
```bash
git clone https://github.com/shuruheel/mindgraph-mcp
cd mindgraph-mcp
npm install
npm run build # 使用 tsup 构建（CJS + .d.ts）
npm run lint # tsc --noEmit
npm run dev # tsup --watch
```
## 许可证
MIT
