@antasphere/chassis-server 1.0.0

package/dist/mcp/http.js

@@ -0,0 +1,80 @@
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import { HTTPException } from 'hono/http-exception';
+import { StreamableHTTPTransport } from '@hono/mcp';
+import { looksLikeJwt } from '../middleware/scopes.js';
+import { buildMcpServer } from './server.js';
+export function mcpRoutes(deps) {
+    const app = new Hono();
+    const challengeUrl = `${deps.publicBaseUrl.replace(/\/+$/, '')}/.well-known/oauth-protected-resource/mcp`;
+    app.use('*', deps.limiter);
+    // JSON-RPC bodies are small; cap them so a caller can't force the transport
+    // to buffer an arbitrarily large body (the /api/v1 cap does not cover /mcp).
+    app.use('*', bodyLimit({
+        maxSize: 1024 * 1024,
+        onError: (c) => c.json({ error: 'payload_too_large', error_description: 'MCP request body exceeds 1 MiB' }, 413)
+    }));
+    const unauthorized = (description) => new Response(JSON.stringify({ error: 'invalid_token', error_description: description }), {
+        status: 401,
+        headers: {
+            'content-type': 'application/json',
+            'www-authenticate': `Bearer resource_metadata="${challengeUrl}"`
+        }
+    });
+    app.post('/', async (c) => {
+        const authHeader = c.req.header('authorization')?.trim() ?? '';
+        const bearer = /^Bearer\s+(.+)$/i.exec(authHeader)?.[1]?.trim() ?? null;
+        if (!bearer) {
+            return unauthorized('Authentication required');
+        }
+        let principal = null;
+        if (deps.isApiKeyToken(bearer)) {
+            principal = await deps.resolveApiKey(bearer);
+        }
+        else if (looksLikeJwt(bearer)) {
+            principal = await deps.resolveOauthJwt(bearer);
+        }
+        if (!principal) {
+            return unauthorized('Bearer token is invalid, expired, or revoked');
+        }
+        const server = buildMcpServer({
+            fetchApi: deps.fetchApi,
+            principal,
+            authorizationHeader: `Bearer ${bearer}`,
+            publicBaseUrl: deps.publicBaseUrl
+        }, { version: deps.version, instanceName: await deps.instanceName() }, deps.tool, deps.identity);
+        // No sessionIdGenerator = stateless: every POST is self-contained.
+        // enableJsonResponse returns plain JSON bodies (no SSE), so the Response
+        // handed back to Hono is complete — no stream outlives the request,
+        // nothing to tear down (the per-request server + transport are
+        // unreferenced after this).
+        const transport = new StreamableHTTPTransport({ enableJsonResponse: true });
+        await server.connect(transport);
+        try {
+            const res = await transport.handleRequest(c);
+            return res ?? c.body(null, 204);
+        }
+        catch (cause) {
+            // The transport reports protocol failures by THROWING HTTPException
+            // (400 -32700 for a malformed / non-JSON-RPC body, 406/415 for header
+            // problems), each carrying a complete JSON-RPC error response. Return
+            // that response instead of letting the root onError turn it into a
+            // generic 500.
+            if (cause instanceof HTTPException) {
+                return cause.getResponse();
+            }
+            throw cause;
+        }
+    });
+    // Non-POST is rejected here EXPLICITLY (ADR 002): the stateless transport
+    // does NOT 405 on its own — its GET handler would happily open a long-lived
+    // server-initiated SSE stream, and DELETE would answer a session teardown.
+    // Neither exists in stateless mode, so every non-POST method gets
+    // 405 + Allow: POST with a JSON-RPC error envelope (the shape the official
+    // SDK expects and tolerates).
+    app.all('/', (c) => c.json({ jsonrpc: '2.0', error: { code: -32000, message: 'Method not allowed' }, id: null }, 405, {
+        allow: 'POST'
+    }));
+    return app;
+}
+//# sourceMappingURL=http.js.map

