适合谁
- 希望代理回答所依赖的知识可检视、可版本控制、可移植的团队
- 需要本地优先、不依赖托管索引或云端刷新服务的工作流
- 需要明确来源引用与保守链接解析（缺失/歧义引用只告警不猜测）的场景
- 希望用确定性词法搜索、不引入嵌入服务或 LLM 密钥的部署
O
63FMRS · C
OKFy 是一个本地优先、只读的 MCP 服务器，把文档站点与 Markdown 文件夹转成可检查、可 Git 追踪的 OKF 知识包，让编码代理以确定性词法搜索、带来源引用的方式读取文档。它适合重视知识可见性与可移植性的团队；不适合需要向量搜索、细粒度标题切分或 Obsidian 高级语义的场景。
OKFy 是一个工具集，可将文档网站和 Markdown 文件夹转换为符合 Open Knowledge Format（OKF）v0.1 的知识包——即可检查、可被 Git 追踪的类型化、链接化 Markdown。它附带的本地 MCP 服务器让 Claude、Codex、Cursor 等代理搜索知识包、只读取相关概念、沿关系链接继续查找，并返回原始来源引用。检索路径为 search_concepts → read_concept → get_neighbors，确定性词法搜索，无需嵌入服务或 LLM API 密钥；网站源缓存于 ~/.okfy，可后台刷新。MCP 工具全部只读，通过 stdio 启动。
工具能力
bundle_summary
报告知识包或工作区的有效性、规模及来源新鲜度。
search_concepts
按查询、来源、类型或标签查找概念预览。
read_concept
读取概念正文、元数据、链接、反向链接及来源。
get_neighbors
遍历某个概念的外向链接与反向链接。
list_types
列出概念类型及其数量。
list_tags
列出标签及其数量。
安装接入
- 使用
npx -y okfy-ai init <name> <url> --client codex抓取文档站点到本地知识包，并打印 MCP 配置（该命令不会修改你的代理配置）。 - 将打印的配置粘贴到客户端：Codex 写入 ~/.codex/config.toml，Claude Code 使用
claude mcp add --transport stdio <name>-okf -- npx -y okfy-ai serve <name> --mcp --auto-refresh，Claude Desktop、Cursor 等使用 JSON 的 mcpServers 配置块。 - 本地 Markdown 可先用
npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs"生成知识包，再npx -y okfy-ai serve ./docs-okf --mcp提供服务。 - 需要用
--all时才把当前 OKFY_HOME 下所有已注册来源提供给代理。 - 若配置失败，运行
npx -y okfy-ai doctor <name> --client codex检查来源状态、知识包有效性、新鲜度、npx、生成的配置、MCP 工具可见性与 stdout 的 JSON-RPC 纯净度。
需要 Node.js 20+；无需全局安装。
claude_desktop_config.json
{
"mcpServers": {
"stripe-okf": {
"command": "npx",
"args": ["-y", "okfy-ai", "serve", "stripe", "--mcp", "--auto-refresh"]
}
}
}
选型与风险
不适合谁
- 需要向量/语义搜索的检索质量要求
- 需要按标题切分文档、或依赖 Canvas、Bases、PDF、图片、音视频、Dataview 字段等 Obsidian 高级语义的场景
- 需要把 GitHub 仓库 URL 直接导入（无专用导入器，需本地检出或文档目录）
- 需要写回知识源、或需要代理可调用的写工具的工作流
所需权限
- 读取本地知识包目录与 ~/.okfy 下的来源缓存和刷新状态
- 在启用刷新时对已注册的文档站点发起同源网络抓取（默认遵守 robots.txt）
- 以 stdio 子进程方式被 MCP 客户端启动；工具本身只读
风险与副作用
- 文档站点抓取的 HTML 清理质量因站点而异，可能影响检索结果
- preflight 会拒绝解析到私有网络的 DNS 目标，但抓取时的 DNS 未做 IP 固定，存在 DNS 重绑定的理论风险
- 刷新模式默认 stale-while-refresh，可能短暂提供非最新文档；可用 blocking 或 off 调整
- 唯一页面/文件映射为一个概念，不做标题级切分，长文档可能粒度较粗
- `--force` 会替换非空输出目录，除非提供显式危险覆盖，否则拒绝不安全输出目录
常见排障
- 运行 `npx -y okfy-ai doctor <name> --client codex` 检查来源状态、知识包有效性、新鲜度、npx、配置生成、MCP 工具可见性与 stdout 是否为纯 JSON-RPC
- 用 `npx -y okfy-ai validate <bundle>` 确认知识包有效；validate 会拒绝缺失 type 元数据与格式错误的保留文件
- 确认输出目录下存在 index.md 与 log.md 等保留文件，缺失或链接断开只会产生警告但影响索引
- `serve --mcp` 由 MCP 客户端作为子进程启动，不要在交互式终端直接运行
- 多来源检索有歧义时，在 search_concepts 或 read_concept 中显式传入 source 过滤或消歧
- 若需阻止服务时联网，使用 `--refresh-mode off`，手动 `okfy update` 仍可用
使用场景
让编码代理检索 Stripe、Clerk 等文档站点并给出带来源引用的回答
把项目内 Markdown 或 Obsidian 库导入为可检视的知识包供代理读取
在一个 MCP 服务器中同时提供多个文档来源，并按来源过滤有歧义的检索
通过本地静态 HTML Inspector 或 activate 输出与团队分享代理可读的文档快照
支持客户端
Claude Desktop完整支持
Claude Code完整支持
Codex完整支持
Cursor完整支持