Icfmcp

An MCP (Model Context Protocol) server that lets AI harnesses — Claude Code, Claude Desktop, and any other MCP client — search and read Indent Comma Format (ICF) knowledge files via their ICX indexes.

Point it at one or more .icf files (or directories of them) and it exposes tag search, one-line summaries, full-text search, record retrieval, and validation as MCP tools over stdio. When a sibling .icx index file exists it is used directly; otherwise an index is generated in memory with icf.js.

Requirements

• Node.js >= 20

Install & run

npm install
npm run build

# serve a directory (scanned recursively for *.icf) and/or individual files
node dist/index.js path/to/knowledge-dir another/file.icf
# or, via the bin:
npx icfmcp path/to/knowledge-dir

The server speaks MCP on stdin/stdout; status lines go to stderr.

Registering with Claude Code

claude mcp add icf -- node <absolute-path>/icfmcp/dist/index.js <absolute-path-to-knowledge-dir>

Or in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "icf": {
      "command": "node",
      "args": ["<absolute-path>/icfmcp/dist/index.js", "<absolute-path-to-knowledge-dir>"]
    }
  }
}

Tools

Every tool returns a single JSON text block. Recoverable problems (unknown document or record, missing arguments) come back as { "error": "..." } with isError: true — never a protocol failure.

How the ICX 1.2 Tags/Summary flow works

ICX is ICF's companion index format. Version 1.2 adds two optional per-row fields and two inverted collections that make an index self-sufficient for triage (ICX v1.2 §7–§9, §15):

• Tags — search keywords per index row, joined with + (a literal + is escaped as \+). Tags are ideally typed master references like Project:ICF, so they resolve against the index's own master rows.
• Summary — a one-line synopsis of the record.
• tagindex[] — inverted map: tag → +-joined record ids.
• summaryindex[] — record id → summary.

The intended harness flow — and what this server implements for you:

1. Read the small index once (list_documents, list_tags).
2. Filter rows by tag (search_by_tag) — from the per-row Tags field and tagindex[], merged.
3. Triage candidates by summary (get_summaries) without opening the ICF.
4. Fetch only the winning records (get_record) — the raw block, resolved data, and byte positions.

When no .icx exists, the server generates the index in memory and fills the same information straight from the source: every field value that is a typed reference to a declared master type becomes a tag (ICX §7 generator behavior), and a record's summary attribute or Summary field becomes its summary. Documents and indexes are cached by mtime+size and reloaded automatically when files change — including when a .icx appears next to an .icf after startup.

Development

npm run dev -- tests/fixtures   # run from source (tsx)
npm test                        # vitest
npm run typecheck               # src + tests
npm run build                   # tsc -> dist/

See CLAUDE.md for the architecture notes.

License

MIT © Edison Williams