OKFy MCP Server

社区

把文档转换为面向 AI 代理的 Open Knowledge Format 知识包，并通过本地只读 MCP 提供检索。

分类: 开发工具第 74 / 438
Stars: ★ 74 热门
传输方式: stdio（本地进程）
运行环境: Node.js 20+
凭据: 无需凭据
许可证: MIT
最近提交: 2 个月前
工具数: 6

63FMRS · C

OKFy 是一个本地优先、只读的 MCP 服务器，把文档站点与 Markdown 文件夹转成可检查、可 Git 追踪的 OKF 知识包，让编码代理以确定性词法搜索、带来源引用的方式读取文档。它适合重视知识可见性与可移植性的团队；不适合需要向量搜索、细粒度标题切分或 Obsidian 高级语义的场景。

最强项 · 文档质量 15/20 最弱项 · 可靠性 11/20

可靠性

11/20

安全与权限

13/20

维护活跃度

11/20

文档质量

15/20

安装易用性

13/20

查看各项评分依据

可靠性 11/20: 静态审查仅见 README 所述内容：MCP 为 stdio 只读服务器，声明六个只读工具（bundle_summary、search_concepts、read_concept、get_neighbors、list_types、list_tags），并称有 CI 徽章（ci.yml）。服务器清单未缓存，无法核对工具声明与真实实现的映射，也没有直接读到已提交的测试用例覆盖关键路径，因此依据静态校准上限不超过 12。README 对错误有较明确说明（doctor 检查 JSON-RPC 干净 stdout、validate 区分错误与警告、刷新模式 off/stale-while-refresh/blocking），可诊断性描述尚可；但缺少可核验的执行证据，存在隐藏假设，故取 11。
安全与权限 13/20: 未触及红线：无凭据窃取、无隐蔽外传、无默认破坏性操作。README 声明爬取遵守 robots.txt、默认同源、限制页数/深度/响应体/并发、默认拒绝私网 URL 字面与跳转、HTML/Markdown 按文本处理不执行脚本、MCP 工具只读、--force 需显式危险覆盖。这些属于合理的最小权限与数据边界设计。扣分点：均为自述证据，无第三方或代码级验证；README 自承 fetch 阶段 DNS 未做 IP 固定（preflight 之后仍存在 DNS 重绑定窗口）；--auto-refresh 使 MCP 服务端会主动联网抓取，用户需自行理解该副作用；配置示例需用户自行粘贴、无内置确认流程。故取 13。
维护活跃度 11/20: 证据显示有 CI 工作流徽章、MIT 许可证、npm 包 okfy-ai 0.3.5、扫描器显示 71 stars、1 个 open issue、未归档，说明项目在维护中。但缺少可见的发布节奏、变更日志、提交历史、依赖更新策略与安全响应渠道说明，治理与版本化信息不足。依据静态校准，无执行证据不额外加分，取 11。
文档质量 15/20: README 覆盖度较好：快速开始、多客户端接入示例（Codex TOML、Claude Code 命令、通用 JSON）、六个工具用途表、bundle 格式示例、命令清单、安全默认值、Current Limits（不支持按标题切分、搜索为确定性词法而非向量、stdio 优先等），并显式披露无云账户/托管索引/LLM key。Obsidian 导入的警告码与诊断清单也写明。扣分点：无 manifest 佐证工具参数细节（如 search_concepts 的 source/limit 只给了一个 JSON 片段）、缺少成本与限流的量化说明、故障排查仅有 doctor 与少量提示、部分文档指向仓库内其他文件而无法在本次静态审查中核验。故取 15。
安装易用性 13/20: 安装路径清晰且对用户友好：无需全局安装，用 npx -y okfy-ai init <name> <url> --client codex 一条命令完成抓取并打印 MCP 配置，随后按客户端粘贴 Codex TOML、Claude Code 命令或通用 JSON 即可；要求 Node.js 20+ 明确；提供 doctor 做校验。但扣分点明显：注册->打印配置->手动编辑客户端文件仍是多步且需人工介入，README 明确说明 init 不会自动改配置；多源 workspace、bundle 路径直连、refresh 模式等需理解额外概念；无缓存 manifest 与真实启动验证，依据静态校准上限不超过 15。取 13。

