tracepass-mcp-server 1.0.0

package/dist/resources.js

@@ -0,0 +1,96 @@
+/**
+ * MCP resources for the TracePass server.
+ *
+ * Resources differ from tools: a tool is something the model
+ * *calls*; a resource is data the user (or client) *attaches as
+ * context*. For TracePass that's read-only entity data — a product,
+ * a passport, its EPCIS event history — addressed by a `tracepass://`
+ * URI so a user can drop "this passport" into a conversation.
+ *
+ * Two kinds, both registered here:
+ *   - a STATIC resource — `tracepass://products` — the catalogue;
+ *   - RESOURCE TEMPLATES — `tracepass://passport/{id}` etc. —
+ *     parameterised URIs the client can complete.
+ *
+ * All resource reads are read-only and go through the same v1 API
+ * client as the tools, so auth / plan-gating / rate-limits behave
+ * identically.
+ */
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Build a ReadResourceResult `contents` entry carrying JSON text. */
+function jsonContents(uri, data) {
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+/** Build a contents entry for an error — resources can't return an
+ *  isError flag, so an unreadable resource yields a JSON error body
+ *  the model can still read. */
+function errorContents(uri, status, body) {
+    return jsonContents(uri, {
+        error: `TracePass API returned ${status}`,
+        detail: body,
+    });
+}
+/**
+ * Register every TracePass resource + resource template on the
+ * server, bound to a v1 API client.
+ */
+export function registerResources(server, client) {
+    // ── Static resource: the product catalogue ────────────────────
+    server.registerResource("products", "tracepass://products", {
+        title: "Product catalogue",
+        description: "The account's TracePass product catalogue (first page). Attach this for an overview of what products exist.",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const res = await client.get("/api/v1/products?limit=100");
+        return res.ok
+            ? jsonContents(uri.href, res.body)
+            : errorContents(uri.href, res.status, res.body);
+    });
+    // ── Template: a product by id ─────────────────────────────────
+    server.registerResource("product", new ResourceTemplate("tracepass://product/{id}", { list: undefined }), {
+        title: "Product",
+        description: "One TracePass product by its id — tracepass://product/{id}.",
+        mimeType: "application/json",
+    }, async (uri, variables) => {
+        const id = String(variables.id);
+        const res = await client.get(`/api/v1/products/${encodeURIComponent(id)}`);
+        return res.ok
+            ? jsonContents(uri.href, res.body)
+            : errorContents(uri.href, res.status, res.body);
+    });
+    // ── Template: a passport by id ────────────────────────────────
+    server.registerResource("passport", new ResourceTemplate("tracepass://passport/{id}", { list: undefined }), {
+        title: "Digital Product Passport",
+        description: "One DPP by its id, full field detail — tracepass://passport/{id}. Attach this to give the model a passport's complete state.",
+        mimeType: "application/json",
+    }, async (uri, variables) => {
+        const id = String(variables.id);
+        const res = await client.get(`/api/v1/passports/${encodeURIComponent(id)}?format=full`);
+        return res.ok
+            ? jsonContents(uri.href, res.body)
+            : errorContents(uri.href, res.status, res.body);
+    });
+    // ── Template: a passport's EPCIS event history ────────────────
+    server.registerResource("passport-epcis", new ResourceTemplate("tracepass://passport/{id}/epcis", {
+        list: undefined,
+    }), {
+        title: "Passport EPCIS events",
+        description: "A passport's supply-chain event history as an EPCIS 2.0 JSON-LD document — tracepass://passport/{id}/epcis.",
+        mimeType: "application/ld+json",
+    }, async (uri, variables) => {
+        const id = String(variables.id);
+        const res = await client.get(`/api/v1/passports/${encodeURIComponent(id)}/epcis`);
+        return res.ok
+            ? jsonContents(uri.href, res.body)
+            : errorContents(uri.href, res.status, res.body);
+    });
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

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

package/dist/result.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tool-result shaping for the MCP server.
+ *
+ * Every MCP tool returns a `CallToolResult` — `{ content: [...],
+ * isError? }`. This module gives the tools one consistent way to
+ * turn a `TracePassApiResponse` into that shape, and — critically —
+ * to translate the v1 API's *meaningful* non-2xx responses into
+ * results an AI agent can read and act on, rather than opaque
+ * errors.
+ *
+ * The three responses an agent MUST be able to act on:
+ *   - 402 overage_required — the write would exceed the plan's DPP
+ *     quota; the agent can retry with `confirmOverage: true`.
+ *   - 403 plan-gated (e.g. epcis_capture_not_available) — the
+ *     feature isn't on the tenant's plan; the agent should tell the
+ *     user, not retry.
+ *   - 429 rate-limited — the daily write/read budget is spent; retry
+ *     tomorrow.
+ * Surfacing these as readable `isError: true` text (not a thrown
+ * exception) lets the model explain the situation to the user.
+ */
+/** The MCP CallToolResult shape (text content only — sufficient for
+ *  every TracePass tool; no tool returns binary). */
+export interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+}
+/** A plain text result. */
+export declare function textResult(text: string): ToolResult;
+/** A successful result carrying JSON data — pretty-printed so the
+ *  model reads it cleanly, plus structuredContent for clients that
+ *  consume it. */
+export declare function jsonResult(data: unknown): ToolResult;
+/** An error result — `isError: true` so the client renders it as a
+ *  failed tool call, with a human-readable explanation. */
+export declare function errorResult(message: string): ToolResult;
+/**
+ * Turn a v1 API response into a ToolResult. 2xx → jsonResult. The
+ * meaningful non-2xx cases get a specific, actionable explanation;
+ * anything else gets a generic error carrying the status + body.
+ */
+export declare function apiResult(res: {
+    status: number;
+    ok: boolean;
+    body: unknown;
+}): ToolResult;
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;qDACqD;AACrD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,2BAA2B;AAC3B,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAEnD;AAED;;kBAEkB;AAClB,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAQpD;AAED;2DAC2D;AAC3D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,UAAU,CA8Cb"}

package/dist/result.js

@@ -0,0 +1,77 @@
+/**
+ * Tool-result shaping for the MCP server.
+ *
+ * Every MCP tool returns a `CallToolResult` — `{ content: [...],
+ * isError? }`. This module gives the tools one consistent way to
+ * turn a `TracePassApiResponse` into that shape, and — critically —
+ * to translate the v1 API's *meaningful* non-2xx responses into
+ * results an AI agent can read and act on, rather than opaque
+ * errors.
+ *
+ * The three responses an agent MUST be able to act on:
+ *   - 402 overage_required — the write would exceed the plan's DPP
+ *     quota; the agent can retry with `confirmOverage: true`.
+ *   - 403 plan-gated (e.g. epcis_capture_not_available) — the
+ *     feature isn't on the tenant's plan; the agent should tell the
+ *     user, not retry.
+ *   - 429 rate-limited — the daily write/read budget is spent; retry
+ *     tomorrow.
+ * Surfacing these as readable `isError: true` text (not a thrown
+ * exception) lets the model explain the situation to the user.
+ */
+/** A plain text result. */
+export function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+/** A successful result carrying JSON data — pretty-printed so the
+ *  model reads it cleanly, plus structuredContent for clients that
+ *  consume it. */
+export function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        structuredContent: data && typeof data === "object" && !Array.isArray(data)
+            ? data
+            : { result: data },
+    };
+}
+/** An error result — `isError: true` so the client renders it as a
+ *  failed tool call, with a human-readable explanation. */
+export function errorResult(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/**
+ * Turn a v1 API response into a ToolResult. 2xx → jsonResult. The
+ * meaningful non-2xx cases get a specific, actionable explanation;
+ * anything else gets a generic error carrying the status + body.
+ */
+export function apiResult(res) {
+    if (res.ok)
+        return jsonResult(res.body);
+    const body = (res.body ?? {});
+    const errorCode = typeof body.error === "string" ? body.error : undefined;
+    const message = typeof body.message === "string" ? body.message : undefined;
+    switch (res.status) {
+        case 401:
+            return errorResult("Authentication failed — the TracePass API key is missing or invalid. Check the key configured for this MCP server.");
+        case 402:
+            // The overage flow. The v1 create-passport routes return this
+            // with the plan limit + per-DPP price; the agent can re-call
+            // the same tool with confirmOverage: true to accept the charge.
+            return errorResult(`This action would exceed the plan's included quota. ${message ?? ""}`.trim() +
+                " Re-run the tool with confirmOverage: true to accept the per-passport overage charge, or tell the user they've hit their plan limit.");
+        case 403:
+            return errorResult(`Not permitted on this account's plan${errorCode ? ` (${errorCode})` : ""}. ${message ?? "This feature may require a higher plan or a paid add-on."}`.trim() +
+                " Do not retry — tell the user this needs a plan change.");
+        case 404:
+            return errorResult(`Not found — ${message ?? "no resource matches that id or serial."}`);
+        case 409:
+            return errorResult(`Conflict — ${message ?? "this would collide with existing data (e.g. a duplicate GTIN or serial)."}`);
+        case 422:
+            return errorResult(`Validation error — ${message ?? "the request payload was rejected. Check the tool arguments against the schema."}`);
+        case 429:
+            return errorResult("Rate limit reached — the account's daily API budget is spent. It resets at 00:00 UTC; retry then.");
+        default:
+            return errorResult(`TracePass API returned ${res.status}. ${message ?? errorCode ?? JSON.stringify(res.body)}`);
+    }
+}
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAUH,2BAA2B;AAC3B,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED;;kBAEkB;AAClB,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QAChE,iBAAiB,EACf,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YACtD,CAAC,CAAE,IAAgC;YACnC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE;KACvB,CAAC;AACJ,CAAC;AAED;2DAC2D;AAC3D,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,GAIzB;IACC,IAAI,GAAG,CAAC,EAAE;QAAE,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAExC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA4B,CAAC;IACzD,MAAM,SAAS,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1E,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAE5E,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC;QACnB,KAAK,GAAG;YACN,OAAO,WAAW,CAChB,oHAAoH,CACrH,CAAC;QACJ,KAAK,GAAG;YACN,8DAA8D;YAC9D,6DAA6D;YAC7D,gEAAgE;YAChE,OAAO,WAAW,CAChB,uDAAuD,OAAO,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE;gBAC3E,sIAAsI,CACzI,CAAC;QACJ,KAAK,GAAG;YACN,OAAO,WAAW,CAChB,uCAAuC,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,IAAI,0DAA0D,EAAE,CAAC,IAAI,EAAE;gBAC1J,yDAAyD,CAC5D,CAAC;QACJ,KAAK,GAAG;YACN,OAAO,WAAW,CAChB,eAAe,OAAO,IAAI,wCAAwC,EAAE,CACrE,CAAC;QACJ,KAAK,GAAG;YACN,OAAO,WAAW,CAChB,cAAc,OAAO,IAAI,0EAA0E,EAAE,CACtG,CAAC;QACJ,KAAK,GAAG;YACN,OAAO,WAAW,CAChB,sBAAsB,OAAO,IAAI,gFAAgF,EAAE,CACpH,CAAC;QACJ,KAAK,GAAG;YACN,OAAO,WAAW,CAChB,mGAAmG,CACpG,CAAC;QACJ;YACE,OAAO,WAAW,CAChB,0BAA0B,GAAG,CAAC,MAAM,KAAK,OAAO,IAAI,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAC5F,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The TracePass MCP server factory.
+ *
+ * `createMcpServer(config)` builds an `McpServer` with every
+ * TracePass tool registered, bound to an API client. It is
+ * TRANSPORT-AGNOSTIC — it knows nothing about stdio vs HTTP. The
+ * caller connects it to a transport:
+ *   - the hosted `/mcp` route → WebStandardStreamableHTTPServerTransport
+ *   - the standalone npm package → StdioServerTransport
+ *
+ * One factory, every transport — so the tool surface can never
+ * drift between the hosted endpoint and the local package.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Server identity reported to MCP clients. Bump `version` on a
+ *  meaningful tool-surface change. */
+export declare const MCP_SERVER_INFO: {
+    readonly name: "tracepass";
+    readonly version: "1.0.0";
+};
+export interface CreateMcpServerConfig {
+    /** Base URL of the TracePass app — e.g. "https://app.tracepass.eu".
+     *  The hosted route passes its own origin; the npm package passes
+     *  the public URL (or a customer override). */
+    baseUrl: string;
+    /** The caller's tp_ API key — every v1 call is made as this key. */
+    apiKey: string;
+}
+/**
+ * Build a fully-wired TracePass `McpServer`. The caller is
+ * responsible for connecting it to a transport via `.connect()`.
+ */
+export declare function createMcpServer(config: CreateMcpServerConfig): McpServer;
+//# 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;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAOpE;sCACsC;AACtC,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AAEX,MAAM,WAAW,qBAAqB;IACpC;;mDAE+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,SAAS,CAqDxE"}

package/dist/server.js

@@ -0,0 +1,75 @@
+/**
+ * The TracePass MCP server factory.
+ *
+ * `createMcpServer(config)` builds an `McpServer` with every
+ * TracePass tool registered, bound to an API client. It is
+ * TRANSPORT-AGNOSTIC — it knows nothing about stdio vs HTTP. The
+ * caller connects it to a transport:
+ *   - the hosted `/mcp` route → WebStandardStreamableHTTPServerTransport
+ *   - the standalone npm package → StdioServerTransport
+ *
+ * One factory, every transport — so the tool surface can never
+ * drift between the hosted endpoint and the local package.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TracePassClient } from "./api-client.js";
+import { buildTools } from "./tools.js";
+import { registerResources } from "./resources.js";
+import { registerPrompts } from "./prompts.js";
+import { errorResult } from "./result.js";
+/** Server identity reported to MCP clients. Bump `version` on a
+ *  meaningful tool-surface change. */
+export const MCP_SERVER_INFO = {
+    name: "tracepass",
+    version: "1.0.0",
+};
+/**
+ * Build a fully-wired TracePass `McpServer`. The caller is
+ * responsible for connecting it to a transport via `.connect()`.
+ */
+export function createMcpServer(config) {
+    const server = new McpServer(MCP_SERVER_INFO, {
+        instructions: "Tools for the TracePass Digital Product Passport platform. " +
+            "Reads are free; writes that create passports are billable and " +
+            "consume plan quota — never create passports in bulk or accept " +
+            "an overage charge without the user's explicit consent. " +
+            "archive_passport is irreversible; prefer suspend_passport when " +
+            "a change might need undoing.",
+    });
+    const client = new TracePassClient({
+        baseUrl: config.baseUrl,
+        apiKey: config.apiKey,
+    });
+    for (const tool of buildTools(client)) {
+        // The SDK passes validated args (typed from the Zod shape) as the
+        // first param + a RequestHandlerExtra second param we don't use.
+        // A handler that throws would surface as an opaque protocol
+        // error, so we catch and convert to a readable isError result.
+        // The result is cast to the SDK's CallToolResult — our ToolResult
+        // is a structurally-compatible subset (text content only).
+        const cb = async (args) => {
+            try {
+                return await tool.handler(args);
+            }
+            catch (err) {
+                return errorResult(`Tool "${tool.name}" failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        };
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+        }, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        cb);
+    }
+    // Resources (entity data the user attaches as context) + prompts
+    // (reusable DPP workflows the client surfaces as slash-commands).
+    // `ping` and capability negotiation are handled by the SDK itself
+    // once a transport is connected — no wiring needed.
+    registerResources(server, client);
+    registerPrompts(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C;sCACsC;AACtC,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,OAAO;CACR,CAAC;AAWX;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAA6B;IAC3D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,eAAe,EAAE;QAC5C,YAAY,EACV,6DAA6D;YAC7D,gEAAgE;YAChE,gEAAgE;YAChE,yDAAyD;YACzD,iEAAiE;YACjE,8BAA8B;KACjC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC,CAAC;IAEH,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,kEAAkE;QAClE,iEAAiE;QACjE,4DAA4D;QAC5D,+DAA+D;QAC/D,kEAAkE;QAClE,2DAA2D;QAC3D,MAAM,EAAE,GAAG,KAAK,EAAE,IAA6B,EAAE,EAAE;YACjD,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAClC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,WAAW,CAChB,SAAS,IAAI,CAAC,IAAI,aAAa,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAClF,CAAC;YACJ,CAAC;QACH,CAAC,CAAC;QACF,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B;QACD,8DAA8D;QAC9D,EAAS,CACV,CAAC;IACJ,CAAC;IAED,iEAAiE;IACjE,kEAAkE;IAClE,kEAAkE;IAClE,oDAAoD;IACpD,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,eAAe,CAAC,MAAM,CAAC,CAAC;IAExB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/stdio.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * stdio entrypoint — the local / npx form of the TracePass MCP
+ * server.
+ *
+ * An MCP client (Claude Desktop, Cursor, an IDE agent) launches this
+ * as a subprocess and speaks MCP over stdin/stdout. The API key and
+ * the TracePass base URL come from environment variables the client
+ * sets in its server config:
+ *
+ *   TRACEPASS_API_KEY    (required) — a tp_ API key
+ *   TRACEPASS_BASE_URL   (optional) — defaults to https://app.tracepass.eu
+ *
+ * This is the SAME server core (`createMcpServer`) the hosted HTTP
+ * service uses — only the transport differs.
+ */
+export {};
+//# sourceMappingURL=stdio.d.ts.map

package/dist/stdio.d.ts.map

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

package/dist/stdio.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * stdio entrypoint — the local / npx form of the TracePass MCP
+ * server.
+ *
+ * An MCP client (Claude Desktop, Cursor, an IDE agent) launches this
+ * as a subprocess and speaks MCP over stdin/stdout. The API key and
+ * the TracePass base URL come from environment variables the client
+ * sets in its server config:
+ *
+ *   TRACEPASS_API_KEY    (required) — a tp_ API key
+ *   TRACEPASS_BASE_URL   (optional) — defaults to https://app.tracepass.eu
+ *
+ * This is the SAME server core (`createMcpServer`) the hosted HTTP
+ * service uses — only the transport differs.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createMcpServer } from "./server.js";
+const DEFAULT_BASE_URL = "https://app.tracepass.eu";
+async function main() {
+    const apiKey = process.env.TRACEPASS_API_KEY;
+    if (!apiKey || apiKey.trim() === "") {
+        // Write to stderr — stdout is the MCP protocol channel and must
+        // not carry anything but JSON-RPC.
+        process.stderr.write("tracepass-mcp-server: TRACEPASS_API_KEY is not set. " +
+            "Add it to the MCP server's env config (a tp_ key from " +
+            "the TracePass dashboard → Developer → API Keys).\n");
+        process.exit(1);
+    }
+    const baseUrl = process.env.TRACEPASS_BASE_URL?.trim() || DEFAULT_BASE_URL;
+    const server = createMcpServer({ apiKey, baseUrl });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // The process now stays alive serving MCP over stdio until the
+    // client closes the pipe.
+}
+main().catch((err) => {
+    process.stderr.write(`tracepass-mcp-server: fatal — ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=stdio.js.map

package/dist/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAC7C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACpC,gEAAgE;QAChE,mCAAmC;QACnC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,sDAAsD;YACpD,wDAAwD;YACxD,oDAAoD,CACvD,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,IAAI,gBAAgB,CAAC;IAE3E,MAAM,MAAM,GAAG,eAAe,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,+DAA+D;IAC/D,0BAA0B;AAC5B,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iCAAiC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACtF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP tool definitions for the TracePass v1 API.
+ *
+ * The v1 surface has ~23 endpoints. Exposing 23 flat MCP tools would
+ * swamp the model's tool list and slow tool selection. Instead the
+ * surface is grouped into FIVE resource tools, each taking:
+ *   - `action` — a required enum naming the operation;
+ *   - `args`   — an object whose required shape DEPENDS on `action`.
+ *
+ * MCP's `inputSchema` is one Zod shape per tool and can't natively
+ * branch on `action`. So `args` is declared permissively, and each
+ * handler validates `args` against the SPECIFIC per-action Zod
+ * schema — the per-action rigor is kept, it just lives in the
+ * handler. A model that omits a required arg gets a precise error
+ * (`ACTION_SCHEMAS` powers both the validation and the messages).
+ *
+ * Every tool's `description` documents each action and its `args`.
+ * `annotations` carry MCP hint flags at the tool level; per-action
+ * risk (billable / irreversible) is spelled out in the description
+ * so the model warns the user before a destructive action.
+ *
+ * Transport-agnostic: `buildTools(client)` binds the handlers to a
+ * `TracePassClient`; the server factory registers them.
+ */
+import { z } from "zod";
+import type { TracePassClient } from "./api-client.js";
+import { type ToolResult } from "./result.js";
+export interface McpToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    annotations: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+    };
+    handler: (args: Record<string, unknown>) => Promise<ToolResult>;
+}
+/**
+ * Build the 5 grouped tools, bound to a TracePass API client.
+ */
+export declare function buildTools(client: TracePassClient): McpToolDefinition[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,WAAW,EAAE;QACX,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACjE;AAmID;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,EAAE,CA2PvE"}