package/dist/mcp/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/mcp/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,cAAc,EAA4C,MAAM,aAAa,CAAC;AAgCvF,MAAM,UAAU,SAAS,CAAC,IAAiB;IACzC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,2CAA2C,CAAC;IAE1G,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,4EAA4E;IAC5E,6EAA6E;IAC7E,GAAG,CAAC,GAAG,CACL,GAAG,EACH,SAAS,CAAC;QACR,OAAO,EAAE,IAAI,GAAG,IAAI;QACpB,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CACb,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,gCAAgC,EAAE,EAAE,GAAG,CAAC;KACnG,CAAC,CACH,CAAC;IAEF,MAAM,YAAY,GAAG,CAAC,WAAmB,EAAE,EAAE,CAC3C,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,WAAW,EAAE,CAAC,EAAE;QACvF,MAAM,EAAE,GAAG;QACX,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,kBAAkB,EAAE,6BAA6B,YAAY,GAAG;SACjE;KACF,CAAC,CAAC;IAEL,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACxB,MAAM,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC/D,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,YAAY,CAAC,yBAAyB,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,SAAS,GAAqB,IAAI,CAAC;QACvC,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/B,SAAS,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAC/C,CAAC;aAAM,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,SAAS,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,YAAY,CAAC,8CAA8C,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,MAAM,GAAG,cAAc,CAC3B;YACE,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,SAAS;YACT,mBAAmB,EAAE,UAAU,MAAM,EAAE;YACvC,aAAa,EAAE,IAAI,CAAC,aAAa;SAClC,EACD,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC,YAAY,EAAE,EAAE,EAClE,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,QAAQ,CACd,CAAC;QACF,mEAAmE;QACnE,yEAAyE;QACzE,oEAAoE;QACpE,+DAA+D;QAC/D,4BAA4B;QAC5B,MAAM,SAAS,GAAG,IAAI,uBAAuB,CAAC,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;YAC7C,OAAO,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,oEAAoE;YACpE,sEAAsE;YACtE,sEAAsE;YACtE,mEAAmE;YACnE,eAAe;YACf,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;YAC7B,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,0EAA0E;IAC1E,4EAA4E;IAC5E,2EAA2E;IAC3E,kEAAkE;IAClE,2EAA2E;IAC3E,8BAA8B;IAC9B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CACjB,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE;QAChG,KAAK,EAAE,MAAM;KACd,CAAC,CACH,CAAC;IAEF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,8 @@
+export { ApiToolError, type ErrorHints, type ToolTextResult, deny, jsonText, mergeErrorHints, wrapToolErrors } from './errors.js';
+export { mcpRoutes } from './http.js';
+export { projectErrorHints, registerProjectTools } from './projects.js';
+export { registerTeamTools } from './teams.js';
+export { type McpInputs, mcpInputs } from './inputs.js';
+export { type McpIdentity, type McpServerInfo, type McpToolDefinition, buildMcpServer, composeErrorHints } from './server.js';
+export { type McpToolContext, callApi, createScopeCheck, fetchApiRaw, forWorkspace, pageQuery } from './tool-kit.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,IAAI,EACJ,QAAQ,EACR,eAAe,EACf,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,cAAc,EACd,iBAAiB,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,cAAc,EACnB,OAAO,EACP,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACV,MAAM,eAAe,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,8 @@
+export { ApiToolError, deny, jsonText, mergeErrorHints, wrapToolErrors } from './errors.js';
+export { mcpRoutes } from './http.js';
+export { projectErrorHints, registerProjectTools } from './projects.js';
+export { registerTeamTools } from './teams.js';
+export { mcpInputs } from './inputs.js';
+export { buildMcpServer, composeErrorHints } from './server.js';
+export { callApi, createScopeCheck, fetchApiRaw, forWorkspace, pageQuery } from './tool-kit.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAGZ,IAAI,EACJ,QAAQ,EACR,eAAe,EACf,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAkB,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAIL,cAAc,EACd,iBAAiB,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,OAAO,EACP,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACV,MAAM,eAAe,CAAC"}

package/dist/mcp/inputs.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { ToolIdentity } from '@antasphere/chassis-contract';
+/**
+ * The inputs every MCP tool of an instance shares, chassis tools and the
+ * tool's own alike: ONE definition, so the same argument reads the same in
+ * every tool of `tools/list`. The workspace input names `<toolPrefix>whoami`
+ * (the identity tool the chassis registers), hence a factory over the MCP half
+ * of the tool's identity. Build it once per server, next to `registerTools`.
+ */
+export declare function mcpInputs(identity: Pick<ToolIdentity['mcp'], 'toolPrefix'>): {
+    /** The per-call target workspace; omitted, the caller's default one. */
+    workspaceInput: z.ZodOptional<z.ZodUUID>;
+    /** The cursor of a paginated list, passed through to the API. */
+    cursorInput: z.ZodOptional<z.ZodString>;
+    /** The page size of a paginated list. */
+    limitInput: z.ZodOptional<z.ZodNumber>;
+};
+export type McpInputs = ReturnType<typeof mcpInputs>;
+//# sourceMappingURL=inputs.d.ts.map

