icfmcp CLAUDE.md

CLAUDE.md

Guidance for Claude Code when working in this repository.

What this repo is

icfmcp is an MCP (Model Context Protocol) server, written in TypeScript (ESM, Node >= 20), that exposes ICF knowledge files to AI harnesses through their ICX indexes. It consumes the sibling icf.js library as a file dependency ("icf.js": "file:../icf.js" — the npm registry copy is older than the local build).

Specs (read before changing index semantics):

• ICF language spec v1.1: F:\git\GreenbooksGithub\icformat.org\icf\specification\v1.1\
• ICX index spec v1.2: F:\git\GreenbooksGithub\icformat.org\icx\specification\v1.2\ — §7 Tags, §8 Summary, §9 inverted structures (tagindex[]/summaryindex[]), §15 harness usage flow.
• icf.js API reference: F:\git\GreenbooksGithub\icf.js\DOCUMENTATION.md

Build & test

npm run build      # tsc -> dist/ (dist/index.js keeps the #!/usr/bin/env node shebang; bin "icfmcp")
npm test           # vitest against tests/fixtures — no MCP transport needed
npm run typecheck  # tsc --noEmit for src (tsconfig.json) and tests (tsconfig.test.json)
npm run dev -- tests/fixtures

Architecture

src/index.ts is only MCP wiring (CLI args → DocumentRegistry, zod tool schemas → McpServer, stdio transport). All logic lives in pure, transport-free modules — tests exercise them directly:

• src/registry.ts — DocumentRegistry. Discovers .icf files (directories scanned recursively, skipping dotdirs/node_modules), keys each by its file stem (duplicates suffixed -2, -3, … in sorted-path order), and caches parsed entries by mtime+size of both the ICF and its ICX. refresh() is called by every tool and is cheap when nothing changed; it also reloads when a sibling .icx appears/disappears and drops vanished files. Index acquisition per document: the ICF's @index directive target first, then the same-stem sibling .icx; if neither exists, generateIcx(doc) in memory.
• src/indexing.ts — extractIndexModel(icxDoc, masterTypes) turns a parsed/generated ICX document into an IndexModel (rows + tagIndex + summaryIndex). Two quirks it absorbs: a hand-written ICX exposes master rows via getMasters() and data rows/tagindex[]/summaryindex[] inside one implicit record; a generateIcx document puts all collections (master types included) in one synthetic record — hence the masterTypes hint from the source document. augmentFromSource(...) then fills gaps from the source ICF: missing Line/Offset/Size from scanned spans, missing tags by harvesting typed master references (ICX §7 generator rule), missing summaries from a summary attribute/field, and synthesizes rows for records the index doesn't know.
• src/source.ts — scanRecordBlocks finds column-0 @record lines, returning per-record byte offset/size, 1-based start line, id=, and the raw block text. Raw blocks are always taken from this scan (never by ICX byte ranges) so stale indexes can't corrupt output. Known limitation: a column-0 @record inside a preformatted text block would miscount; spans are correlated with parsed records by id first, by order only when counts agree.
• src/tags.ts — ICX §7 tag-cell handling. Feature-detects icf.js 1.2 splitTags/joinTags exports and falls back to a local implementation (join +, escape \, \+ = literal plus). Keep the fallbacks and their direct tests even after icf.js 1.2 is everywhere.
• src/tools.ts — the seven tool functions, all (registry, args) -> JSON-serializable object. Recoverable problems return { error, ... } (checked with isToolError), never throw; src/index.ts maps that to isError: true and always emits a single JSON text content block.