@ebitex/content-mcp 0.1.0

package/dist/routes.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The `kind`-to-route table — SPEC.md's Business Logic §9.
+ *
+ * **This is the only content-model knowledge this server holds, and it is not much: which URL a
+ * kind lives at.** It knows nothing about what a Contract may contain, what field types exist, or
+ * what makes a document valid. Those are answered at runtime by the API (`content_describe` for the
+ * first two, the write's own response for the third), which is what makes this server unable to
+ * drift from the product — there is no second copy of the model here to fall out of step.
+ *
+ * The table is worth reading carefully, because a reader who assumed a uniform `POST /{kind}` /
+ * `PUT /{kind}/{id}` shape would get four things wrong, all found by checking the routes as mapped
+ * rather than by reading endpoint file names:
+ *
+ *  - **An Adapter updates with `PATCH`.** Every other family takes `PUT`. `PUT /adapters/{id}` does
+ *    not exist, so assuming uniformity builds clean and answers `405` at run time — on the one
+ *    family whose mapping canvas is the hardest thing an agent will try to author.
+ *  - **A node's payload is its own route**, so it is its own kind. `PUT /experience/nodes/{id}`
+ *    carries identity and location and *not* the payload; folding them together would put a silent
+ *    no-op behind a successful write, which is worse than a refusal.
+ *  - **A site is not a node.** `POST /experience/sites` creates a root; a page under it is a
+ *    separate call to `/experience/nodes`.
+ *  - **The surface is not uniformly CRUD.** Folders, audiences, sites and both taxonomy kinds have
+ *    no single-entity `GET` at all — they are read by listing. `readOne: null` records that rather
+ *    than inventing a route that would 404.
+ *
+ * Anything not in this table is not reachable by this server, and that is the same default-closed
+ * posture the server's own allow-list takes (`ContentManagementRouteScopes.RequiredScope` returns
+ * null for an unknown segment, which the filter treats as a refusal). Workflow, providers,
+ * environments, promotion and credential minting have no row because spec #641 admits none of them.
+ */
+export declare const WRITABLE_KINDS: readonly ["contract", "template", "component", "folder", "site", "node", "nodePayload", "adapter", "stream", "audience", "categoryGroup", "category"];
+export type EntityKind = (typeof WRITABLE_KINDS)[number];
+export type KindRoutes = {
+    /** What this kind is called in prose, for messages an agent reads. */
+    label: string;
+    /** `POST` target, or null where the kind cannot be created on its own (a node's payload). */
+    create: string | null;
+    /** Path template for update/delete/read, `{id}` substituted. Null where the verb does not exist. */
+    update: {
+        method: 'PUT' | 'PATCH';
+        path: string;
+    } | null;
+    remove: string | null;
+    /** Single-entity `GET`, or null for a family that is only listable. */
+    readOne: string | null;
+    /** Listing route, which is also how a `readOne: null` kind is read. */
+    list: string | null;
+};
+export declare function isEntityKind(value: string): value is EntityKind;
+export declare function routesFor(kind: EntityKind): KindRoutes;
+/**
+ * Substitutes `{id}` in a path template.
+ *
+ * Encoded, because every id here is a Guid today and will not always be — a stream is addressable by
+ * external id on the delivery side already, and an id that ever carries a slash would otherwise
+ * silently change which route was matched.
+ */
+export declare function withId(template: string, id: string): string;
+/**
+ * The message a kind this server cannot reach gets.
+ *
+ * It answers locally rather than sending the request to earn a `404`, because the `404` says only
+ * "no such route" — it does not say which kinds *are* writable, which is the one thing that gets the
+ * agent to its next call. This is the same instinct as §3's verbatim relay pointed the other way:
+ * be transparent about what the server knows, and say nothing it does not.
+ */
+export declare function unknownKindMessage(kind: string): string;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,eAAO,MAAM,cAAc,uJAajB,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,MAAM,MAAM,UAAU,GAAG;IACvB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,6FAA6F;IAC7F,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,oGAAoG;IACpG,MAAM,EAAE;QAAE,MAAM,EAAE,KAAK,GAAG,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACxD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,uEAAuE;IACvE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,uEAAuE;IACvE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB,CAAA;AAsGD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAEtD;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMvD"}

package/dist/routes.js

