@ebitex/content-mcp 0.1.0

package/README.md

@@ -0,0 +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.

package/dist/client.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The HTTP client for `/content/management/v1`.
+ *
+ * Deliberately **one method per verb**, not one per endpoint. The endpoints come from
+ * `routes.ts`'s table, which is the only place in this package that knows a route exists — so a
+ * family admitted by a later spec is a row there rather than a method here, and there is no second
+ * list to keep in step with the first.
+ *
+ * It is also the only module that holds the key, and the only one that calls `fetch`. Both are
+ * worth keeping true: a test drives the whole server by substituting one function.
+ */
+export declare const ROUTE_PREFIX = "/content/management/v1";
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type ContentClient = {
+    /** Origin only, for messages that need to say where writes are landing. */
+    readonly baseUrl: string;
+    request(method: HttpMethod, path: string, body?: unknown): Promise<unknown>;
+};
+export type ClientOptions = {
+    baseUrl: string;
+    key: string;
+    /** Substituted by tests. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+};
+export declare function createClient(options: ClientOptions): ContentClient;
+/**
+ * Builds a query string from values that may be absent, skipping the absent ones.
+ *
+ * Kept here rather than inlined because the API rejects unknown *properties* on a body but is
+ * ordinary about query parameters — the asymmetry is easy to forget, and sending `limit=undefined`
+ * as a literal string is the kind of thing that reads as an API bug for an afternoon.
+ */
+export declare function query(params: Record<string, string | number | boolean | undefined | null>): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,YAAY,2BAA2B,CAAA;AAEpD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEpE,MAAM,MAAM,aAAa,GAAG;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC5E,CAAA;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,CAAA;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAgClE;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,MAAM,CASlG"}

package/dist/client.js

@@ -0,0 +1,63 @@
+import { toContentApiError } from './errors.js';
+/**
+ * The HTTP client for `/content/management/v1`.
+ *
+ * Deliberately **one method per verb**, not one per endpoint. The endpoints come from
+ * `routes.ts`'s table, which is the only place in this package that knows a route exists — so a
+ * family admitted by a later spec is a row there rather than a method here, and there is no second
+ * list to keep in step with the first.
+ *
+ * It is also the only module that holds the key, and the only one that calls `fetch`. Both are
+ * worth keeping true: a test drives the whole server by substituting one function.
+ */
+export const ROUTE_PREFIX = '/content/management/v1';
+export function createClient(options) {
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    return {
+        baseUrl: options.baseUrl,
+        async request(method, path, body) {
+            const response = await doFetch(`${options.baseUrl}${ROUTE_PREFIX}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${options.key}`,
+                    Accept: 'application/json',
+                    ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+            if (!response.ok)
+                throw await toContentApiError(response);
+            // 202 (both publish phases) and 204 (every delete) carry no body. Returning `null` rather
+            // than throwing on an empty parse keeps the caller from having to know which is which.
+            if (response.status === 204)
+                return null;
+            const text = await response.text();
+            if (!text)
+                return null;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        },
+    };
+}
+/**
+ * Builds a query string from values that may be absent, skipping the absent ones.
+ *
+ * Kept here rather than inlined because the API rejects unknown *properties* on a body but is
+ * ordinary about query parameters — the asymmetry is easy to forget, and sending `limit=undefined`
+ * as a literal string is the kind of thing that reads as an API bug for an afternoon.
+ */
+export function query(params) {
+    const search = new URLSearchParams();
+    for (const [name, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        search.set(name, String(value));
+    }
+    const rendered = search.toString();
+    return rendered ? `?${rendered}` : '';
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAA;AAiBpD,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAA;IAErD,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI;YAC9B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,GAAG,YAAY,GAAG,IAAI,EAAE,EAAE;gBACzE,MAAM;gBACN,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,OAAO,CAAC,GAAG,EAAE;oBACtC,MAAM,EAAE,kBAAkB;oBAC1B,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;iBACtE;gBACD,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;aAC5D,CAAC,CAAA;YAEF,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAA;YAEzD,0FAA0F;YAC1F,uFAAuF;YACvF,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,IAAI,CAAA;YAExC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;YAClC,IAAI,CAAC,IAAI;gBAAE,OAAO,IAAI,CAAA;YAEtB,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACzB,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAC,MAAoE;IACxF,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;IACpC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE;YAAE,SAAQ;QACnE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IACjC,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;IAClC,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;AACvC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Everything this server reads from its environment, in one place.
+ *
+ * An MCP server is launched by a host process with a config block, not by a person at a prompt, so
+ * a misconfiguration has no interactive moment in which to be noticed. That makes the failure mode
+ * the thing to design for: a missing key must stop the server at startup naming the variable, never
+ * surface later as a `401` on whatever tool the agent happened to call first. An agent reading a
+ * `401` will reasonably conclude the credential is wrong rather than absent, and will retry.
+ */
+/** The one required variable. Minted in Composer under Settings > Management keys. */
+export declare const KEY_VAR = "EBITEX_CONTENT_MANAGEMENT_KEY";
+/** Where the API lives. Only ever changed for a local AppHost or a self-hosted deployment. */
+export declare const BASE_VAR = "EBITEX_CONTENT_API_BASE";
+/**
+ * An operator's declaration that this session must not write, independent of what the key could do.
+ *
+ * It exists because a key's scopes are not readable: the credential carries no scope list, and no
+ * endpoint reports one (see DEV_PLAN's Open Questions). So "hide the write tools" cannot be derived
+ * from the key, and the honest alternatives are to advertise writes always — which sends an agent
+ * down paths that will `403` — or to let the operator say. This is the operator saying.
+ */
+export declare const READ_ONLY_VAR = "EBITEX_CONTENT_MCP_READ_ONLY";
+/** A second key, bound to the environment `content_transfer` imports *into*. */
+export declare const TARGET_KEY_VAR = "EBITEX_CONTENT_TARGET_MANAGEMENT_KEY";
+export declare const DEFAULT_BASE = "https://api.ebitex.io";
+export type ServerConfig = {
+    /** Origin only — `/content/management/v1` is appended by the client, never by a caller. */
+    baseUrl: string;
+    key: string;
+    /** Present only when {@link TARGET_KEY_VAR} is set; `content_transfer` is otherwise export-only. */
+    targetKey: string | null;
+    readOnly: boolean;
+};
+export declare class ConfigError extends Error {
+}
+/**
+ * Reads the configuration, or throws {@link ConfigError} with a message written for the person
+ * editing an MCP client's JSON — it names the variable and where to get its value, because that is
+ * the only thing they can act on.
+ */
+export declare function readConfig(env?: Record<string, string | undefined>): ServerConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sFAAsF;AACtF,eAAO,MAAM,OAAO,kCAAkC,CAAA;AAEtD,8FAA8F;AAC9F,eAAO,MAAM,QAAQ,4BAA4B,CAAA;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,iCAAiC,CAAA;AAE3D,gFAAgF;AAChF,eAAO,MAAM,cAAc,yCAAyC,CAAA;AAEpE,eAAO,MAAM,YAAY,0BAA0B,CAAA;AAEnD,MAAM,MAAM,YAAY,GAAG;IACzB,2FAA2F;IAC3F,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,oGAAoG;IACpG,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,YAAY,CAyB9F"}

package/dist/config.js

@@ -0,0 +1,62 @@
+/**
+ * Everything this server reads from its environment, in one place.
+ *
+ * An MCP server is launched by a host process with a config block, not by a person at a prompt, so
+ * a misconfiguration has no interactive moment in which to be noticed. That makes the failure mode
+ * the thing to design for: a missing key must stop the server at startup naming the variable, never
+ * surface later as a `401` on whatever tool the agent happened to call first. An agent reading a
+ * `401` will reasonably conclude the credential is wrong rather than absent, and will retry.
+ */
+/** The one required variable. Minted in Composer under Settings > Management keys. */
+export const KEY_VAR = 'EBITEX_CONTENT_MANAGEMENT_KEY';
+/** Where the API lives. Only ever changed for a local AppHost or a self-hosted deployment. */
+export const BASE_VAR = 'EBITEX_CONTENT_API_BASE';
+/**
+ * An operator's declaration that this session must not write, independent of what the key could do.
+ *
+ * It exists because a key's scopes are not readable: the credential carries no scope list, and no
+ * endpoint reports one (see DEV_PLAN's Open Questions). So "hide the write tools" cannot be derived
+ * from the key, and the honest alternatives are to advertise writes always — which sends an agent
+ * down paths that will `403` — or to let the operator say. This is the operator saying.
+ */
+export const READ_ONLY_VAR = 'EBITEX_CONTENT_MCP_READ_ONLY';
+/** A second key, bound to the environment `content_transfer` imports *into*. */
+export const TARGET_KEY_VAR = 'EBITEX_CONTENT_TARGET_MANAGEMENT_KEY';
+export const DEFAULT_BASE = 'https://api.ebitex.io';
+export class ConfigError extends Error {
+}
+/**
+ * Reads the configuration, or throws {@link ConfigError} with a message written for the person
+ * editing an MCP client's JSON — it names the variable and where to get its value, because that is
+ * the only thing they can act on.
+ */
+export function readConfig(env = process.env) {
+    const key = env[KEY_VAR]?.trim();
+    if (!key) {
+        throw new ConfigError(`${KEY_VAR} is not set. Mint a Content management key in Composer ` +
+            '(Settings > Management keys) and set it in this server\'s "env" block.');
+    }
+    const base = env[BASE_VAR]?.trim() || DEFAULT_BASE;
+    let baseUrl;
+    try {
+        // Normalizing here rather than at each call site means a trailing slash, a path, or a typo in
+        // the scheme is one error at startup instead of a puzzling 404 per tool.
+        baseUrl = new URL(base).origin;
+    }
+    catch {
+        throw new ConfigError(`${BASE_VAR} is not a valid URL: ${base}`);
+    }
+    return {
+        baseUrl,
+        key,
+        targetKey: env[TARGET_KEY_VAR]?.trim() || null,
+        readOnly: isTruthy(env[READ_ONLY_VAR]),
+    };
+}
+function isTruthy(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,OAAO,GAAG,+BAA+B,CAAA;AAEtD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,QAAQ,GAAG,yBAAyB,CAAA;AAEjD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,8BAA8B,CAAA;AAE3D,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAG,sCAAsC,CAAA;AAEpE,MAAM,CAAC,MAAM,YAAY,GAAG,uBAAuB,CAAA;AAWnD,MAAM,OAAO,WAAY,SAAQ,KAAK;CAAG;AAEzC;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,MAA0C,OAAO,CAAC,GAAG;IAC9E,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAA;IAChC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,WAAW,CACnB,GAAG,OAAO,yDAAyD;YACjE,wEAAwE,CAC3E,CAAA;IACH,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,YAAY,CAAA;IAClD,IAAI,OAAe,CAAA;IACnB,IAAI,CAAC;QACH,8FAA8F;QAC9F,yEAAyE;QACzE,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAA;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CAAC,GAAG,QAAQ,wBAAwB,IAAI,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,OAAO;QACL,OAAO;QACP,GAAG;QACH,SAAS,EAAE,GAAG,CAAC,cAAc,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI;QAC9C,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;KACvC,CAAA;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,KAAyB;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IACxB,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAC7C,OAAO,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,KAAK,CAAA;AAC5E,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * How a refusal from the API reaches the agent — SPEC.md's Business Logic §3.
+ *
+ * The rule is that the error **is** the control loop. An agent works by try → read the error → fix,
+ * and that loop only closes if the error still says what to change. Content's per-entity write
+ * refuses an invalid document with the failing field's path and message; a bundle import names every
+ * invalid item. So this module's entire job is to lose none of that.
+ *
+ * Concretely, it does **not** branch on the error code, and that is deliberate rather than lazy:
+ * `apps/content-web/src/lib/contentApi.ts` has a large switch mapping each code to a friendly
+ * sentence, which is right for a person looking at a form and wrong here twice over — it discards
+ * the field paths a program needs, and it goes stale the first time the API adds a code (that file
+ * has had exactly that bug, twice, where an unmapped code fell through to a branch that dropped the
+ * body entirely). Emitting the whole body cannot go stale, because it makes no claim about shape.
+ *
+ * One shaping *is* applied, and only one: the body is pretty-printed. That changes no content.
+ */
+/** A non-2xx response, carrying everything the server said about it. */
+export declare class ContentApiError extends Error {
+    readonly status: number;
+    /** The API's own `error` code when the body carries one — `validation_failed`, `scope_denied`, … */
+    readonly code: string | null;
+    /** The parsed body, or the raw text when it was not JSON (a proxy's HTML error page, say). */
+    readonly body: unknown;
+    constructor(status: number, code: string | null, body: unknown, message: string);
+}
+/**
+ * Builds the error from a response, reading the body once.
+ *
+ * A body that is not JSON is kept as text rather than discarded: when something in front of the API
+ * answers (a proxy timeout, a WAF), that text is the only evidence of what happened, and an empty
+ * error would send the agent looking at its own request.
+ */
+export declare function toContentApiError(response: Response): Promise<ContentApiError>;
+/**
+ * The text an agent actually reads.
+ *
+ * Line one is the status and the API's own code, so the machine-readable identity is never buried.
+ * Everything after it is the body, verbatim. No summary, no count, no "and 3 more" — an elision
+ * here would remove exactly the field the next call has to set.
+ */
+export declare function describe(status: number, code: string | null, body: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;gBAEV,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM;CAOhF;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,eAAe,CAAC,CAiBpF;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAMnF"}

package/dist/errors.js

@@ -0,0 +1,82 @@
+/**
+ * How a refusal from the API reaches the agent — SPEC.md's Business Logic §3.
+ *
+ * The rule is that the error **is** the control loop. An agent works by try → read the error → fix,
+ * and that loop only closes if the error still says what to change. Content's per-entity write
+ * refuses an invalid document with the failing field's path and message; a bundle import names every
+ * invalid item. So this module's entire job is to lose none of that.
+ *
+ * Concretely, it does **not** branch on the error code, and that is deliberate rather than lazy:
+ * `apps/content-web/src/lib/contentApi.ts` has a large switch mapping each code to a friendly
+ * sentence, which is right for a person looking at a form and wrong here twice over — it discards
+ * the field paths a program needs, and it goes stale the first time the API adds a code (that file
+ * has had exactly that bug, twice, where an unmapped code fell through to a branch that dropped the
+ * body entirely). Emitting the whole body cannot go stale, because it makes no claim about shape.
+ *
+ * One shaping *is* applied, and only one: the body is pretty-printed. That changes no content.
+ */
+/** A non-2xx response, carrying everything the server said about it. */
+export class ContentApiError extends Error {
+    status;
+    /** The API's own `error` code when the body carries one — `validation_failed`, `scope_denied`, … */
+    code;
+    /** The parsed body, or the raw text when it was not JSON (a proxy's HTML error page, say). */
+    body;
+    constructor(status, code, body, message) {
+        super(message);
+        this.name = 'ContentApiError';
+        this.status = status;
+        this.code = code;
+        this.body = body;
+    }
+}
+/**
+ * Builds the error from a response, reading the body once.
+ *
+ * A body that is not JSON is kept as text rather than discarded: when something in front of the API
+ * answers (a proxy timeout, a WAF), that text is the only evidence of what happened, and an empty
+ * error would send the agent looking at its own request.
+ */
+export async function toContentApiError(response) {
+    const text = await response.text().catch(() => '');
+    let body = text;
+    let code = null;
+    if (text) {
+        try {
+            body = JSON.parse(text);
+            if (body && typeof body === 'object' && typeof body.error === 'string') {
+                code = body.error;
+            }
+        }
+        catch {
+            // Not JSON. `body` stays the raw text.
+        }
+    }
+    return new ContentApiError(response.status, code, body, describe(response.status, code, body));
+}
+/**
+ * The text an agent actually reads.
+ *
+ * Line one is the status and the API's own code, so the machine-readable identity is never buried.
+ * Everything after it is the body, verbatim. No summary, no count, no "and 3 more" — an elision
+ * here would remove exactly the field the next call has to set.
+ */
+export function describe(status, code, body) {
+    const heading = code ? `HTTP ${status} ${code}` : `HTTP ${status}`;
+    if (body === undefined || body === null || body === '')
+        return heading;
+    const rendered = typeof body === 'string' ? body : safeStringify(body);
+    return `${heading}\n${rendered}`;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        // A cycle cannot occur in a parsed JSON body, but stringify can still throw on a BigInt. Saying
+        // so beats throwing while reporting an error, which would replace a useful message with a
+        // useless one.
+        return String(value);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,wEAAwE;AACxE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,MAAM,CAAQ;IACvB,oGAAoG;IAC3F,IAAI,CAAe;IAC5B,8FAA8F;IACrF,IAAI,CAAS;IAEtB,YAAY,MAAc,EAAE,IAAmB,EAAE,IAAa,EAAE,OAAe;QAC7E,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAkB;IACxD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IAElD,IAAI,IAAI,GAAY,IAAI,CAAA;IACxB,IAAI,IAAI,GAAkB,IAAI,CAAA;IAC9B,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACvB,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAQ,IAA4B,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAChG,IAAI,GAAI,IAA0B,CAAC,KAAK,CAAA;YAC1C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uCAAuC;QACzC,CAAC;IACH,CAAC;IAED,OAAO,IAAI,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;AAChG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,IAAmB,EAAE,IAAa;IACzE,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,MAAM,EAAE,CAAA;IAClE,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,OAAO,CAAA;IAEtE,MAAM,QAAQ,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAA;IACtE,OAAO,GAAG,OAAO,KAAK,QAAQ,EAAE,CAAA;AAClC,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,gGAAgG;QAChG,0FAA0F;QAC1F,eAAe;QACf,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The library entry point, for embedding this server in a host that owns its own transport.
+ *
+ * The ordinary way to use this package is the `ebitex-content-mcp` executable, configured in an MCP
+ * client. This export exists so a host that already has a transport (an in-process client, an HTTP
+ * bridge) can build the same server without going through a child process.
+ */
+export { buildServer, startupBanner, SERVER_NAME, SERVER_VERSION, type BuiltServer } from './server.js';
+export { readConfig, ConfigError, type ServerConfig } from './config.js';
+export { resolveSession, StartupError, type Session, type WhoAmI } from './session.js';
+export { createClient, type ContentClient } from './client.js';
+export { ContentApiError } from './errors.js';
+export { WRITABLE_KINDS, isEntityKind, routesFor, type EntityKind } from './routes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AACvG,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAA;AACtF,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * The library entry point, for embedding this server in a host that owns its own transport.
+ *
+ * The ordinary way to use this package is the `ebitex-content-mcp` executable, configured in an MCP
+ * client. This export exists so a host that already has a transport (an in-process client, an HTTP
+ * bridge) can build the same server without going through a child process.
+ */
+export { buildServer, startupBanner, SERVER_NAME, SERVER_VERSION } from './server.js';
+export { readConfig, ConfigError } from './config.js';
+export { resolveSession, StartupError } from './session.js';
+export { createClient } from './client.js';
+export { ContentApiError } from './errors.js';
+export { WRITABLE_KINDS, isEntityKind, routesFor } from './routes.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAoB,MAAM,aAAa,CAAA;AACvG,OAAO,EAAE,UAAU,EAAE,WAAW,EAAqB,MAAM,aAAa,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,YAAY,EAA6B,MAAM,cAAc,CAAA;AACtF,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAmB,MAAM,aAAa,CAAA"}

package/dist/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":""}

package/dist/main.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ConfigError } from './config.js';
+import { buildServer } from './server.js';
+import { StartupError } from './session.js';
+/**
+ * The published `ebitex-content-mcp` executable. `package.json`'s `bin` points at this module's
+ * compiled output; TypeScript preserves the leading `#!` verbatim on emit, so there is no separate
+ * untyped shim.
+ *
+ * Kept to process concerns only — starting, failing, exiting — with everything testable living in
+ * `server.ts`.
+ *
+ * **Everything diagnostic goes to stderr.** On a stdio transport, stdout *is* the protocol: a single
+ * stray `console.log` corrupts the JSON-RPC stream and the client reports a parse error rather than
+ * whatever was printed. That is the one rule to remember when adding anything to this file.
+ */
+async function main() {
+    const { server, banner } = await buildServer();
+    console.error(banner);
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    // A configuration or startup failure is something a person can fix in a config file, so it is
+    // printed as its message alone — a stack trace here would bury the one line that matters.
+    // Anything else is a real fault and keeps its stack.
+    if (error instanceof ConfigError || error instanceof StartupError) {
+        console.error(error.message);
+    }
+    else {
+        console.error(error);
+    }
+    process.exit(1);
+});
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +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"}

package/dist/resources/helpCorpus.generated.d.ts

@@ -0,0 +1,7 @@
+export type HelpTopic = {
+    slug: string;
+    title: string;
+    body: string;
+};
+export declare const HELP_TOPICS: HelpTopic[];
+//# sourceMappingURL=helpCorpus.generated.d.ts.map

package/dist/resources/helpCorpus.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpCorpus.generated.d.ts","sourceRoot":"","sources":["../../src/resources/helpCorpus.generated.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAErE,eAAO,MAAM,WAAW,EAAE,SAAS,EA0GlC,CAAA"}