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

Tool	Input	Behavior
list_documents	—	Registry overview: name, path, record count, schema ids, whether the index came from a .icx file or was generated, tag count.
list_tags	document?	All tags with the number of records carrying each, sorted by count descending.
search_by_tag	tag, document?, matchMode?	Records carrying a tag. exact (default) is case-insensitive equality; contains is a case-insensitive substring match. Returns document, recordId, uuid, summary, tags, and Line/Offset/Size when known.
get_record	document, recordId	One record in full: resolved data as JSON, @record attributes, its index row, and the raw ICF block text. Also resolves master rows by id.
get_summaries	document?, tag?	recordId → one-line summary for every record that has one, optionally filtered by tag.
search_text	query, document?	Case-insensitive full-text search over raw record blocks; returns matching lines with recordId and absolute line numbers.
validate_document	document? or icf?	Errors and warnings from the ICF validator, for a served document or inline ICF text.

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