内容
# okf-mcp
**适用于 [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog) 捆绑包的 MCP 服务器** — 暴露 [okf-ingest](https://github.com/travisjakel/okf-ingest) 的确定性消费动词，作为任何 MCP 客户端（Claude Code、Cursor、自定义代理）可以调用的工具。
现有的 OKF MCP 服务器向代理提供降档的 *文件*。而这个服务器提供**可查询的目录和概念图**：索引优先的上下文组装、影响/反向链接分析、SQL 查询 frontmatter、差异分析以及健康检查 — 所有这些都是确定性的 okf-ingest 代码，服务器中没有模型调用。
## 工具
| 工具 | 代理获取的内容 |
|---|---|
| `okf_list_bundles` | 服务器暴露的捆绑包 |
| `okf_search` | 标题/正文与术语匹配的概念 |
| `okf_get_concept` | 一个概念的 frontmatter + 正文 |
| `okf_context` | **旗舰工具** — index.md + 一个概念的最相关邻域，作为一个策划的 Markdown 块，排名基于作者链接图的精确个性化 PageRank（传递 `rank='bfs'` 以获取平面深度）— 或者传递 `query`（一个自由文本问题）而不是 `start` 以进行词汇种子多 PPR 检索 |
| `okf_related` | 与主题最相关的 k 个概念 — 精确 PPR，无需嵌入 |
| `okf_impact` | 入站/出站/传递链接 — “如果 X 更改，什么会损坏” |
| `okf_sql` | 只读 SELECT 查询 DuckDB 目录（`okf_concept`、`okf_link`、`okf_validation`） |
| `okf_diff` | 自服务器加载捆绑包以来磁盘上的更改 — 代理在两次查看之间的内存刷新 |
| `okf_refresh` | 在 `okf_diff` 显示更改后重新摄取目录捆绑包 |
| `okf_doctor` | 健康分数 + 每个规则的发现，在信任捆绑包之前 |
## 安装和运行
```bash
pip install okf-mcp # 依赖于 okf-ingest >= 0.9.0
# 一个或多个捆绑包：目录和/或 okf-ingest .duckdb 目录，
# 可选地命名（第一个是默认目标）
okf-mcp ~/my-bundle
okf-mcp wiki=~/wiki notes=~/vault snapshot=./kb.duckdb
```
在 Claude Code 中注册：
```bash
claude mcp add okf -- okf-mcp ~/my-bundle
```
或者在任何 MCP 客户端配置中：
```json
{ "mcpServers": { "okf": { "command": "okf-mcp", "args": ["wiki=/path/to/bundle"] } } }
```
## 设计笔记
- **只读。** 目录捆绑包被摄取到一次性内存中的 DuckDB 目录中；`.duckdb` 源代码只读；`okf_sql` 只接受 SELECT/WITH 查询。服务器永远不会写入您的捆绑包。
- **确定性。** 每个工具都是纯 okf-ingest 代码 — 相同的输入，相同的答案；代理看到的唯一不确定性是其自身的。
- **概念按名称解析。** `okf_get_concept` / `okf_context` / `okf_impact` 接受路径 *或* wikilink 样式的名称 — id、别名、标题或文件名干，比较字母数字（'agent memory architecture' 找到 `ops/agent_memory_architecture.md`）。模糊名称返回候选列表而不是猜测。
- **`[[wikilinks]]` 有效。** Vault 样式的捆绑包（Obsidian/Logseq/Foam）按 id / 别名 / 标题 / 干解析，与 okf-ingest 0.6.0+ 相同。
Apache-2.0. 配套项目：[okf-ingest](https://github.com/travisjakel/okf-ingest) （此项目包装的 R + Python 摄取工具）。
