@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 +79 -5
- package/assets/vocabulary.json +1 -1
- package/dist/tools.d.ts.map +1 -1
- package/dist/tools.js +2 -3
- package/dist/tools.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,11 +1,85 @@
|
|
|
1
1
|
# @inventarch/mcp-door
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@inventarch/mcp-door) [](https://github.com/inventarch/ia/actions/workflows/platform-quality.yml) [](LICENSE) [](package.json)
|
|
4
4
|
|
|
5
|
-
`ia-mcp-door
|
|
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
|
-
|
|
9
|
+
## ⚡ Quick start
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
**With Claude Code or Codex.** In an initialized project, preview the registration, then apply it:
|
|
10
12
|
|
|
11
|
-
|
|
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)
|
package/assets/vocabulary.json
CHANGED
|
@@ -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": "
|
|
5
|
+
"sourceDigest": "8ebfaf93977468e42897cf4951025d11fab1297bacce94971a76d484aec43201",
|
|
6
6
|
"words": [
|
|
7
7
|
{
|
|
8
8
|
"word": "agent",
|
package/dist/tools.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"
|
|
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
|
-
*
|
|
21
|
-
*
|
|
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":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAChC,MAAM,MAAM,GAAG,CAAC,UAAmC,EAAE,WAA8B,EAAE,EAAE,EAAE,CAAC,CAAC;IACzF,IAAI,EAAE,QAAQ;IACd,UAAU;IACV,QAAQ;IACR,oBAAoB,EAAE,KAAK;CAC5B,CAAC,CAAC;AACH,wGAAwG;AACxG,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;IACzB,WAAW,EACT,6LAA6L;CAChM,CAAC;AACF,MAAM,UAAU,GAAG,CAAC,MAAkB,EAAc,EAAE,CAAC,CAAC;IACtD,GAAG,MAAM;IACT,UAAU,EAAE,EAAE,GAAI,MAAM,CAAC,YAAY,CAA6B,EAAE,MAAM,EAAE,MAAM,EAAE;CACrF,CAAC,CAAC;AACH
|
|
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.
|
|
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.
|
|
17
|
+
"@inventarch/runtime": "3.1.1"
|
|
18
18
|
},
|
|
19
19
|
"devDependencies": {
|
|
20
20
|
"@types/node": "^22.19.0",
|