tracepass-mcp-server 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TracePass LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# TracePass MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for
+**[TracePass](https://www.tracepass.eu)** — the EU Digital Product
+Passport platform. It lets AI assistants (Claude, Cursor, IDE agents)
+manage products, Digital Product Passports, economic-operator parties,
+and GS1 EPCIS 2.0 supply-chain events.
+
+It speaks the full MCP protocol — **tools**, **resources**, **resource
+templates**, and **prompts**.
+
+## Two ways to use it
+
+The same server core ships two ways:
+
+1. **Hosted** — point your MCP client at `https://ai.tracepass.eu/mcp`.
+   Nothing to install; always current.
+2. **Local (npm)** — run `tracepass-mcp-server` via `npx`. The MCP
+   client launches it as a subprocess and speaks MCP over stdio.
+
+Both need a TracePass API key — mint one in the dashboard under
+**Developer → API Keys** (a `tp_…` key).
+
+## Configuration
+
+### Hosted
+
+```json
+{
+  "mcpServers": {
+    "tracepass": {
+      "url": "https://ai.tracepass.eu/mcp",
+      "headers": { "Authorization": "Bearer tp_YOUR_KEY" }
+    }
+  }
+}
+```
+
+### Local (npx / stdio)
+
+```json
+{
+  "mcpServers": {
+    "tracepass": {
+      "command": "npx",
+      "args": ["-y", "tracepass-mcp-server"],
+      "env": {
+        "TRACEPASS_API_KEY": "tp_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+Optional env var: `TRACEPASS_BASE_URL` (defaults to
+`https://app.tracepass.eu`) — point the tools at a different
+TracePass deployment.
+
+## Tools
+
+The ~23 TracePass v1 API operations are grouped into **5 tools**,
+each taking an `action` plus action-specific `args`:
+
+| Tool | Actions |
+|------|---------|
+| `tracepass_products` | `list`, `get`, `create`, `update` |
+| `tracepass_passports` | `list`, `get`, `get_by_serial`, `create`, `suspend`, `archive`, `get_qr` |
+| `tracepass_passport_fields` | `update` |
+| `tracepass_passport_parties` | `set`, `remove` |
+| `tracepass_epcis` | `export`, `capture`, `capture_job`, `query` |
+
+### A note on writes
+
+Some actions **cost money or are irreversible** — the server's tool
+descriptions tell the model so:
+
+- **`tracepass_passports` `create`** consumes a billable DPP slot on
+  the account's plan. Over-quota creation incurs a per-passport
+  overage charge; the tool surfaces a 402-style message and only
+  proceeds with `args.confirmOverage: true` after the user agrees.
+- **`tracepass_passports` `archive`** is irreversible — the public QR
+  permanently 404s. Use `suspend` (reversible) when a change might be
+  undone.
+- **`tracepass_epcis` `capture` / `query`** require the paid EPCIS
+  add-on; `export` is included on Starter plans and up.
+
+## Resources
+
+Read-only entity data you can attach as conversation context:
+
+- `tracepass://products` — the product catalogue
+- `tracepass://product/{id}` — one product
+- `tracepass://passport/{id}` — one passport, full field detail
+- `tracepass://passport/{id}/epcis` — a passport's EPCIS 2.0 events
+
+## Prompts
+
+Reusable DPP workflows the client surfaces as slash-commands:
+
+- `audit_passport` — review a passport for completeness and
+  compliance readiness
+- `onboard_product` — create a product and its first passport
+- `review_epcis_events` — summarise a passport's supply-chain trail
+
+## Development
+
+```bash
+npm install
+npm run build        # tsc -> dist/
+npm run typecheck
+npm test             # vitest
+npm run lint
+npm start            # run the hosted HTTP service locally (:8080)
+npm run start:stdio  # run the stdio server locally
+```
+
+The hosted service is a plain Node HTTP server (`dist/http.js`),
+stateless — each request carries its own API key and builds a fresh
+MCP session. It is containerised via the `Dockerfile` and deployed to
+Hetzner; see `tracepass-environment/docker-mcp.yml`.
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,60 @@
+/**
+ * HTTP client for the TracePass v1 API, used by the MCP tools.
+ *
+ * Design decision — why the MCP tools talk to the v1 API over HTTP
+ * rather than calling `lib/` functions in-process:
+ *   - The v1 route handlers already encapsulate API-key auth,
+ *     idempotency, the overage (402) flow, plan-gating, and the
+ *     per-day write/read counter bumps. Re-implementing that inside
+ *     the MCP tools would inevitably drift from the routes.
+ *   - It is the SAME code path the standalone npm package will use,
+ *     so the MCP core is genuinely transport-agnostic — the hosted
+ *     /mcp endpoint and the local npm package differ only in base
+ *     URL and where the key comes from.
+ *   - One bug surface, not two.
+ * The cost is a loopback HTTP hop when hosted — negligible.
+ *
+ * The client is intentionally thin: it forwards the Bearer key,
+ * sets Idempotency-Key on writes, and returns the parsed JSON plus
+ * the status code. Interpreting a 402 overage / 403 plan-gate /
+ * 429 rate-limit is the tool's job — those are meaningful results an
+ * AI agent must see and act on, not errors to swallow.
+ */
+export interface TracePassApiResponse {
+    /** HTTP status code. */
+    status: number;
+    /** `true` for 2xx. */
+    ok: boolean;
+    /** Parsed JSON body, or null when the body was empty / not JSON. */
+    body: unknown;
+}
+export interface TracePassClientConfig {
+    /** Base URL of the TracePass app, no trailing slash —
+     *  e.g. "https://app.tracepass.eu". */
+    baseUrl: string;
+    /** The caller's tp_ API key. */
+    apiKey: string;
+}
+export declare class TracePassClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(config: TracePassClientConfig);
+    /**
+     * Perform a v1 API request.
+     *
+     * @param method  HTTP method
+     * @param path    path under the base URL, must start with "/"
+     * @param body    JSON body for write methods (omitted for GET)
+     *
+     * Write methods automatically carry an `Idempotency-Key` header so
+     * a retried tool call doesn't double-execute. Never throws on a
+     * non-2xx response — the status + body come back for the tool to
+     * interpret. Throws only on a genuine network/transport failure.
+     */
+    request(method: "GET" | "POST" | "PATCH" | "DELETE", path: string, body?: unknown): Promise<TracePassApiResponse>;
+    get(path: string): Promise<TracePassApiResponse>;
+    post(path: string, body?: unknown): Promise<TracePassApiResponse>;
+    patch(path: string, body?: unknown): Promise<TracePassApiResponse>;
+    delete(path: string): Promise<TracePassApiResponse>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,oBAAoB;IACnC,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,oEAAoE;IACpE,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC;2CACuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AASD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,qBAAqB;IAKzC;;;;;;;;;;;OAWG;IACG,OAAO,CACX,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,EAC3C,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,oBAAoB,CAAC;IA8BhC,GAAG,CAAC,IAAI,EAAE,MAAM;IAGhB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAGjC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAGlC,MAAM,CAAC,IAAI,EAAE,MAAM;CAGpB"}

package/dist/api-client.js

@@ -0,0 +1,87 @@
+/**
+ * HTTP client for the TracePass v1 API, used by the MCP tools.
+ *
+ * Design decision — why the MCP tools talk to the v1 API over HTTP
+ * rather than calling `lib/` functions in-process:
+ *   - The v1 route handlers already encapsulate API-key auth,
+ *     idempotency, the overage (402) flow, plan-gating, and the
+ *     per-day write/read counter bumps. Re-implementing that inside
+ *     the MCP tools would inevitably drift from the routes.
+ *   - It is the SAME code path the standalone npm package will use,
+ *     so the MCP core is genuinely transport-agnostic — the hosted
+ *     /mcp endpoint and the local npm package differ only in base
+ *     URL and where the key comes from.
+ *   - One bug surface, not two.
+ * The cost is a loopback HTTP hop when hosted — negligible.
+ *
+ * The client is intentionally thin: it forwards the Bearer key,
+ * sets Idempotency-Key on writes, and returns the parsed JSON plus
+ * the status code. Interpreting a 402 overage / 403 plan-gate /
+ * 429 rate-limit is the tool's job — those are meaningful results an
+ * AI agent must see and act on, not errors to swallow.
+ */
+/** Generate a random Idempotency-Key for a write request. */
+function newIdempotencyKey() {
+    // crypto.randomUUID is available on Node 18+ and every Web runtime
+    // the MCP server can plausibly run on.
+    return `mcp-${crypto.randomUUID()}`;
+}
+export class TracePassClient {
+    baseUrl;
+    apiKey;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.apiKey = config.apiKey;
+    }
+    /**
+     * Perform a v1 API request.
+     *
+     * @param method  HTTP method
+     * @param path    path under the base URL, must start with "/"
+     * @param body    JSON body for write methods (omitted for GET)
+     *
+     * Write methods automatically carry an `Idempotency-Key` header so
+     * a retried tool call doesn't double-execute. Never throws on a
+     * non-2xx response — the status + body come back for the tool to
+     * interpret. Throws only on a genuine network/transport failure.
+     */
+    async request(method, path, body) {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+        };
+        const init = { method, headers };
+        if (body !== undefined && method !== "GET") {
+            headers["Content-Type"] = "application/json";
+            headers["Idempotency-Key"] = newIdempotencyKey();
+            init.body = JSON.stringify(body);
+        }
+        const res = await fetch(`${this.baseUrl}${path}`, init);
+        let parsed = null;
+        const text = await res.text();
+        if (text.length > 0) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // Non-JSON body (e.g. an HTML error page from a proxy) —
+                // keep the raw text so the tool can still report something.
+                parsed = { raw: text };
+            }
+        }
+        return { status: res.status, ok: res.ok, body: parsed };
+    }
+    get(path) {
+        return this.request("GET", path);
+    }
+    post(path, body) {
+        return this.request("POST", path, body ?? {});
+    }
+    patch(path, body) {
+        return this.request("PATCH", path, body ?? {});
+    }
+    delete(path) {
+        return this.request("DELETE", path);
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAmBH,6DAA6D;AAC7D,SAAS,iBAAiB;IACxB,mEAAmE;IACnE,uCAAuC;IACvC,OAAO,OAAO,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,OAAO,eAAe;IACT,OAAO,CAAS;IAChB,MAAM,CAAS;IAEhC,YAAY,MAA6B;QACvC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,OAAO,CACX,MAA2C,EAC3C,IAAY,EACZ,IAAc;QAEd,MAAM,OAAO,GAA2B;YACtC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;YACtC,MAAM,EAAE,kBAAkB;SAC3B,CAAC;QACF,MAAM,IAAI,GAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAE9C,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YAC3C,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;YAC7C,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,EAAE,CAAC;YACjD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;QAExD,IAAI,MAAM,GAAY,IAAI,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;YAAC,MAAM,CAAC;gBACP,yDAAyD;gBACzD,4DAA4D;gBAC5D,MAAM,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;YACzB,CAAC;QACH,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1D,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,CAAC,IAAY,EAAE,IAAc;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,KAAK,CAAC,IAAY,EAAE,IAAc;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,CAAC,IAAY;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/http.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HTTP entrypoint — the hosted form of the TracePass MCP server.
+ *
+ * Runs as a standalone Node service (deployed to Hetzner, served at
+ * https://ai.tracepass.eu/mcp). An MCP client connects over
+ * Streamable HTTP; the customer's TracePass API key travels in the
+ * `Authorization: Bearer tp_...` header of every request.
+ *
+ * Stateless by design: each MCP request is self-contained, so we
+ * build a fresh server + transport per request, bound to that
+ * request's API key. No server-side session state — which means the
+ * service scales horizontally and a restart drops nothing.
+ *
+ * This is the SAME server core (`createMcpServer`) the stdio
+ * entrypoint uses — only the transport + the key source differ.
+ *
+ * Env:
+ *   PORT                (optional) — listen port, default 8080
+ *   TRACEPASS_BASE_URL  (optional) — the TracePass API base URL the
+ *                       tools call, default https://app.tracepass.eu
+ */
+export {};
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

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

package/dist/http.js

@@ -0,0 +1,138 @@
+/**
+ * HTTP entrypoint — the hosted form of the TracePass MCP server.
+ *
+ * Runs as a standalone Node service (deployed to Hetzner, served at
+ * https://ai.tracepass.eu/mcp). An MCP client connects over
+ * Streamable HTTP; the customer's TracePass API key travels in the
+ * `Authorization: Bearer tp_...` header of every request.
+ *
+ * Stateless by design: each MCP request is self-contained, so we
+ * build a fresh server + transport per request, bound to that
+ * request's API key. No server-side session state — which means the
+ * service scales horizontally and a restart drops nothing.
+ *
+ * This is the SAME server core (`createMcpServer`) the stdio
+ * entrypoint uses — only the transport + the key source differ.
+ *
+ * Env:
+ *   PORT                (optional) — listen port, default 8080
+ *   TRACEPASS_BASE_URL  (optional) — the TracePass API base URL the
+ *                       tools call, default https://app.tracepass.eu
+ */
+import { createServer } from "node:http";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { createMcpServer } from "./server.js";
+const PORT = Number(process.env.PORT) || 8080;
+const DEFAULT_BASE_URL = "https://app.tracepass.eu";
+const BASE_URL = process.env.TRACEPASS_BASE_URL?.trim() || DEFAULT_BASE_URL;
+/** The MCP endpoint path. `/mcp` is the conventional path. */
+const MCP_PATH = "/mcp";
+/** Extract the tp_ API key from the Authorization header. */
+function extractApiKey(req) {
+    const auth = req.headers["authorization"];
+    if (typeof auth !== "string")
+        return null;
+    const m = auth.match(/^Bearer\s+(.+)$/i);
+    return m ? m[1].trim() : null;
+}
+/** Read a Node request body into a string. */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+/** Convert a Node IncomingMessage to a Web `Request`. */
+async function toWebRequest(req) {
+    const host = req.headers["host"] ?? `localhost:${PORT}`;
+    const url = `http://${host}${req.url ?? "/"}`;
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (v === undefined)
+            continue;
+        headers.set(k, Array.isArray(v) ? v.join(", ") : v);
+    }
+    const method = req.method ?? "GET";
+    const hasBody = method !== "GET" && method !== "HEAD";
+    const body = hasBody ? await readBody(req) : undefined;
+    return new Request(url, { method, headers, body: body || undefined });
+}
+/** Write a Web `Response` back through a Node ServerResponse. */
+async function writeWebResponse(webRes, res) {
+    res.statusCode = webRes.status;
+    webRes.headers.forEach((value, key) => res.setHeader(key, value));
+    const text = await webRes.text();
+    res.end(text);
+}
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify(body));
+}
+const httpServer = createServer((req, res) => {
+    void (async () => {
+        try {
+            const url = req.url ?? "/";
+            // Health check — for the Hetzner container's liveness probe.
+            if (url === "/health" || url === "/healthz") {
+                sendJson(res, 200, { status: "ok", service: "tracepass-mcp" });
+                return;
+            }
+            // Only the MCP path is served.
+            if (url.split("?")[0] !== MCP_PATH) {
+                sendJson(res, 404, {
+                    error: "not_found",
+                    message: `This service serves MCP at ${MCP_PATH} only.`,
+                });
+                return;
+            }
+            // API key required — no anonymous MCP access.
+            const apiKey = extractApiKey(req);
+            if (!apiKey) {
+                sendJson(res, 401, {
+                    error: "unauthorized",
+                    message: "Missing API key. Send Authorization: Bearer <tp_ key>. Mint a key in the TracePass dashboard → Developer → API Keys.",
+                });
+                return;
+            }
+            // Fresh, stateless server + transport per request, bound to
+            // this request's key. The transport's handleRequest takes a
+            // Web Request and returns a Web Response.
+            const server = createMcpServer({ apiKey, baseUrl: BASE_URL });
+            const transport = new WebStandardStreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // stateless
+            });
+            await server.connect(transport);
+            const webReq = await toWebRequest(req);
+            const webRes = await transport.handleRequest(webReq);
+            await writeWebResponse(webRes, res);
+            // Stateless — release the per-request server once answered.
+            await server.close();
+        }
+        catch (err) {
+            // Never leak a stack trace; never leave the socket hanging.
+            if (!res.headersSent) {
+                sendJson(res, 500, {
+                    error: "internal_error",
+                    message: err instanceof Error ? err.message : "Unexpected error",
+                });
+            }
+            else {
+                res.end();
+            }
+        }
+    })();
+});
+httpServer.listen(PORT, () => {
+    process.stdout.write(`tracepass-mcp-server listening on :${PORT}${MCP_PATH} ` +
+        `(TracePass API: ${BASE_URL})\n`);
+});
+// Graceful shutdown so a container stop / redeploy drains cleanly.
+for (const signal of ["SIGTERM", "SIGINT"]) {
+    process.on(signal, () => {
+        httpServer.close(() => process.exit(0));
+    });
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/prompts.d.ts

@@ -0,0 +1,23 @@
+/**
+ * MCP prompts for the TracePass server.
+ *
+ * Prompts are reusable, parameterised instructions the MCP client
+ * surfaces to the user (typically as slash-commands). They are not
+ * tool calls — a prompt returns a `messages` array that seeds the
+ * conversation, after which the model uses the TracePass tools to
+ * carry out the workflow.
+ *
+ * Each prompt here encodes a common DPP workflow so a user doesn't
+ * have to phrase it from scratch — and so the model approaches the
+ * task the way TracePass intends (e.g. always reviewing before
+ * publishing, never bulk-creating billable passports without
+ * consent).
+ *
+ * Pure — no IO. `registerPrompts(server)` wires them onto the server.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register every TracePass prompt on the server.
+ */
+export declare function registerPrompts(server: McpServer): void;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAczE;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4EvD"}

package/dist/prompts.js

@@ -0,0 +1,82 @@
+/**
+ * MCP prompts for the TracePass server.
+ *
+ * Prompts are reusable, parameterised instructions the MCP client
+ * surfaces to the user (typically as slash-commands). They are not
+ * tool calls — a prompt returns a `messages` array that seeds the
+ * conversation, after which the model uses the TracePass tools to
+ * carry out the workflow.
+ *
+ * Each prompt here encodes a common DPP workflow so a user doesn't
+ * have to phrase it from scratch — and so the model approaches the
+ * task the way TracePass intends (e.g. always reviewing before
+ * publishing, never bulk-creating billable passports without
+ * consent).
+ *
+ * Pure — no IO. `registerPrompts(server)` wires them onto the server.
+ */
+import { z } from "zod";
+/** Build a GetPromptResult from a single user-role text message. */
+function userPrompt(text) {
+    return {
+        messages: [
+            {
+                role: "user",
+                content: { type: "text", text },
+            },
+        ],
+    };
+}
+/**
+ * Register every TracePass prompt on the server.
+ */
+export function registerPrompts(server) {
+    // ── Audit a passport's completeness ───────────────────────────
+    server.registerPrompt("audit_passport", {
+        title: "Audit a passport",
+        description: "Review one Digital Product Passport for completeness and compliance readiness — which required fields are missing, which economic-operator parties are unset, whether it's publishable.",
+        argsSchema: {
+            passportId: z
+                .string()
+                .describe("The TracePass id of the passport to audit."),
+        },
+    }, ({ passportId }) => userPrompt(`Audit the TracePass Digital Product Passport with id "${passportId}".\n\n` +
+        `1. Fetch it with the tracepass_passports tool (action: get, format: full).\n` +
+        `2. Report: which required template fields are still empty or unapproved; ` +
+        `which economic-operator parties (manufacturer / importer / recycler / etc.) are missing; ` +
+        `the passport's status and completion percentage.\n` +
+        `3. State plainly whether the passport is ready to publish, and if not, the exact gaps to close.\n` +
+        `Do not change anything — this is a read-only audit.`));
+    // ── Set up a product + its first passport ─────────────────────
+    server.registerPrompt("onboard_product", {
+        title: "Onboard a new product",
+        description: "Walk through creating a new product and its first Digital Product Passport — gathering the details, then creating both.",
+        argsSchema: {
+            productName: z.string().describe("The product's name."),
+            category: z
+                .string()
+                .describe("Category key — battery, textile, electronics, construction, steel, chemicals, packaging, furniture, tyres, jewelry, toys, or fmcg."),
+        },
+    }, ({ productName, category }) => userPrompt(`Help me onboard a new product into TracePass: "${productName}" in the "${category}" category.\n\n` +
+        `1. Confirm the product details with me (model / SKU, description), then create it with tracepass_products (action: create).\n` +
+        `2. Ask me for the first unit's GTIN and serial number.\n` +
+        `3. Before creating the passport, remind me that a passport is BILLABLE and consumes a plan DPP slot. ` +
+        `Only after I confirm, create it with tracepass_passports (action: create).\n` +
+        `4. If the account is over its plan quota, tell me the overage cost and wait for my explicit go-ahead before retrying with confirmOverage.`));
+    // ── Reconcile EPCIS supply-chain events ───────────────────────
+    server.registerPrompt("review_epcis_events", {
+        title: "Review a passport's EPCIS events",
+        description: "Inspect the EPCIS 2.0 supply-chain event history of a passport and summarise the product's traceability story.",
+        argsSchema: {
+            passportId: z
+                .string()
+                .describe("The TracePass id of the passport whose events to review."),
+        },
+    }, ({ passportId }) => userPrompt(`Review the EPCIS 2.0 supply-chain events for the TracePass passport "${passportId}".\n\n` +
+        `1. Export them with tracepass_epcis (action: export).\n` +
+        `2. Summarise the product's traceability story in plain language — the sequence of events ` +
+        `(commissioning, production steps, shipping, service, ownership changes), with dates and locations.\n` +
+        `3. Flag any gaps — e.g. a long unexplained period, a missing production step, events with no location.\n` +
+        `This is read-only; do not capture or modify any events.`));
+}
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,oEAAoE;AACpE,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,MAAe;gBACrB,OAAO,EAAE,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE;aACzC;SACF;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,MAAiB;IAC/C,iEAAiE;IACjE,MAAM,CAAC,cAAc,CACnB,gBAAgB,EAChB;QACE,KAAK,EAAE,kBAAkB;QACzB,WAAW,EACT,yLAAyL;QAC3L,UAAU,EAAE;YACV,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,CAAC,4CAA4C,CAAC;SAC1D;KACF,EACD,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CACjB,UAAU,CACR,yDAAyD,UAAU,QAAQ;QACzE,8EAA8E;QAC9E,2EAA2E;QAC3E,2FAA2F;QAC3F,oDAAoD;QACpD,mGAAmG;QACnG,qDAAqD,CACxD,CACJ,CAAC;IAEF,iEAAiE;IACjE,MAAM,CAAC,cAAc,CACnB,iBAAiB,EACjB;QACE,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EACT,yHAAyH;QAC3H,UAAU,EAAE;YACV,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;YACvD,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,CACP,oIAAoI,CACrI;SACJ;KACF,EACD,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,CAC5B,UAAU,CACR,kDAAkD,WAAW,aAAa,QAAQ,iBAAiB;QACjG,+HAA+H;QAC/H,0DAA0D;QAC1D,uGAAuG;QACvG,8EAA8E;QAC9E,2IAA2I,CAC9I,CACJ,CAAC;IAEF,iEAAiE;IACjE,MAAM,CAAC,cAAc,CACnB,qBAAqB,EACrB;QACE,KAAK,EAAE,kCAAkC;QACzC,WAAW,EACT,gHAAgH;QAClH,UAAU,EAAE;YACV,UAAU,EAAE,CAAC;iBACV,MAAM,EAAE;iBACR,QAAQ,CAAC,0DAA0D,CAAC;SACxE;KACF,EACD,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CACjB,UAAU,CACR,wEAAwE,UAAU,QAAQ;QACxF,yDAAyD;QACzD,2FAA2F;QAC3F,sGAAsG;QACtG,0GAA0G;QAC1G,yDAAyD,CAC5D,CACJ,CAAC;AACJ,CAAC"}

package/dist/resources.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { TracePassClient } from "./api-client.js";
+/**
+ * Register every TracePass resource + resource template on the
+ * server, bound to a v1 API client.
+ */
+export declare function registerResources(server: McpServer, client: TracePassClient): void;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAyBvD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,eAAe,GACtB,IAAI,CAiFN"}