@inventarch/mcp-door 3.1.0 → 3.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,11 +1,85 @@
1
1
  # @inventarch/mcp-door
2
2
 
3
- See [the package contract](SPEC.md) and the exported TypeScript declarations.
3
+ [![npm](https://img.shields.io/npm/v/@inventarch/mcp-door?label=npm)](https://www.npmjs.com/package/@inventarch/mcp-door) [![Public quality](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml/badge.svg?branch=main)](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE) [![Node](https://img.shields.io/badge/node-22.x-brightgreen)](package.json)
4
4
 
5
- `ia-mcp-door [--root <workspace>]` serves read-only MCP 2025-11-25 tools over one workspace root, as UTF-8 JSON-RPC lines on stdin and stdout. `tools/list` projects `MACHINE_PROTOCOL` from `@inventarch/runtime`: one tool per Door operation whose row names one, with the row's parameter schema as its `inputSchema` (`ia_context` adds the transport-only `format`), plus `ia_vocabulary`, which reads the catalogue shipped with the server and no workspace. That is twelve tools: `ia_scope`, `ia_context`, `ia_select`, `ia_get`, `ia_records`, `ia_resolve`, `ia_search` and `ia_traverse` from protocol version 1, `ia_read`, `ia_next` and `ia_position` from version 2, and `ia_vocabulary`. `report` is CLI-only. A scope token lives as long as the server process, so a token `ia_scope` issues narrows later calls.
5
+ > `ia-mcp-door` is a local MCP server that gives an agent host read-only access to one IA workspace over stdio. It serves twelve tools: eleven Door operations from [`@inventarch/runtime`](../../packages/runtime/README.md), the same reads the `ia` CLI performs, and `ia_vocabulary`.
6
+ >
7
+ > `ia host claude` and `ia host codex` register it for you. Any other MCP client can launch it directly.
6
8
 
7
- `ia_read` returns the body behind one locator (`<identity>`, `<identity>#<phase>/<Primitive>`, `<identity>#<REQ-ID>` or `<path>:<line>`) inside the scope, with the SHA-256 of its UTF-8 bytes and `certified: false`: a fragment's text, else the document the record's source locator names, read from the workspace or, for an adopted mount, from the directory `.ia/workspace.json` binds it to, else the record's own body. A locator that no admitted record in the scope answers is refused as `IA-RUNTIME-READ-UNADMITTED`: through a token narrower than the whole workspace, one `ia_scope` issued with `identities`, a `phase` or a `root` below the workspace root, or from such a token, without naming what lies outside the scope; through the server's initial scope, the whole workspace, or a token `ia_scope` issued from it without narrowing it, naming what its sources hold there, a record admission refused with its `reason`. A document the server cannot read is named by its workspace-relative path, never by the server's root. Pass `includeRuntime: true` to read a record at runtime placement.
9
+ ## ⚡ Quick start
8
10
 
9
- `ia_next` returns one plan's delivery view inside the scope, computed per call and never stored: the plan a `seat` (a `@plan`, `@milestone` or `@task` identity) belongs to, or without one the only `@plan` authored at band 100; its milestones and tasks in one prerequisites-first order, each task with a basis line per requirement, one verdict (`exit evidence recorded (…)`, `no declared blocker` or `blocked (…)`), its `work.status` as self-declared and five state lines; review items; and `next`, the command for the first task with no declared blocker. A refusal (`IA-RUNTIME-NEXT-SEAT`, `-NO-PLAN`, `-AMBIGUOUS` or `-CYCLE`) carries `next`, the one command to run, and the `plans` or the `cycle` it names.
11
+ **With Claude Code or Codex.** In an initialized project, preview the registration, then apply it:
10
12
 
11
- `ia_position` returns body(K) for a scope key inside the scope, `{body, digest, hostNote}`: the key's parts `seat` (an identity, or `{path}` for a location), `shape`, `phase`, `depth` (0 to 2), `budget` (0 to 64) and `word`, all optional, no part being K0, the repository's `@workspace` at context, orient, depth 0 and budget 0. The body is a pure function of the key and the records the scope admits, so it names no root, token or time and reads no request text, and its `digest` is the SHA-256 of its canonical JSON; `hostNote` is host state beside it, the revision and how fresh the last `ia capture` is. A refusal of the key (`IA-RUNTIME-REQUEST-INVALID`) carries `next`, the one command to run.
13
+ ```sh
14
+ ia host claude
15
+ ia host claude --apply --yes
16
+ ```
17
+
18
+ Claude 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. Claude Code asks for approval before it starts a project MCP server.
19
+
20
+ **With any MCP client.** Install the package and point the server at a workspace:
21
+
22
+ ```sh
23
+ npm install --global @inventarch/mcp-door
24
+ ia-mcp-door --root path/to/your-project
25
+ ```
26
+
27
+ Without `--root` it serves the current directory. 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](../../README.md#-quick-start), this session reads the authored `@decision`:
28
+
29
+ ```sh
30
+ printf '%s\n' \
31
+ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"demo","version":"1"}}}' \
32
+ '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
33
+ '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ia_read","arguments":{"locator":"work-system/definition/decision/api-response-format"}}}' \
34
+ | ia-mcp-door --root .
35
+ ```
36
+
37
+ The second response line carries the result as `structuredContent` (shortened here):
38
+
39
+ ```text
40
+ {"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}}
41
+ ```
42
+
43
+ ## 🧭 What it does
44
+
45
+ | Tool | Returns |
46
+ | --- | --- |
47
+ | `ia_scope` | A scope token, or one narrowed by `phase`, `identities` or `root`. Pass it as `within` to later calls. |
48
+ | `ia_context` | Cited procedure cells and applicable governance for a declared phase and primitive. `format: "compact"` summarizes omissions. |
49
+ | `ia_select` | Exactly one of the identities you supply; a tie or a missing coordinate refuses. |
50
+ | `ia_get` | One admitted record. |
51
+ | `ia_records` | The admitted record snapshot. It can be large; `ia_search`, `ia_get` and `ia_traverse` read less. |
52
+ | `ia_resolve` | The identity a typed reference resolves to; an unresolved reference says why. |
53
+ | `ia_search` | Ranked matches in decoded record text, with statistics computed inside the scope. |
54
+ | `ia_traverse` | Relationships followed from start records, with typed filters and optional condition gating. |
55
+ | `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. |
56
+ | `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. |
57
+ | `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`. No key part means the repository's `@workspace` at context, orient, depth 0, budget 0. |
58
+ | `ia_vocabulary` | The public words and their schemas, from the catalogue shipped with the server. It reads no workspace and takes no scope token. |
59
+
60
+ The first eight tools are machine-protocol version 1 and `ia_read`, `ia_next` and `ia_position` are version 2. The protocol's `report` operation has no tool; run `ia report` from the CLI.
61
+
62
+ Every result carries its JSON as `structuredContent` and as text. A refusal sets `isError: true` and returns `ok: false` with a `code`. Refusals from the three version 2 tools can also carry `next`, the one command to run:
63
+
64
+ - `ia_read`: `IA-RUNTIME-READ-UNADMITTED` for 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.
65
+ - `ia_next`: `IA-RUNTIME-NEXT-SEAT`, `-NO-PLAN`, `-AMBIGUOUS` or `-CYCLE`, with the `plans` or the `cycle` concerned.
66
+ - `ia_position`: `IA-RUNTIME-REQUEST-INVALID` for an invalid key or an unknown parameter, such as free text.
67
+
68
+ 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.
69
+
70
+ ## ⚖️ What it does not do
71
+
72
+ - **It never writes.** Every tool is annotated `readOnlyHint: true`, and the workspace files are unchanged after a session. Authoring, validation and capture stay with the CLI (`ia preview`, `ia author`, `ia validate`, `ia capture`).
73
+ - **It checks no `@mandate`.** The CLI's mandate-checked commands, the edit guard and `ia-runner` check mandates; these tools do not. Mandates are cooperative restrictions, not authentication or a sandbox.
74
+ - **It grants nothing.** `ia_select` and `ia_context` choose and deliver records; they execute nothing. A read certifies nothing: the digest identifies bytes, not whether they are true.
75
+ - **Scope tokens are process-local.** A token from `ia_scope` lasts as long as the server process. Narrowing a token limits what later calls read through it.
76
+ - **Bounded transport.** Stdio only, with no network listener. A line over 4 MiB or invalid UTF-8 ends the session, and `tools/list` issues no pagination cursor.
77
+
78
+ ## 📚 Learn more
79
+
80
+ - [SPEC.md](SPEC.md): the package contract
81
+ - [LANGUAGE.md](LANGUAGE.md): the packaged summary of the words this release ships
82
+ - [`@inventarch/runtime`](../../packages/runtime/README.md): the Door, `MACHINE_PROTOCOL`, positions and delivery views behind these tools
83
+ - [CLI guide](../cli/README.md): `ia host`, `ia doctor` and the matching `ia position`, `ia next` and `ia read` commands
84
+ - [Architecture reference](../../docs/reference/architecture/README.md)
85
+ - [Root README](../../README.md)
@@ -2,7 +2,7 @@
2
2
  "version": 1,
3
3
  "language": "ia 1.0",
4
4
  "status": "public IA 1.0 language contract",
5
- "sourceDigest": "5c2c9fbdf0911032d90a97a303bdbe3fb2416ca615b6babeca4baa306677026f",
5
+ "sourceDigest": "8ebfaf93977468e42897cf4951025d11fab1297bacce94971a76d484aec43201",
6
6
  "words": [
7
7
  {
8
8
  "word": "agent",
@@ -1 +1 @@
1
- {"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AA0EA,eAAO,MAAM,KAAK;;;;;;;;;;;;;;GAKf,CAAC;AACJ,eAAO,MAAM,UAAU,qBAAuE,CAAC"}
1
+ {"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAyEA,eAAO,MAAM,KAAK;;;;;;;;;;;;;;GAKf,CAAC;AACJ,eAAO,MAAM,UAAU,qBAAuE,CAAC"}
package/dist/tools.js CHANGED
@@ -17,9 +17,8 @@ const withFormat = (schema) => ({
17
17
  properties: { ...schema['properties'], format: FORMAT },
18
18
  });
19
19
  /**
20
- * M04: the door operations whose row names a tool, described once in @inventarch/runtime's MACHINE_PROTOCOL (spec-0012
21
- * MCP-01): the eight of version 1 (report is CLI-only), and read, next and position, which version 2 adds (plan
22
- * amendment A3).
20
+ * The door operations whose row names a tool, described once in @inventarch/runtime's MACHINE_PROTOCOL (runtime R12):
21
+ * the eight of version 1 (report is CLI-only), and read, next and position, which version 2 adds.
23
22
  */
24
23
  const served = MACHINE_PROTOCOL.operations.flatMap((operation) => operation.mcp === null
25
24
  ? []
package/dist/tools.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inventarch/mcp-door",
3
- "version": "3.1.0",
3
+ "version": "3.1.1",
4
4
  "type": "module",
5
5
  "main": "./dist/main.js",
6
6
  "types": "./dist/main.d.ts",
@@ -14,7 +14,7 @@
14
14
  "LANGUAGE.md"
15
15
  ],
16
16
  "dependencies": {
17
- "@inventarch/runtime": "3.1.0"
17
+ "@inventarch/runtime": "3.1.1"
18
18
  },
19
19
  "devDependencies": {
20
20
  "@types/node": "^22.19.0",