@@ -0,0 +1,173 @@
+/**
+ * The `kind`-to-route table — SPEC.md's Business Logic §9.
+ *
+ * **This is the only content-model knowledge this server holds, and it is not much: which URL a
+ * kind lives at.** It knows nothing about what a Contract may contain, what field types exist, or
+ * what makes a document valid. Those are answered at runtime by the API (`content_describe` for the
+ * first two, the write's own response for the third), which is what makes this server unable to
+ * drift from the product — there is no second copy of the model here to fall out of step.
+ *
+ * The table is worth reading carefully, because a reader who assumed a uniform `POST /{kind}` /
+ * `PUT /{kind}/{id}` shape would get four things wrong, all found by checking the routes as mapped
+ * rather than by reading endpoint file names:
+ *
+ *  - **An Adapter updates with `PATCH`.** Every other family takes `PUT`. `PUT /adapters/{id}` does
+ *    not exist, so assuming uniformity builds clean and answers `405` at run time — on the one
+ *    family whose mapping canvas is the hardest thing an agent will try to author.
+ *  - **A node's payload is its own route**, so it is its own kind. `PUT /experience/nodes/{id}`
+ *    carries identity and location and *not* the payload; folding them together would put a silent
+ *    no-op behind a successful write, which is worse than a refusal.
+ *  - **A site is not a node.** `POST /experience/sites` creates a root; a page under it is a
+ *    separate call to `/experience/nodes`.
+ *  - **The surface is not uniformly CRUD.** Folders, audiences, sites and both taxonomy kinds have
+ *    no single-entity `GET` at all — they are read by listing. `readOne: null` records that rather
+ *    than inventing a route that would 404.
+ *
+ * Anything not in this table is not reachable by this server, and that is the same default-closed
+ * posture the server's own allow-list takes (`ContentManagementRouteScopes.RequiredScope` returns
+ * null for an unknown segment, which the filter treats as a refusal). Workflow, providers,
+ * environments, promotion and credential minting have no row because spec #641 admits none of them.
+ */
+export const WRITABLE_KINDS = [
+    'contract',
+    'template',
+    'component',
+    'folder',
+    'site',
+    'node',
+    'nodePayload',
+    'adapter',
+    'stream',
+    'audience',
+    'categoryGroup',
+    'category',
+];
+const ROUTES = {
+    contract: {
+        label: 'Contract',
+        create: '/contracts',
+        update: { method: 'PUT', path: '/contracts/{id}' },
+        remove: '/contracts/{id}',
+        readOne: '/contracts/{id}',
+        list: '/contracts',
+    },
+    template: {
+        label: 'Template',
+        create: '/templates',
+        update: { method: 'PUT', path: '/templates/{id}' },
+        remove: '/templates/{id}',
+        readOne: '/templates/{id}',
+        list: '/templates',
+    },
+    component: {
+        label: 'Component',
+        create: '/components',
+        update: { method: 'PUT', path: '/components/{id}' },
+        remove: '/components/{id}',
+        readOne: '/components/{id}',
+        list: '/components',
+    },
+    folder: {
+        label: 'Folder',
+        create: '/folders',
+        update: { method: 'PUT', path: '/folders/{id}' },
+        remove: '/folders/{id}',
+        readOne: null,
+        list: '/folders',
+    },
+    site: {
+        label: 'Site (an Experience root)',
+        create: '/experience/sites',
+        update: null,
+        remove: null,
+        readOne: null,
+        list: '/experience/sites',
+    },
+    node: {
+        label: 'Experience node (a page)',
+        create: '/experience/nodes',
+        update: { method: 'PUT', path: '/experience/nodes/{id}' },
+        remove: '/experience/nodes/{id}',
+        readOne: '/experience/nodes/{id}',
+        list: null,
+    },
+    nodePayload: {
+        label: "An Experience node's payload (what it renders)",
+        create: null,
+        update: { method: 'PUT', path: '/experience/nodes/{id}/payload' },
+        remove: '/experience/nodes/{id}/payload',
+        readOne: null,
+        list: null,
+    },
+    adapter: {
+        label: 'Adapter (a field mapping)',
+        create: '/adapters',
+        // PATCH, not PUT. See this file's own header.
+        update: { method: 'PATCH', path: '/adapters/{id}' },
+        remove: '/adapters/{id}',
+        readOne: '/adapters/{id}',
+        list: '/adapters',
+    },
+    stream: {
+        label: 'Stream (a saved query over published content)',
+        create: '/streams',
+        update: { method: 'PUT', path: '/streams/{id}' },
+        remove: '/streams/{id}',
+        readOne: '/streams/{id}',
+        list: '/streams',
+    },
+    audience: {
+        label: 'Audience (a personalization segment)',
+        create: '/audiences',
+        update: { method: 'PUT', path: '/audiences/{id}' },
+        remove: '/audiences/{id}',
+        readOne: null,
+        list: '/audiences',
+    },
+    categoryGroup: {
+        label: 'Category group',
+        create: '/taxonomy/groups',
+        update: { method: 'PUT', path: '/taxonomy/groups/{id}' },
+        remove: '/taxonomy/groups/{id}',
+        readOne: null,
+        list: '/taxonomy/groups',
+    },
+    category: {
+        label: 'Category',
+        create: '/taxonomy/categories',
+        update: { method: 'PUT', path: '/taxonomy/categories/{id}' },
+        remove: '/taxonomy/categories/{id}',
+        readOne: null,
+        list: null,
+    },
+};
+export function isEntityKind(value) {
+    return Object.hasOwn(ROUTES, value);
+}
+export function routesFor(kind) {
+    return ROUTES[kind];
+}
+/**
+ * Substitutes `{id}` in a path template.
+ *
+ * Encoded, because every id here is a Guid today and will not always be — a stream is addressable by
+ * external id on the delivery side already, and an id that ever carries a slash would otherwise
+ * silently change which route was matched.
+ */
+export function withId(template, id) {
+    return template.replace('{id}', encodeURIComponent(id));
+}
+/**
+ * The message a kind this server cannot reach gets.
+ *
+ * It answers locally rather than sending the request to earn a `404`, because the `404` says only
+ * "no such route" — it does not say which kinds *are* writable, which is the one thing that gets the
+ * agent to its next call. This is the same instinct as §3's verbatim relay pointed the other way:
+ * be transparent about what the server knows, and say nothing it does not.
+ */
+export function unknownKindMessage(kind) {
+    return (`Unknown kind "${kind}". This server can write: ${WRITABLE_KINDS.join(', ')}.\n` +
+        'Workflows, providers, environments, promotion and credential minting are deliberately not ' +
+        'reachable with a management key.');
+}
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,32 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ServerConfig } from './config.js';
+import { type Session } from './session.js';
+/**
+ * Assembly. Nothing here decides anything — which tools exist is decided by the key's own scopes
+ * (`session.has`), and which routes exist is decided by `routes.ts`. This file only wires them.
+ */
+export declare const SERVER_NAME = "ebitex-content";
+/** Kept in step with `package.json` by the build; reported in the MCP handshake. */
+export declare const SERVER_VERSION = "0.1.0";
+export type BuiltServer = {
+    server: McpServer;
+    session: Session;
+    /** What to print to stderr before connecting — see {@link startupBanner}. */
+    banner: string;
+};
+export declare function buildServer(options?: {
+    config?: ServerConfig;
+    fetchImpl?: typeof fetch;
+}): Promise<BuiltServer>;
+/**
+ * What the operator sees on stderr at startup.
+ *
+ * It exists for one failure, and it is not a bug in this server: a key bound to a production
+ * authoring environment sitting in an MCP client's config file, with an agent doing exactly what it
+ * was asked to. This server cannot detect that — whether an environment is "production" is the
+ * customer's own topology, and a management key deliberately cannot see it — so saying plainly
+ * where writes will land is the whole mitigation, and it is why it names the environment rather
+ * than only reporting that the key worked.
+ */
+export declare function startupBanner(config: ServerConfig, session: Session): string;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAE3D,OAAO,EAAmC,KAAK,OAAO,EAAE,MAAM,cAAc,CAAA;AAG5E;;;GAGG;AAEH,eAAO,MAAM,WAAW,mBAAmB,CAAA;AAE3C,oFAAoF;AACpF,eAAO,MAAM,cAAc,UAAU,CAAA;AAErC,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,SAAS,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED,wBAAsB,WAAW,CAAC,OAAO,CAAC,EAAE;IAC1C,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB,GAAG,OAAO,CAAC,WAAW,CAAC,CA4BvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAoB5E"}