package/dist/mcp/inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputs.d.ts","sourceRoot":"","sources":["../../src/mcp/inputs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAEvE,wEAAwE;;IAOxE,iEAAiE;;IAEjE,yCAAyC;;EAS5C;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC"}

package/dist/mcp/inputs.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+/**
+ * The inputs every MCP tool of an instance shares, chassis tools and the
+ * tool's own alike: ONE definition, so the same argument reads the same in
+ * every tool of `tools/list`. The workspace input names `<toolPrefix>whoami`
+ * (the identity tool the chassis registers), hence a factory over the MCP half
+ * of the tool's identity. Build it once per server, next to `registerTools`.
+ */
+export function mcpInputs(identity) {
+    return {
+        /** The per-call target workspace; omitted, the caller's default one. */
+        workspaceInput: z
+            .uuid()
+            .optional()
+            .describe(`Target organization (workspace id). Omit to use your default org — see ${identity.toolPrefix}whoami.`),
+        /** The cursor of a paginated list, passed through to the API. */
+        cursorInput: z.string().optional().describe('nextCursor from a previous page.'),
+        /** The page size of a paginated list. */
+        limitInput: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe('Page size (server max 100). Default 50.')
+    };
+}
+//# sourceMappingURL=inputs.js.map

package/dist/mcp/inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputs.js","sourceRoot":"","sources":["../../src/mcp/inputs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,QAAiD;IACzE,OAAO;QACL,wEAAwE;QACxE,cAAc,EAAE,CAAC;aACd,IAAI,EAAE;aACN,QAAQ,EAAE;aACV,QAAQ,CACP,0EAA0E,QAAQ,CAAC,UAAU,SAAS,CACvG;QACH,iEAAiE;QACjE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;QAC/E,yCAAyC;QACzC,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,GAAG,CAAC;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,yCAAyC,CAAC;KACvD,CAAC;AACJ,CAAC"}

package/dist/mcp/projects.d.ts

@@ -0,0 +1,31 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ErrorHints } from './errors.js';
+import { type McpScopes, type McpToolContext, type ScopeCheck } from './tool-kit.js';
+import type { McpIdentity } from './server.js';
+/**
+ * The project codes, turned from an API code into a sentence a model can act
+ * on, for the tool whose prefix is given: a hint that names a tool names it
+ * as it is registered (`<toolPrefix>list_project_members`), or the model
+ * follows it to a tool that does not exist. Merged into the instance's hint
+ * table (`mergeErrorHints`) so a refusal reads as words rather than as a
+ * code. The role a refusal needs is the message's, never assumed here: a
+ * tool's own route over a project may gate on `editor` where every chassis
+ * route gates on `manager`.
+ *
+ * Every key here is a code only the project routes answer. `not_found` is
+ * DELIBERATELY absent: it is the whole instance's code, a tool already words
+ * it for its own domain (and its hint wins, `buildMcpServer`), and a sentence
+ * about projects on the answer of every other 404 would be worse than none.
+ * The tiered answer is stated in the descriptions instead, where it belongs:
+ * a project you cannot read answers not found, so being refused is not proof
+ * that it exists.
+ */
+export declare function projectErrorHints(toolPrefix: string): ErrorHints;
+/**
+ * Register the eleven project tools on a server. Called by `buildMcpServer`
+ * after `<toolPrefix>whoami` and before the tool's own set, so `tools/list`
+ * keeps one stable order: the chassis examples, whoami, the projects, the
+ * tool's own.
+ */
+export declare function registerProjectTools(server: McpServer, ctx: McpToolContext, identity: McpIdentity, scopes: McpScopes, checkScope: ScopeCheck<string>, hints: ErrorHints): void;
+//# sourceMappingURL=projects.d.ts.map

package/dist/mcp/projects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/mcp/projects.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EAAkC,KAAK,UAAU,EAAuB,MAAM,aAAa,CAAC;AACnG,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA8C/C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CA8BhE;AAkCD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,cAAc,EACnB,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,EAC9B,KAAK,EAAE,UAAU,GAChB,IAAI,CAiUN"}

