@ebitex/content-mcp 0.1.0 → 0.1.74

package/README.md

@@ -1,102 +1,102 @@
-# @ebitex/content-mcp
-
-An [MCP](https://modelcontextprotocol.io) server for **ebitex Content**. Point an AI agent at it and
-it can build a content model end to end — Contracts and their fields, Templates, Components, the
-Experience tree — and publish it.
-
-It runs locally, over `stdio`, authenticated by a Content management key you mint yourself. Nothing
-is hosted by ebitex, so your write-capable key never leaves your machine.
-
-## Configure it
-
-```json
-{
-  "mcpServers": {
-    "ebitex-content": {
-      "command": "npx",
-      "args": ["-y", "@ebitex/content-mcp"],
-      "env": { "EBITEX_CONTENT_MANAGEMENT_KEY": "frm_live_..." }
-    }
-  }
-}
-```
-
-| Variable | |
-|---|---|
-| `EBITEX_CONTENT_MANAGEMENT_KEY` | **Required.** Mint one in Composer under Settings → Management keys |
-| `EBITEX_CONTENT_API_BASE` | Defaults to `https://api.ebitex.io` |
-| `EBITEX_CONTENT_MCP_READ_ONLY` | Set to `1` to hide every write tool regardless of the key's scopes |
-| `EBITEX_CONTENT_TARGET_MANAGEMENT_KEY` | A second key, for `content_transfer` to import into |
-
-## Mint the key deliberately
-
-A management key is bound to **one organization and one authoring environment**, and acts as **one
-role**. That binding is the real safety boundary here, and it is the one this server cannot supply
-for you:
-
-- **Bind it to a non-production authoring environment.** This server has no way to tell which of
-  your environments is production — that is your own topology, and a management key deliberately
-  cannot see it. A heuristic would be worse than nothing, because it would be believed.
-- **Leave the authoring scope off unless the agent needs to write.** Without it, the write tools are
-  not merely refused; they are not offered at all.
-- **Give it a role with the access it needs and no more.** Branch access rules and workflow gating
-  apply to a key exactly as they do to a person.
-
-On startup the server prints, to stderr, which organization and environment the key reached and
-which role it acts as. Read it once; if it is not what you expected, stop.
-
-## The tools
-
-Eight, shaped around what an agent does rather than around REST routes.
-
-| | |
-|---|---|
-| `content_describe` | What can exist here: every field type with its **own settings schema**, plus this environment's Contracts and Templates |
-| `content_find` | Locate entities by kind, search or external id |
-| `content_get` | Read one entity in full |
-| `content_write` | Create or update one entity |
-| `content_delete` | Delete one, behind an explicit confirmation |
-| `content_publish` | Plan, read the blockers, then publish |
-| `content_operation_status` | Poll a job |
-| `content_transfer` | Move a whole model between environments, atomically |
-
-Which of them appear depends on your key's scopes: a read-scoped key gets a server with no write
-tools at all, rather than tools that always fail.
-
-## Why it cannot drift
-
-The server encodes **no knowledge of the content model**. It does not know what field types exist,
-what a Contract may contain, or what makes a document valid. All three are answered at runtime:
-`content_describe` returns each field type's own declared schema, and every write is validated by the
-server that stores it. There is nothing here to fall out of step, because nothing is duplicated.
-
-That also shapes how errors work. A refusal is relayed **whole**, with its field paths intact and no
-summarizing, because for an agent the error is the control loop: try, read the error, fix the one
-field it names, call again.
-
-## Resources
-
-Alongside the tools, the server offers the Content documentation as MCP resources — start with
-`ebitex-content://help/agent-authoring`, which explains what Contracts, Templates, Presentations,
-Adapters and the Experience tree are for, and the order to create them in.
-
-## Embedding it
-
-```ts
-import { buildServer, readConfig } from '@ebitex/content-mcp'
-
-const { server, banner } = await buildServer({ config: readConfig() })
-console.error(banner) // never stdout — on stdio, that stream is the protocol
-```
-
-## A note on `zod`
-
-This package pins `zod` to `^3.25.76` rather than `^4`, even though `@modelcontextprotocol/sdk`
-accepts either. The reason is type identity, not capability: the SDK's schema types are written
-against whichever `zod` resolves for *it*, and a second copy at a different major produces a type
-mismatch on every tool registration. Pinning to the version the SDK resolves keeps one `zod` in the
-tree. This matters at build time only; at runtime the SDK handles both.
-
-## Licence
-
-UNLICENSED — © ebitex software LLC.
+# @ebitex/content-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for **ebitex Content**. Point an AI agent at it and
+it can build a content model end to end — Contracts and their fields, Templates, Components, the
+Experience tree — and publish it.
+
+It runs locally, over `stdio`, authenticated by a Content management key you mint yourself. Nothing
+is hosted by ebitex, so your write-capable key never leaves your machine.
+
+## Configure it
+
+```json
+{
+  "mcpServers": {
+    "ebitex-content": {
+      "command": "npx",
+      "args": ["-y", "@ebitex/content-mcp"],
+      "env": { "EBITEX_CONTENT_MANAGEMENT_KEY": "frm_live_..." }
+    }
+  }
+}
+```
+
+| Variable | |
+|---|---|
+| `EBITEX_CONTENT_MANAGEMENT_KEY` | **Required.** Mint one in Composer under Settings → Management keys |
+| `EBITEX_CONTENT_API_BASE` | Defaults to `https://api.ebitex.io` |
+| `EBITEX_CONTENT_MCP_READ_ONLY` | Set to `1` to hide every write tool regardless of the key's scopes |
+| `EBITEX_CONTENT_TARGET_MANAGEMENT_KEY` | A second key, for `content_transfer` to import into |
+
+## Mint the key deliberately
+
+A management key is bound to **one organization and one authoring environment**, and acts as **one
+role**. That binding is the real safety boundary here, and it is the one this server cannot supply
+for you:
+
+- **Bind it to a non-production authoring environment.** This server has no way to tell which of
+  your environments is production — that is your own topology, and a management key deliberately
+  cannot see it. A heuristic would be worse than nothing, because it would be believed.
+- **Leave the authoring scope off unless the agent needs to write.** Without it, the write tools are
+  not merely refused; they are not offered at all.
+- **Give it a role with the access it needs and no more.** Branch access rules and workflow gating
+  apply to a key exactly as they do to a person.
+
+On startup the server prints, to stderr, which organization and environment the key reached and
+which role it acts as. Read it once; if it is not what you expected, stop.
+
+## The tools
+
+Eight, shaped around what an agent does rather than around REST routes.
+
+| | |
+|---|---|
+| `content_describe` | What can exist here: every field type with its **own settings schema**, plus this environment's Contracts and Templates |
+| `content_find` | Locate entities by kind, search or external id |
+| `content_get` | Read one entity in full |
+| `content_write` | Create or update one entity |
+| `content_delete` | Delete one, behind an explicit confirmation |
+| `content_publish` | Plan, read the blockers, then publish |
+| `content_operation_status` | Poll a job |
+| `content_transfer` | Move a whole model between environments, atomically |
+
+Which of them appear depends on your key's scopes: a read-scoped key gets a server with no write
+tools at all, rather than tools that always fail.
+
+## Why it cannot drift
+
+The server encodes **no knowledge of the content model**. It does not know what field types exist,
+what a Contract may contain, or what makes a document valid. All three are answered at runtime:
+`content_describe` returns each field type's own declared schema, and every write is validated by the
+server that stores it. There is nothing here to fall out of step, because nothing is duplicated.
+
+That also shapes how errors work. A refusal is relayed **whole**, with its field paths intact and no
+summarizing, because for an agent the error is the control loop: try, read the error, fix the one
+field it names, call again.
+
+## Resources
+
+Alongside the tools, the server offers the Content documentation as MCP resources — start with
+`ebitex-content://help/agent-authoring`, which explains what Contracts, Templates, Presentations,
+Adapters and the Experience tree are for, and the order to create them in.
+
+## Embedding it
+
+```ts
+import { buildServer, readConfig } from '@ebitex/content-mcp'
+
+const { server, banner } = await buildServer({ config: readConfig() })
+console.error(banner) // never stdout — on stdio, that stream is the protocol
+```
+
+## A note on `zod`
+
+This package pins `zod` to `^3.25.76` rather than `^4`, even though `@modelcontextprotocol/sdk`
+accepts either. The reason is type identity, not capability: the SDK's schema types are written
+against whichever `zod` resolves for *it*, and a second copy at a different major produces a type
+mismatch on every tool registration. Pinning to the version the SDK resolves keeps one `zod` in the
+tree. This matters at build time only; at runtime the SDK handles both.
+
+## Licence
+
+UNLICENSED — © ebitex software LLC.

package/dist/main.js

@@ -30,6 +30,22 @@ main().catch((error) => {
     else {
         console.error(error);
     }
-    process.exit(1);
+    // `process.exitCode`, never `process.exit()`. Found on Windows against the real published
+    // package: `process.exit()` here tears the process down while the `fetch` to `/whoami` still has
+    // live libuv handles, which aborts with
+    //
+    //   Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src/win/async.c, line 76
+    //
+    // and an exit code of 127 rather than 1 — conventionally "command not found", which is actively
+    // misleading for a launcher. The message does still print first, so the failure looks like a
+    // crash *after* correctly reporting itself.
+    //
+    // Setting the code and letting the loop drain exits cleanly in well under a second: undici's
+    // keep-alive socket is unref'd, so it holds nothing open. The startup path that throws BEFORE any
+    // request (a missing key) was always fine, which is what localizes this to "a fetch happened".
+    //
+    // Note no test here can catch a regression: the assertion is Windows-only (`src/win/async.c`) and
+    // CI runs Ubuntu, where `process.exit()` would exit 1 quietly. The guard is this comment.
+    process.exitCode = 1;
 });
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,WAAW,EAAE,CAAA;IAC9C,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IAErB,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAA;AAClD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,8FAA8F;IAC9F,0FAA0F;IAC1F,qDAAqD;IACrD,IAAI,KAAK,YAAY,WAAW,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9B,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,WAAW,EAAE,CAAA;IAC9C,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IAErB,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAA;AAClD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,8FAA8F;IAC9F,0FAA0F;IAC1F,qDAAqD;IACrD,IAAI,KAAK,YAAY,WAAW,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAC9B,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;IAED,0FAA0F;IAC1F,iGAAiG;IACjG,wCAAwC;IACxC,EAAE;IACF,0FAA0F;IAC1F,EAAE;IACF,gGAAgG;IAChG,6FAA6F;IAC7F,4CAA4C;IAC5C,EAAE;IACF,6FAA6F;IAC7F,kGAAkG;IAClG,+FAA+F;IAC/F,EAAE;IACF,kGAAkG;IAClG,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAA;AACtB,CAAC,CAAC,CAAA"}