package/dist/server.js

@@ -0,0 +1,65 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { createClient } from './client.js';
+import { readConfig } from './config.js';
+import { registerResources } from './resources/register.js';
+import { resolveSession, SCOPE_AUTHORING } from './session.js';
+import { registerTools } from './tools/register.js';
+/**
+ * Assembly. Nothing here decides anything — which tools exist is decided by the key's own scopes
+ * (`session.has`), and which routes exist is decided by `routes.ts`. This file only wires them.
+ */
+export const SERVER_NAME = 'ebitex-content';
+/** Kept in step with `package.json` by the build; reported in the MCP handshake. */
+export const SERVER_VERSION = '0.1.0';
+export async function buildServer(options) {
+    const config = options?.config ?? readConfig();
+    const client = createClient({ baseUrl: config.baseUrl, key: config.key, fetchImpl: options?.fetchImpl });
+    const target = config.targetKey
+        ? createClient({ baseUrl: config.baseUrl, key: config.targetKey, fetchImpl: options?.fetchImpl })
+        : null;
+    const session = await resolveSession(client, { readOnlyRequested: config.readOnly });
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        instructions: 'Content is ebitex\'s CMS. Start with content_describe — it returns every field type with ' +
+            'its own settings schema and the Contracts and Templates this environment already has, ' +
+            'which is where the shape of anything you write comes from. Read the ' +
+            'ebitex-content://help/agent-authoring resource before building a model; it explains what ' +
+            'Contracts, Templates, Presentations, Adapters and the Experience tree are for, and the ' +
+            'order to create them in. When a write is refused, the refusal names the failing field: ' +
+            'correct that one thing and call again.',
+    });
+    registerTools(server, { client, session, target });
+    registerResources(server, { client, session });
+    return { server, session, banner: startupBanner(config, session) };
+}
+/**
+ * What the operator sees on stderr at startup.
+ *
+ * It exists for one failure, and it is not a bug in this server: a key bound to a production
+ * authoring environment sitting in an MCP client's config file, with an agent doing exactly what it
+ * was asked to. This server cannot detect that — whether an environment is "production" is the
+ * customer's own topology, and a management key deliberately cannot see it — so saying plainly
+ * where writes will land is the whole mitigation, and it is why it names the environment rather
+ * than only reporting that the key worked.
+ */
+export function startupBanner(config, session) {
+    const { who } = session;
+    const lines = [
+        'ebitex Content MCP',
+        `  api           ${config.baseUrl}`,
+        `  organization  ${who.organizationName ?? who.organizationId}`,
+        `  environment   ${who.environmentName ?? who.environmentId}`,
+        `  acting as     ${who.roleName ?? 'unknown role'}  (key: ${who.keyName ?? 'unnamed'})`,
+        `  scopes        ${who.scopes.length ? who.scopes.join(', ') : 'none'}`,
+    ];
+    if (config.readOnly) {
+        lines.push('  mode          read-only (forced by EBITEX_CONTENT_MCP_READ_ONLY)');
+    }
+    else if (session.has(SCOPE_AUTHORING)) {
+        lines.push(`  mode          READ-WRITE — writes land in "${who.environmentName ?? who.environmentId}"`);
+    }
+    else {
+        lines.push('  mode          read-only (this key carries no authoring scope)');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,45 @@
+import type { ContentClient } from './client.js';
+/**
+ * Who this key is, resolved once at startup from `GET /whoami` — SPEC.md's Business Logic §4 and §6.
+ *
+ * Two things depend on it, and they are the reason that endpoint was added by this spec rather than
+ * worked around:
+ *
+ *  - **Which tools exist at all.** A key's scopes decide what it may do, and an agent that cannot
+ *    see a tool will not plan around it. Advertising a write tool a read-scoped key holds is an
+ *    expensive way to learn something knowable before the session began — the agent spends a turn,
+ *    reads a `403`, and has to re-plan.
+ *  - **Where writes are landing.** The realistic failure of a write-capable agent tool is not a bug
+ *    in it; it is a key bound to a production environment sitting in a config file somebody else
+ *    wrote. The server cannot detect that (see §6 — production-ness is the customer's own topology,
+ *    and #641 deliberately keeps the environments family off a key), so the mitigation is to say
+ *    plainly what the key is bound to, at startup and on every write.
+ */
+export declare const SCOPE_READ = "content.management.read";
+export declare const SCOPE_WRITE = "content.management.write";
+export declare const SCOPE_PUBLISH = "content.management.publish";
+export declare const SCOPE_AUTHORING = "content.management.authoring";
+export type WhoAmI = {
+    organizationId: string;
+    organizationName: string | null;
+    organizationSlug: string | null;
+    environmentId: string;
+    environmentName: string | null;
+    roleName: string | null;
+    keyName: string | null;
+    scopes: string[];
+};
+export type Session = {
+    who: WhoAmI;
+    /** True when the operator forced read-only regardless of what the key could do. */
+    readOnlyRequested: boolean;
+    has(scope: string): boolean;
+    /** One line naming where a write just landed, appended to every write result (§6). */
+    contextLine(): string;
+};
+export declare class StartupError extends Error {
+}
+export declare function resolveSession(client: ContentClient, options: {
+    readOnlyRequested: boolean;
+}): Promise<Session>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAGhD;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,UAAU,4BAA4B,CAAA;AACnD,eAAO,MAAM,WAAW,6BAA6B,CAAA;AACrD,eAAO,MAAM,aAAa,+BAA+B,CAAA;AACzD,eAAO,MAAM,eAAe,iCAAiC,CAAA;AAE7D,MAAM,MAAM,MAAM,GAAG;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,OAAO,GAAG;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,mFAAmF;IACnF,iBAAiB,EAAE,OAAO,CAAA;IAC1B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;IAC3B,sFAAsF;IACtF,WAAW,IAAI,MAAM,CAAA;CACtB,CAAA;AAED,qBAAa,YAAa,SAAQ,KAAK;CAAG;AAE1C,wBAAsB,cAAc,CAClC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE;IAAE,iBAAiB,EAAE,OAAO,CAAA;CAAE,GACtC,OAAO,CAAC,OAAO,CAAC,CAmBlB"}

package/dist/session.js

@@ -0,0 +1,71 @@
+import { ContentApiError } from './errors.js';
+/**
+ * Who this key is, resolved once at startup from `GET /whoami` — SPEC.md's Business Logic §4 and §6.
+ *
+ * Two things depend on it, and they are the reason that endpoint was added by this spec rather than
+ * worked around:
+ *
+ *  - **Which tools exist at all.** A key's scopes decide what it may do, and an agent that cannot
+ *    see a tool will not plan around it. Advertising a write tool a read-scoped key holds is an
+ *    expensive way to learn something knowable before the session began — the agent spends a turn,
+ *    reads a `403`, and has to re-plan.
+ *  - **Where writes are landing.** The realistic failure of a write-capable agent tool is not a bug
+ *    in it; it is a key bound to a production environment sitting in a config file somebody else
+ *    wrote. The server cannot detect that (see §6 — production-ness is the customer's own topology,
+ *    and #641 deliberately keeps the environments family off a key), so the mitigation is to say
+ *    plainly what the key is bound to, at startup and on every write.
+ */
+export const SCOPE_READ = 'content.management.read';
+export const SCOPE_WRITE = 'content.management.write';
+export const SCOPE_PUBLISH = 'content.management.publish';
+export const SCOPE_AUTHORING = 'content.management.authoring';
+export class StartupError extends Error {
+}
+export async function resolveSession(client, options) {
+    let who;
+    try {
+        who = (await client.request('GET', '/whoami'));
+    }
+    catch (error) {
+        throw new StartupError(startupMessage(error, client.baseUrl));
+    }
+    const scopes = new Set(who.scopes ?? []);
+    return {
+        who,
+        readOnlyRequested: options.readOnlyRequested,
+        // A forced read-only session reports every write scope as absent, so tool registration —
+        // which asks this and nothing else — needs no second concept of "but the operator said no".
+        has: (scope) => (options.readOnlyRequested && isWriteScope(scope) ? false : scopes.has(scope)),
+        contextLine: () => `[${who.organizationName ?? who.organizationId} · ${who.environmentName ?? who.environmentId} · as ${who.roleName ?? 'unknown role'}]`,
+    };
+}
+function isWriteScope(scope) {
+    return scope === SCOPE_WRITE || scope === SCOPE_PUBLISH || scope === SCOPE_AUTHORING;
+}
+/**
+ * What a failed startup says.
+ *
+ * Each arm names a **different remedy**, which is the only reason to distinguish them at all: a
+ * `401` means the key string is wrong, a `403 tier_required` means nothing about the key is wrong
+ * and somebody has to change the plan, and a `404` means this API predates `/whoami` entirely.
+ * Collapsing them into "could not connect" would leave the reader guessing between three unrelated
+ * actions.
+ */
+function startupMessage(error, baseUrl) {
+    if (!(error instanceof ContentApiError)) {
+        return (`Could not reach the Content Management API at ${baseUrl}.\n` +
+            (error instanceof Error ? error.message : String(error)));
+    }
+    if (error.status === 401) {
+        return `The Content management key was not accepted by ${baseUrl} (${error.code ?? 'unauthorized'}).`;
+    }
+    if (error.status === 404) {
+        return (`${baseUrl} does not serve GET /content/management/v1/whoami, which this server needs in ` +
+            'order to know which organization and environment the key is bound to, and which tools to ' +
+            'offer. Upgrade the API, or point EBITEX_CONTENT_API_BASE at one that has it.');
+    }
+    // Everything else — tier, lapsed payment, the Content app not enabled, an IP allow-list — is a
+    // real refusal with a real message, and relaying it beats classifying it (§3).
+    return `The Content Management API refused this key.\n${error.message}`;
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,yBAAyB,CAAA;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,0BAA0B,CAAA;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,4BAA4B,CAAA;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,8BAA8B,CAAA;AAsB7D,MAAM,OAAO,YAAa,SAAQ,KAAK;CAAG;AAE1C,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAqB,EACrB,OAAuC;IAEvC,IAAI,GAAW,CAAA;IACf,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAW,CAAA;IAC1D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,YAAY,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;IAC/D,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAA;IAExC,OAAO;QACL,GAAG;QACH,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C,yFAAyF;QACzF,4FAA4F;QAC5F,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9F,WAAW,EAAE,GAAG,EAAE,CAChB,IAAI,GAAG,CAAC,gBAAgB,IAAI,GAAG,CAAC,cAAc,MAAM,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,aAAa,SAAS,GAAG,CAAC,QAAQ,IAAI,cAAc,GAAG;KACzI,CAAA;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,aAAa,IAAI,KAAK,KAAK,eAAe,CAAA;AACtF,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,KAAc,EAAE,OAAe;IACrD,IAAI,CAAC,CAAC,KAAK,YAAY,eAAe,CAAC,EAAE,CAAC;QACxC,OAAO,CACL,iDAAiD,OAAO,KAAK;YAC7D,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CACzD,CAAA;IACH,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACzB,OAAO,kDAAkD,OAAO,KAAK,KAAK,CAAC,IAAI,IAAI,cAAc,IAAI,CAAA;IACvG,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACzB,OAAO,CACL,GAAG,OAAO,gFAAgF;YAC1F,2FAA2F;YAC3F,8EAA8E,CAC/E,CAAA;IACH,CAAC;IAED,+FAA+F;IAC/F,+EAA+E;IAC/E,OAAO,iDAAiD,KAAK,CAAC,OAAO,EAAE,CAAA;AACzE,CAAC"}

package/dist/tools/register.d.ts

@@ -0,0 +1,26 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ContentClient } from '../client.js';
+import { type Session } from '../session.js';
+/**
+ * The eight tools — SPEC.md's Architecture table.
+ *
+ * They are **task-shaped**, not endpoint-shaped: one per thing an agent does, never one per REST
+ * route or per entity kind. With the per-entity surface admitted the API is roughly thirty endpoint
+ * groups, so a generated one-tool-per-route surface would crowd an agent's context with dozens of
+ * entries to express eight tasks — which is why §8 rejects generating from OpenAPI, and why the
+ * case against it got *stronger* as the API grew rather than weaker.
+ *
+ * The payloads are deliberately opaque. `content_write` takes a `kind` and an object, and this
+ * module has no idea what belongs in that object: the agent learns each Contract's shape from
+ * `content_describe` at runtime, and the server validates what arrives. A per-kind tool schema
+ * would be a second copy of the content model living here, stale the first time a FieldType ships —
+ * the precise drift §1 exists to prevent.
+ */
+export type ToolContext = {
+    client: ContentClient;
+    session: Session;
+    /** The credential for the environment `content_transfer` imports into, when one is configured. */
+    target: ContentClient | null;
+};
+export declare function registerTools(server: McpServer, context: ToolContext): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/tools/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/tools/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAExE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAGjD,OAAO,EAA2D,KAAK,OAAO,EAAE,MAAM,eAAe,CAAA;AAGrG;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,aAAa,CAAA;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;CAC7B,CAAA;AAID,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CA0R3E"}