package/dist/mcp/projects.js

@@ -0,0 +1,315 @@
+import { z } from 'zod';
+import { PROJECT_METADATA_MAX_LENGTH, projectRoleSchema, projectsArchivedFilterSchema } from '@antasphere/chassis-contract';
+import { mcpInputs } from './inputs.js';
+import { deny, jsonText, wrapToolErrors } from './errors.js';
+import { callApi, forWorkspace, pageQuery } from './tool-kit.js';
+/**
+ * The eleven PROJECT tools, registered by the chassis beside
+ * `<toolPrefix>whoami` — a project is a chassis concept (a subgroup of a
+ * workspace with its own members and roles), so every tool an instance serves
+ * over it is the chassis', not a tool's. Each one is a thin shim over the
+ * instance's own /api/v1/projects called IN-PROCESS with the caller's bearer
+ * forwarded verbatim: no privileged path, no MCP-only endpoint, and the API's
+ * fail-closed scope allowlist plus the tiered project answer (404 before 403
+ * before 409) apply unchanged.
+ *
+ * The conventions of the set are the chassis' (server.ts): reads carry
+ * `readOnlyHint: true` and pre-check the read scope, writes describe
+ * themselves confirm-first and pre-check the write scope, and every tool
+ * takes the same optional `workspace` argument.
+ *
+ * Nothing here names a tool, a brand or a domain: the prefix arrives as
+ * `identity.toolPrefix` and the wire shapes are the contract's.
+ */
+/**
+ * What a project IS, in the words an agent that has never seen one needs. It
+ * opens every description in the set, so a model reading `tools/list` learns
+ * the concept once from whichever tool it looks at first.
+ */
+const WHAT_IS_A_PROJECT = 'A project is a subgroup of an organization (workspace): a named space with its own members, ' +
+    'used to group work and who may touch it.';
+/**
+ * The three roles, each containing the one before it. Written out wherever a
+ * role is chosen or shown, because the whole authorization story of the
+ * surface is in it.
+ */
+const ROLE_LADDER_BODY = '`viewer` reads the project and what is linked to it; `editor` may also write what is linked to ' +
+    'it; `manager` may also rename the project, archive it, and manage its members. An organization ' +
+    'owner or admin acts as a manager on every project.';
+const ROLE_LADDER = `Roles, each containing the one before it: ${ROLE_LADDER_BODY}`;
+/** How an archived project behaves, and the one way back. */
+const ARCHIVED_RULE = 'An archived project is out of the default list and read-only: every change is refused until it ' +
+    'is brought back. A project is never deleted.';
+/**
+ * The project codes, turned from an API code into a sentence a model can act
+ * on, for the tool whose prefix is given: a hint that names a tool names it
+ * as it is registered (`<toolPrefix>list_project_members`), or the model
+ * follows it to a tool that does not exist. Merged into the instance's hint
+ * table (`mergeErrorHints`) so a refusal reads as words rather than as a
+ * code. The role a refusal needs is the message's, never assumed here: a
+ * tool's own route over a project may gate on `editor` where every chassis
+ * route gates on `manager`.
+ *
+ * Every key here is a code only the project routes answer. `not_found` is
+ * DELIBERATELY absent: it is the whole instance's code, a tool already words
+ * it for its own domain (and its hint wins, `buildMcpServer`), and a sentence
+ * about projects on the answer of every other 404 would be worse than none.
+ * The tiered answer is stated in the descriptions instead, where it belongs:
+ * a project you cannot read answers not found, so being refused is not proof
+ * that it exists.
+ */
+export function projectErrorHints(toolPrefix) {
+    const t = (name) => `${toolPrefix}${name}`;
+    return {
+        insufficient_project_role: 'Your role on this project is below what this needs (the message names the role; the chassis ' +
+            'routes need manager). Ask a project manager, or an owner or admin of the organization, to make ' +
+            'the change or to raise your role.',
+        project_archived: 'This project is archived, so it is read-only. Bring it back first (archive the project with ' +
+            'archived set to false), then try again.',
+        project_not_archived: 'This project is not archived, so there is nothing to bring back.',
+        member_not_found: `No such member. On ${t('add_project_member')}: nobody in the organization matches, and a project ` +
+            'member must already be an active organization member, named by the exact user id or email ' +
+            `address they joined with. On ${t('set_project_member_role')} or ${t('remove_project_member')}: ` +
+            `this person is not on the project (${t('list_project_members')} shows who is).`,
+        already_member: 'This person or team is already a member of the project — change the role instead of adding ' +
+            'them again.',
+        team_not_found: `No such team. On ${t('add_project_member')}: no team of the organization has this id ` +
+            `(${t('list_teams')} lists them). On ${t('set_project_team_role')} or ${t('remove_project_team')}: ` +
+            `this team is not on the project (${t('list_project_members')} shows who is).`,
+        guest_target: 'This person is an external guest invited to one item: their account is not this organization’s ' +
+            'to put on a project.',
+        guest_forbidden: 'This credential is a guest of the organization, invited to one item only, and guests take no ' +
+            'part in projects: nothing under the project tools answers it. Use a member’s credential.'
+    };
+}
+/**
+ * A project is named by an opaque id, never by its name: two projects may
+ * share a name, and the API answers 404 to whoever cannot read one.
+ */
+const projectIdInput = z
+    .uuid()
+    .describe('The project id, from the list or the create answer (never the project name).');
+const teamIdInput = z
+    .uuid()
+    .describe('The team id, as the teams list or the project member list reports it (never its name or slug).');
+const userIdInput = z
+    .string()
+    .min(1)
+    .max(200)
+    .describe('The member’s user id, as the member list reports it.');
+const roleInput = projectRoleSchema.describe(`The role on this project. ${ROLE_LADDER_BODY}`);
+const nameInput = z.string().min(1).max(200).describe('The project name, as people will read it.');
+const descriptionInput = z.string().max(2000).describe('A sentence or two on what the project is for.');
+const metadataInput = z
+    .record(z.string(), z.unknown())
+    .describe('Your own structured data on the project, a plain JSON object the server keeps verbatim ' +
+    `(at most ${PROJECT_METADATA_MAX_LENGTH} characters once serialized). It REPLACES the whole ` +
+    'object: read the project first and send the merged result, never a fragment.');
+/**
+ * Register the eleven project tools on a server. Called by `buildMcpServer`
+ * after `<toolPrefix>whoami` and before the tool's own set, so `tools/list`
+ * keeps one stable order: the chassis examples, whoami, the projects, the
+ * tool's own.
+ */
+export function registerProjectTools(server, ctx, identity, scopes, checkScope, hints) {
+    const { workspaceInput, cursorInput, limitInput } = mcpInputs(identity);
+    const prefix = identity.toolPrefix;
+    /** The read/write pre-check + the per-call workspace seam, in one step. */
+    const enter = (scope, workspace) => {
+        const denied = checkScope(ctx.principal, scope);
+        return denied ? { denied } : { ctx: forWorkspace(ctx, workspace) };
+    };
+    const run = (scope, workspace, body) => {
+        const entered = enter(scope, workspace);
+        if ('denied' in entered)
+            return Promise.resolve(entered.denied);
+        return wrapToolErrors(async () => jsonText(await body(entered.ctx)), hints);
+    };
+    const jsonBody = (value) => ({
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(value)
+    });
+    // ── Reads ────────────────────────────────────────────────────────────────
+    server.registerTool(`${prefix}list_projects`, {
+        description: `List the projects you belong to in an organization, newest first. ${WHAT_IS_A_PROJECT} ` +
+            `${ROLE_LADDER} Returns { projects: [{ id, name, description, metadata, archivedAt, ` +
+            'createdBy, createdAt, updatedAt, myRole, memberCount }], nextCursor } — `myRole` is YOUR ' +
+            'role on that project, so it tells you in advance what you may do. When nextCursor is ' +
+            `non-null, call again with cursor set to it. By default only the live projects are listed; ` +
+            `${ARCHIVED_RULE}`,
+        inputSchema: {
+            workspace: workspaceInput,
+            archived: z
+                .union([z.boolean(), projectsArchivedFilterSchema])
+                .optional()
+                .describe('Which projects to list: false (the default) the live ones, true the archived ones, ' +
+                '"all" both.'),
+            limit: limitInput,
+            cursor: cursorInput
+        },
+        annotations: { readOnlyHint: true }
+    }, async ({ workspace, archived, limit, cursor }) => run(scopes.read, workspace, (c) => 
+    // A model writes the natural boolean; the wire takes the enum.
+    callApi(c, pageQuery('/api/v1/projects', { cursor, limit }, { archived: typeof archived === 'boolean' ? String(archived) : archived }))));
+    server.registerTool(`${prefix}get_project`, {
+        description: `Read one project, with your own role on it. ${WHAT_IS_A_PROJECT} ${ROLE_LADDER} Returns ` +
+            '{ id, name, description, metadata, archivedAt, createdBy, createdAt, updatedAt, myRole, ' +
+            'memberCount }. A project you are not a member of answers "not found" whether or not it ' +
+            'exists — being refused is not proof that it is there.',
+        inputSchema: { workspace: workspaceInput, projectId: projectIdInput },
+        annotations: { readOnlyHint: true }
+    }, async ({ workspace, projectId }) => run(scopes.read, workspace, (c) => callApi(c, `/api/v1/projects/${projectId}`)));
+    server.registerTool(`${prefix}list_project_members`, {
+        description: `List a project's members and what each of them may do. ${ROLE_LADDER} A member is a ` +
+            'person or a team, told apart by `kind`: a person entry is { kind: "person", userId, email, ' +
+            'name, role, addedBy, createdAt }, a team entry { kind: "team", teamId, slug, name, ' +
+            'membersCount, hubTeamId, role, addedBy, createdAt }, and every member of a team holds the ' +
+            'team’s role; a person’s effective role is the highest of their own entry and their teams’. ' +
+            'Returns { members, nextCursor }; pass a person’s `userId` to the tools that change or remove ' +
+            `a member, a team’s \`teamId\` to ${prefix}set_project_team_role and ${prefix}remove_project_team.`,
+        inputSchema: {
+            workspace: workspaceInput,
+            projectId: projectIdInput,
+            limit: limitInput,
+            cursor: cursorInput
+        },
+        annotations: { readOnlyHint: true }
+    }, async ({ workspace, projectId, limit, cursor }) => run(scopes.read, workspace, (c) => callApi(c, pageQuery(`/api/v1/projects/${projectId}/members`, { cursor, limit }))));
+    // ── Writes ───────────────────────────────────────────────────────────────
+    server.registerTool(`${prefix}create_project`, {
+        description: `Create a project in an organization — confirm with the user first (name included). ` +
+            `${WHAT_IS_A_PROJECT} You become its first manager, so you may then add members and set ` +
+            `their roles. ${ROLE_LADDER} Returns the new project, whose id is what every other ` +
+            'project tool takes.',
+        inputSchema: {
+            workspace: workspaceInput,
+            name: nameInput,
+            description: descriptionInput.optional(),
+            metadata: metadataInput.optional()
+        }
+    }, async ({ workspace, name, description, metadata }) => run(scopes.write, workspace, (c) => callApi(c, '/api/v1/projects', jsonBody({
+        name,
+        ...(description !== undefined ? { description } : {}),
+        ...(metadata !== undefined ? { metadata } : {})
+    }))));
+    server.registerTool(`${prefix}update_project`, {
+        description: 'Change a project’s name, description or metadata — confirm with the user first. Needs the ' +
+            'manager role on the project (an organization owner or admin has it everywhere). Send only ' +
+            'the fields you are changing; `metadata` REPLACES the whole object, and a description set to ' +
+            `null clears it. ${ARCHIVED_RULE} Returns the project as it now is.`,
+        inputSchema: {
+            workspace: workspaceInput,
+            projectId: projectIdInput,
+            name: nameInput.optional(),
+            description: descriptionInput
+                .nullable()
+                .optional()
+                .describe('A sentence or two on what the project is for; null clears it.'),
+            metadata: metadataInput.optional()
+        }
+    }, async ({ workspace, projectId, name, description, metadata }) => {
+        if (name === undefined && description === undefined && metadata === undefined) {
+            return deny('Nothing to change: pass at least one of name, description or metadata. ' +
+                'Read the project first if you need its current values.');
+        }
+        return run(scopes.write, workspace, (c) => callApi(c, `/api/v1/projects/${projectId}`, {
+            ...jsonBody({
+                ...(name !== undefined ? { name } : {}),
+                ...(description !== undefined ? { description } : {}),
+                ...(metadata !== undefined ? { metadata } : {})
+            }),
+            method: 'PATCH'
+        }));
+    });
+    server.registerTool(`${prefix}archive_project`, {
+        description: 'Archive a project, or bring an archived one back — confirm with the user first. Needs the ' +
+            `manager role on the project. ${ARCHIVED_RULE} Nothing is lost: archiving is reversible, by ` +
+            'calling this same tool with `archived` set to false. Returns the project in its new state.',
+        inputSchema: {
+            workspace: workspaceInput,
+            projectId: projectIdInput,
+            archived: z
+                .boolean()
+                .optional()
+                .describe('true (the default) archives the project; false brings an archived one back.')
+        }
+        // No destructiveHint: a reversible, read-only switch is not a delete,
+        // and a host that gates destructive tools must not block the restore.
+    }, async ({ workspace, projectId, archived }) => {
+        const leg = archived === false ? 'unarchive' : 'archive';
+        return run(scopes.write, workspace, (c) => callApi(c, `/api/v1/projects/${projectId}/${leg}`, { method: 'POST' }));
+    });
+    server.registerTool(`${prefix}add_project_member`, {
+        description: 'Put one of the organization’s own members on a project, with a role — confirm with the ' +
+            `user first. Needs the manager role on the project. ${ROLE_LADDER} Name the person by ` +
+            'either `userId` or `email`, and it must be someone who is already an active member of the ' +
+            'organization: this invites nobody and creates no account. Or a team by `teamId` (from ' +
+            `${prefix}list_teams), which puts every member of the team on the project with that role. ` +
+            'Exactly one of `userId`, `email` or `teamId`. Returns the new project member, a person or a ' +
+            'team entry.',
+        inputSchema: {
+            workspace: workspaceInput,
+            projectId: projectIdInput,
+            userId: userIdInput.optional(),
+            email: z.email().optional().describe('The email address the person joined the organization with.'),
+            teamId: teamIdInput.optional(),
+            role: roleInput
+        }
+    }, async ({ workspace, projectId, userId, email, teamId, role }) => {
+        if ([userId, email, teamId].filter((k) => k !== undefined).length !== 1) {
+            return deny('Name exactly one member: a person by userId or email, or a team by teamId, not several ' +
+                `and not none. The organization member list has both for everyone who has joined; ` +
+                `${prefix}list_teams has the team ids.`);
+        }
+        const who = userId !== undefined ? { userId } : email !== undefined ? { email } : { teamId };
+        return run(scopes.write, workspace, (c) => callApi(c, `/api/v1/projects/${projectId}/members`, jsonBody({ ...who, role })));
+    });
+    server.registerTool(`${prefix}set_project_member_role`, {
+        description: 'Change what a project member may do — confirm with the user first. Needs the manager role ' +
+            `on the project. ${ROLE_LADDER} Raising someone to manager lets them manage the members and ` +
+            'archive the project too. Returns the member as they now are.',
+        inputSchema: {
+            workspace: workspaceInput,
+            projectId: projectIdInput,
+            userId: userIdInput,
+            role: roleInput
+        }
+    }, async ({ workspace, projectId, userId, role }) => run(scopes.write, workspace, (c) => callApi(c, `/api/v1/projects/${projectId}/members/${encodeURIComponent(userId)}`, {
+        ...jsonBody({ role }),
+        method: 'PATCH'
+    })));
+    server.registerTool(`${prefix}remove_project_member`, {
+        description: 'Take someone off a project — confirm with the user first; their access to the project and ' +
+            'to what is linked to it stops immediately. Needs the manager role on the project (anyone ' +
+            'may remove themselves). This removes the person from THIS project only: they stay a member ' +
+            'of the organization. Returns a last snapshot of the member that was removed.',
+        inputSchema: { workspace: workspaceInput, projectId: projectIdInput, userId: userIdInput },
+        annotations: { destructiveHint: true }
+    }, async ({ workspace, projectId, userId }) => run(scopes.write, workspace, (c) => callApi(c, `/api/v1/projects/${projectId}/members/${encodeURIComponent(userId)}`, {
+        method: 'DELETE'
+    })));
+    server.registerTool(`${prefix}set_project_team_role`, {
+        description: 'Change the role a team holds on a project — confirm with the user first. Every member of ' +
+            `the team holds this role on the project through it. Needs the manager role on the project. ` +
+            `${ROLE_LADDER} Returns the team entry as it now is.`,
+        inputSchema: {
+            workspace: workspaceInput,
+            projectId: projectIdInput,
+            teamId: teamIdInput,
+            role: roleInput
+        }
+    }, async ({ workspace, projectId, teamId, role }) => run(scopes.write, workspace, (c) => callApi(c, `/api/v1/projects/${projectId}/teams/${teamId}`, {
+        ...jsonBody({ role }),
+        method: 'PATCH'
+    })));
+    server.registerTool(`${prefix}remove_project_team`, {
+        description: 'Take a team off a project — confirm with the user first; the access its members held ' +
+            'THROUGH the team stops immediately. Needs the manager role on the project. People who also ' +
+            'have their own entry on the project keep it, and the team itself stays in the organization. ' +
+            'Returns a last snapshot of the team entry that was removed.',
+        inputSchema: { workspace: workspaceInput, projectId: projectIdInput, teamId: teamIdInput },
+        annotations: { destructiveHint: true }
+    }, async ({ workspace, projectId, teamId }) => run(scopes.write, workspace, (c) => callApi(c, `/api/v1/projects/${projectId}/teams/${teamId}`, { method: 'DELETE' })));
+}
+//# sourceMappingURL=projects.js.map

