Tools · AI integration

icfmcp — the ICF MCP server

ICF provides an MCP (Model Context Protocol) integration for exposing structured knowledge to AI clients. Point icfmcp at your .icf files and Claude Code, Claude Desktop, or any MCP client can search them by tag, read one-line summaries, run full-text search, retrieve full records, and validate documents.

Version 0.1.1 npm: icfmcp Node 20+ MIT Source on GitHub

Setup

Register with Claude Code:

claude mcp add icf -- npx -y icfmcp /path/to/knowledge

Or in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "icf": {
      "command": "npx",
      "args": ["-y", "icfmcp", "/path/to/knowledge"]
    }
  }
}

Arguments are one or more .icf files and/or directories (scanned recursively for *.icf).

What data is exposed — and to whom

  • Local only. The server runs on your machine and speaks MCP over stdin/stdout to the client that launched it. It makes no network calls; your data never leaves the machine unless your AI client sends retrieved content to a model — the same trust decision as any MCP server.
  • Only what you point it at. It reads exactly the files and directories given on the command line — nothing else.
  • ICX is optional. When a sibling .icx index exists it is used directly; otherwise an index (tags, summaries, byte ranges) is generated in memory with icf.js. Plain .icf files work out of the box.

Tools

ToolWhat it does
list_documentsRegistry overview — name, record count, schema ids, tag count, whether the index came from a .icx or was generated.
list_tagsAll tags with record counts, most frequent first.
search_by_tagRecords carrying a tag (exact or substring match) with summary and byte range.
get_summariesrecordId → one-line summary, optionally filtered by tag — cheap triage before reading records.
search_textCase-insensitive full-text search over record blocks, with line numbers.
get_recordOne record in full: resolved JSON, attributes, index row and raw ICF text; master references resolved.
validate_documentErrors and warnings from the ICF validator, for a served document or inline ICF text.

Why ICF + ICX works well for AI harnesses

The ICX 1.2 index carries Tags and one-line Summary fields per record, so a harness can triage an entire archive from the index alone — then fetch only the matching records by byte range instead of reading whole files into context. icfmcp packages that flow as MCP tools.

Any MCP-capable client can use the server — Claude Code and Claude Desktop are the tested configurations.