OKFy MCP Server

Community

Turn docs into Open Knowledge Format bundles served to AI agents over a local read-only MCP server.

★ 71 Stars Category · Dev Tools Popular

63FMRS · C

OKFy is a local-first, read-only MCP server that turns documentation sites and Markdown folders into inspectable, Git-diffable OKF bundles, letting coding agents read source-linked documentation through deterministic lexical search. It suits teams that value visible, portable knowledge, but not use cases requiring vector search, fine-grained heading splits, or advanced Obsidian semantics.

Reliability

11/20

Security and permissions

13/20

Maintenance

11/20

Documentation

15/20

Setup experience

13/20

Read the FMRS scoring method →

OKFy converts documentation websites and Markdown folders into Open Knowledge Format (OKF) v0.1-conformant bundles: typed, linked Markdown that can be inspected and diffed in Git. Its local MCP server lets Claude, Codex, Cursor, and other agents search the bundle, read only relevant concepts, follow relationships with get_neighbors, and return original source references. The retrieval path is search_concepts → read_concept → get_neighbors with deterministic lexical search; no embedding service or LLM API key is required. Website sources are cached under ~/.okfy and can refresh in the background. MCP tools are read-only and served over stdio.

Tools

bundle_summary

Report bundle or workspace validity, size, and source freshness.

search_concepts

Find concept previews by query, source, type, or tags.

read_concept

Read a concept body, metadata, links, backlinks, and source.

get_neighbors

Traverse outbound links and backlinks around a concept.

list_types

List concept types and counts.

list_tags

List tags and counts.

Setup

Generate a local bundle and agent setup with npx -y okfy-ai init <name> <url> --client codex; it crawls the source, prints the MCP configuration, and does not edit your agent config.
Paste the printed configuration into your client: Codex uses ~/.codex/config.toml, Claude Code uses claude mcp add --transport stdio <name>-okf -- npx -y okfy-ai serve <name> --mcp --auto-refresh, and Claude Desktop, Cursor, and other MCP clients use the JSON mcpServers block.
For local Markdown, first build a bundle with npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs", then serve it with npx -y okfy-ai serve ./docs-okf --mcp.
Use --all only when every registered source in the current OKFY_HOME belongs in the agent context.
If setup fails, run npx -y okfy-ai doctor <name> --client codex to check source state, bundle validity, freshness, npx, generated configuration, MCP tool visibility, and JSON-RPC-clean stdout.

Requires Node.js 20+; no global install is needed.

claude_desktop_config.json

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

Generate and validate client config

Fit and risk

Best for

Teams that need the knowledge behind agent answers to stay inspectable, versioned, and portable
Local-first workflows that avoid hosted indexes, cloud registries, or cloud refresh workers
Scenarios requiring visible source references and conservative link resolution that warns instead of guessing
Deployments that want deterministic lexical search without an embedding service or LLM key

Not for

Retrieval quality that depends on vector or semantic search
Heading-based splitting, or Obsidian semantics like Canvas, Bases, PDFs, images, audio, video, and Dataview fields
Importing GitHub repository URLs directly (there is no dedicated importer; use a local checkout or docs folder)
Workflows that need to write back to the knowledge source or need agent-callable write tools

Required permissions

Read local bundle directories and source cache and refresh state under ~/.okfy
Make same-origin network fetches to registered documentation sites when refresh is enabled (respects robots.txt by default)
Be launched as a stdio subprocess by an MCP client; the tools themselves are read-only

Risks and side effects

HTML cleanup quality varies by documentation site and can affect search results
Preflight rejects DNS-resolved private targets, but fetch-time DNS is not IP-pinned, leaving a theoretical DNS rebinding risk
The default stale-while-refresh mode can briefly serve non-latest docs; blocking or off modes change this
One page or file becomes one concept with no heading-based splitting, so granularity can be coarse
`--force` replaces a non-empty output bundle, and unsafe output directories are rejected unless an explicit dangerous override is given

Troubleshooting

Run `npx -y okfy-ai doctor <name> --client codex` to check source state, bundle validity, freshness, npx, generated configuration, MCP tool visibility, and JSON-RPC-clean stdout
Use `npx -y okfy-ai validate <bundle>` to confirm the bundle is valid; validation rejects missing type metadata and malformed reserved files
Confirm reserved files such as index.md and log.md exist; broken links and missing indexes are warnings but affect indexing
`serve --mcp` is started as a subprocess by the MCP client; do not run it as a normal interactive terminal command
When multi-source searches are ambiguous, pass an explicit source filter or disambiguation to search_concepts or read_concept
To prevent network fetches while serving, use `--refresh-mode off`; manual `okfy update` remains available

Use cases

Letting coding agents search documentation sites such as Stripe or Clerk and answer with source references

Importing project Markdown or Obsidian vaults into inspectable bundles for agent reading

Serving multiple documentation sources through one MCP server with source-filtered disambiguation

Sharing an agent-readable snapshot via the local static HTML Inspector or activate output

Supported clients

Claude DesktopFull support

Claude CodeFull support

CodexFull support

CursorFull support

Related MCP servers

Compare with other MCP servers