静态评测 · 未实际运行收录于 2026-09-10

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件访问网络

适合谁

希望代理回答所依赖的知识可检视、可版本控制、可移植的团队
需要本地优先、不依赖托管索引或云端刷新服务的工作流
需要明确来源引用与保守链接解析（缺失/歧义引用只告警不猜测）的场景
希望用确定性词法搜索、不引入嵌入服务或 LLM 密钥的部署

不适合谁

需要向量/语义搜索的检索质量要求
需要按标题切分文档、或依赖 Canvas、Bases、PDF、图片、音视频、Dataview 字段等 Obsidian 高级语义的场景
需要把 GitHub 仓库 URL 直接导入（无专用导入器，需本地检出或文档目录）
需要写回知识源、或需要代理可调用的写工具的工作流

所需权限

读取本地知识包目录与 ~/.okfy 下的来源缓存和刷新状态
在启用刷新时对已注册的文档站点发起同源网络抓取（默认遵守 robots.txt）
以 stdio 子进程方式被 MCP 客户端启动；工具本身只读

风险与副作用

文档站点抓取的 HTML 清理质量因站点而异，可能影响检索结果
preflight 会拒绝解析到私有网络的 DNS 目标，但抓取时的 DNS 未做 IP 固定，存在 DNS 重绑定的理论风险
刷新模式默认 stale-while-refresh，可能短暂提供非最新文档；可用 blocking 或 off 调整
唯一页面/文件映射为一个概念，不做标题级切分，长文档可能粒度较粗
`--force` 会替换非空输出目录，除非提供显式危险覆盖，否则拒绝不安全输出目录

安装接入

准备工作

运行环境：Node.js 20+

使用 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"]
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "stripe-okf": {
      "command": "npx",
      "args": [
        "-y",
        "okfy-ai",
        "serve",
        "stripe",
        "--mcp",
        "--auto-refresh"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add stripe-okf -- npx -y okfy-ai serve stripe --mcp --auto-refresh

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在客户端工具列表中应出现 bundle_summary、search_concepts、read_concept、get_neighbors、list_types、list_tags 这些只读工具；调用 bundle_summary 返回来源有效性、大小与新鲜度即说明连接成功。

常见排障

运行 `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` 仍可用

试试这样问

连接成功后，可以直接对 AI 助手这样说：

使用 Stripe 文档，解释 Checkout Sessions 的最小后端流程，阅读相关概念，必要时顺着关联文档，并附上所有用到的来源引用。
总结当前工作区中各文档源的有效性、大小和新鲜度。
在 Stripe 文档源中搜索 "checkout sessions"，按来源过滤，最多返回 5 条结果。
列出这个知识包里的所有概念类型和标签及其数量。

工具能力 6

bundle_summary 只读

报告知识包或工作区的有效性、规模及来源新鲜度。

search_concepts 只读

按查询、来源、类型或标签查找概念预览。

read_concept 只读

读取概念正文、元数据、链接、反向链接及来源。

get_neighbors 只读

遍历某个概念的外向链接与反向链接。

list_types 只读

列出概念类型及其数量。

list_tags 只读

列出标签及其数量。

使用场景

让编码代理检索 Stripe、Clerk 等文档站点并给出带来源引用的回答

把项目内 Markdown 或 Obsidian 库导入为可检视的知识包供代理读取

在一个 MCP 服务器中同时提供多个文档来源，并按来源过滤有歧义的检索

通过本地静态 HTML Inspector 或 activate 输出与团队分享代理可读的文档快照

支持客户端

Claude Desktop

Claude Code

Codex

Cursor

依据项目文档列出，未经本站实测。

详细介绍

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 启动。