package/dist/mcp/projects.js.map

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

package/dist/mcp/server.d.ts

@@ -0,0 +1,52 @@
+import type { ToolIdentity } from '@antasphere/chassis-contract';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ErrorHints } from './errors.js';
+import { type McpScopes, type McpToolContext } from './tool-kit.js';
+/**
+ * The bundled MCP server: tools are thin shims over the instance's own
+ * /api/v1 — called IN-PROCESS with the caller's Authorization header
+ * forwarded verbatim. MCP is just another API client: no privileged path, no
+ * MCP-only endpoints; new behavior lands in the API first. Identity comes
+ * from the verified credential, never from a tool parameter.
+ *
+ * Conventions (ported from the predecessor MCP template):
+ *  - read tools: `readOnlyHint: true` + a checkScope on the tool's read scope
+ *  - write tools: confirm-first description + the tool's write scope (+ destructiveHint
+ *    for deletes) — see the write tools of the tool's own set (its tools.ts)
+ *  - checkScope is UX only — the API's fail-closed allowlist is the
+ *    enforcement point; this just gives the model a clean, actionable error.
+ *
+ * get_me and list_files below are the chassis' original example tools (the
+ * end-to-end whoami proof + a cursor-paginated list), followed by
+ * `<toolPrefix>whoami`, the identity tool under the tool's own prefix; the product tool set
+ * (`<toolPrefix>*`) lives in the tool's app (its tools.ts).
+ */
+export type { McpToolContext } from './tool-kit.js';
+export interface McpServerInfo {
+    version: string;
+    instanceName: string;
+}
+/**
+ * What a tool plugs into the bundled MCP server: its own tool set (registered
+ * AFTER the three chassis tools, so `tools/list` keeps its order), the server
+ * instructions, the error hints of its domain codes, and the two scope names
+ * the chassis tools pre-check.
+ */
+export interface McpToolDefinition {
+    registerTools: (server: McpServer, ctx: McpToolContext) => void;
+    instructions: (info: McpServerInfo) => string;
+    errorHints: ErrorHints;
+    scopes: McpScopes;
+}
+/** The MCP half of the tool's identity (`ToolIdentity['mcp']`): the server's name and the tool names' prefix. */
+export type McpIdentity = ToolIdentity['mcp'];
+/**
+ * The ONE composition of an instance's hint table: the domain hints, then
+ * every chassis group (the projects today), then the tool's own last, so a
+ * tool may re-word a chassis code and never the reverse. A tool set that
+ * wraps its own errors reads the same composition (never a copy), so a
+ * chassis group added here reaches the tool's tools without a second edit.
+ */
+export declare function composeErrorHints(toolHints: ErrorHints, toolPrefix: string): ErrorHints;
+export declare function buildMcpServer(ctx: McpToolContext, info: McpServerInfo, tool: McpToolDefinition, identity: McpIdentity): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzF,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;;;GAkBG;AACH,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;IAChE,YAAY,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,MAAM,CAAC;IAC9C,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,iHAAiH;AACjH,MAAM,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAEvF;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,WAAW,GACpB,SAAS,CAoGX"}