@inventarch/mcp-door
v3.8.1
Published
[](https://www.npmjs.com/package/@inventarch/mcp-door) [](https://github.com
Readme
@inventarch/mcp-door
ia-mcp-dooris a local MCP server that gives an agent host access to IA workspaces over stdio. It serves twenty tools: eleven read-only Door operations from@inventarch/runtime, the same reads theiaCLI performs,ia_vocabulary, five scopedia_kb_*knowledge readers, and three method tools,ia_session,ia_catalogueandia_method, which carry a method kit's procedure to any host.
ia host claudeandia host codexregister it for you. Any other MCP client can launch it directly.
⚡ Quick start
With Claude Code or Codex. In an initialized project, preview the registration, then apply it:
ia host claude
ia host claude --apply --yesClaude Code gets an ia-workspace server in .mcp.json; ia host codex --apply --yes adds [mcp_servers."ia-workspace"] to .codex/config.toml. Both entries start the copy of this server bundled in the host payload that ia host installs under ~/.ia/hosts/ (or $IA_HOME/hosts/), with your Node binary and the project's absolute path as --root. The files are machine-local; do not commit them. To commit a door entry instead, run ia host claude --commit (or codex or copilot): it adds an ia server that runs npx -y @inventarch/mcp-door@<version> from the project folder, with no local path, beside an instruction block that names ia_session. Claude Code asks for approval before it starts a project MCP server.
With any MCP client. Install the package and point the server at a workspace:
npm install --global @inventarch/mcp-door
ia-mcp-door --root path/to/your-projectWithout --root it serves the current directory. --kits <folder> (or the IA_KITS_DIR environment variable) names a folder of method kits, such as the ia plugin's config/kits; the method tools also read the kits installed under <IA home>/kits/<folder>/<version>/. At a workspace whose .ia/distributions.lock.json installs kits from an npm package of kits (the package entry ia install --package writes), they read those kits from the workspace store, where the engine installed them as ordinary releases, and never from another copy. A fresh clone holds no store yet: ia_session says to run ia restore, which refetches them by digest. It speaks MCP 2025-11-25 as UTF-8 JSON-RPC, one message per line on stdin and stdout. A client sends initialize and notifications/initialized before tools/list or tools/call. In the project from the root quick start, this session reads the authored @decision:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"demo","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ia_read","arguments":{"locator":"work-system/definition/decision/api-response-format"}}}' \
| ia-mcp-door --root .The second response line carries the result as structuredContent (shortened here):
{"jsonrpc":"2.0","id":2,"result":{"content":[…],"structuredContent":{"ok":true,"result":{…,"kind":"record","digest":"dae12679…","body":"Choose a response format for the public API.","certified":false}},"isError":false}}🧭 What it does
| Tool | Returns |
| --- | --- |
| ia_scope | A scope token, or one narrowed by phase, identities or root. Pass it as within to later calls. |
| ia_context | Cited procedure cells and applicable governance for a declared phase and primitive. format: "compact" summarizes omissions. |
| ia_select | Exactly one of the identities you supply; a tie or a missing coordinate refuses. |
| ia_get | One admitted record. |
| ia_records | The admitted record snapshot. It can be large; ia_search, ia_get and ia_traverse read less. |
| ia_resolve | The identity a typed reference resolves to; an unresolved reference says why. |
| ia_search | Ranked matches in decoded record text, with statistics computed inside the scope. |
| ia_traverse | Relationships followed from start records, with typed filters and optional condition gating. |
| ia_read | The body behind a locator (<identity>, <identity>#<phase>/<Primitive>, <identity>#<REQ-ID> or <path>:<line>), with the SHA-256 of its UTF-8 bytes and certified: false. includeRuntime: true reads a record at runtime placement. |
| ia_next | One plan's delivery view, as ia next prints it: milestones and tasks in prerequisite order, each task's verdict, and next, the command for the first task with no declared blocker. |
| ia_position | {body, digest, hostNote} for a scope key: seat (an identity or {path}), shape, phase, depth (0 to 2), budget (0 to 64) and word, plus optional primitive. Omitted, primitive is derived from shape; explicit primitive also supplies the default phase. No key part means the repository's @workspace at context, orient, depth 0, budget 0. |
| ia_vocabulary | The public words and their schemas, from the catalogue shipped with the server. It reads no workspace and takes no scope token. |
| ia_session | {sessionId, root, workspace, kits, lanes, pin?, restore?, briefing}: the kits found (bundled, installed or home), restore with the kits the lock installs that the store lacks and a briefing line that says to run ia restore, the lanes work, knowledge and delivery, the task pin last written for the workspace, and a briefing of at most 2,500 characters. It appends a line to <IA home>/sessions-v1/<sessionId>.jsonl. claim: {path, mode} is recorded as advisory; nothing is fenced. |
| ia_catalogue | {lane, items} for lane (work, knowledge or delivery), optionally narrowed by word and phase. Each item has a key such as work.brainstorm, its display name (ia-work:brainstorm, or ia-work for work.*), its kit, version, capability and profile, a one-line description and its state, bound or installed. |
| ia_method | The method packet for one key, exactly as the ia plugin's resolve.mjs prints it, with the same digest; a refusal is {error: {code, message, candidates?, key?}}, such as IA-CORE-NO-METHOD. With task, it writes the task pin under <IA home>/work-v1/<project>/<task>/, <project> being the workspace folder's name as a slug. subject is kept only as its SHA-256. |
The first eight tools were introduced in machine-protocol version 1 and ia_read, ia_next and ia_position in version 2. The server uses the latest protocol, version 3, whose ia_position schema additionally accepts primitive. A runtime Door explicitly serving version 2 still refuses that parameter. The protocol's report operation has no tool; run ia report from the CLI.
Every result carries its JSON as structuredContent and as text. A refusal sets isError: true. Door tools return ok: false with a top-level code; knowledge tools return {version: 1, ok: false, error: {code, message}}. Refusals from the three version 2 tools can also carry next, the one command to run:
ia_read:IA-RUNTIME-READ-UNADMITTEDfor a locator no admitted record in the scope answers. Through a narrowed token it names nothing outside the scope; through the whole workspace it says what the sources hold there, such as a record whose admission was refused.ia_next:IA-RUNTIME-NEXT-SEAT,-NO-PLAN,-AMBIGUOUSor-CYCLE, with theplansor thecycleconcerned.ia_position:IA-RUNTIME-REQUEST-INVALIDfor an invalid key or an unknown parameter, such as free text.
The ia_position body is a pure function of the key and the admitted records. It names no root, token or time, so two agents asking the same key of the same records read the same body and digest. hostNote sits beside it and says how fresh the last ia capture is.
⚖️ What it does not do
- It never writes a workspace. The read tools are annotated
readOnlyHint: true, and the workspace files are unchanged after a session. The method tools write only outside it (each*-v1home folder named here is the authoritative one unless its plain folder holds anauthoritativemarker; see the runtime SPEC): the session log and the task pin under the IA home, retained method bytes under itsmethod-closures-v1, and a kit's restored read copy under itskit-roots-v1. Authoring, validation and capture stay with the CLI (ia preview,ia author,ia validate,ia capture). - It checks mandates only for the method tools. A method tool acts at the server's
--rootor at a root the IA home'sworkspace-locations.jsonlists, and only when that workspace's governing mandates admit Observation for its default actor. The read tools check no@mandate; the CLI's mandate-checked commands, the edit guard andia-runnerdo. Mandates are cooperative restrictions, not authentication or a sandbox. - It grants nothing.
ia_selectandia_contextchoose and deliver records; they execute nothing. A read certifies nothing: the digest identifies bytes, not whether they are true. - Scope tokens are process-local and can expire. A token from
ia_scopelasts at most as long as the server process. Once 4,096 newer scopes are issued or read before it is read again, it refuses withIA-DB-STALE(IA-KB-SCOPE-UNAVAILABLEfrom ania_kbtool) and reads nothing. Callia_scopefor a new one, with the same narrowing. Calls that omitwithinread the initial boundary, which never expires. Narrowing a token limits what later calls read through it. - Bounded transport. Stdio only, with no network listener. A line over 4 MiB or invalid UTF-8 ends the session, and
tools/listissues no pagination cursor.
📚 Learn more
Five additional read tools—ia_kb_check, ia_kb_search, ia_kb_read, ia_kb_resolve, and ia_kb_traverse—read selected native records and their bound documents through the knowledge foundation. They accept an optional within issued by this server. The original Door validates membership, and a matching graph revision is required before any body read. A stale, foreign or unsupported narrowed scope refuses; there is no workspace fallback. The complete knowledge-tool result envelope, including both text and structured content, is bounded to 48 KiB; an oversized request id instead receives a JSON-RPC error. Local citations resolve only while current captured bytes still match. These tools create no index or .kb directory.
- SPEC.md: the package contract
- LANGUAGE.md: the packaged summary of the words this release ships
@inventarch/runtime: the Door,MACHINE_PROTOCOL, positions and delivery views behind these tools- CLI guide:
ia host,ia doctorand the matchingia position,ia nextandia readcommands - Architecture reference
- Root README
