tracepass-mcp-server: Instructions file for Claude Code

tracepass-mcp-server

MCP server for TracePass — lets AI assistants manage products, Digital Product Passports, economic-operator parties, and GS1 EPCIS 2.0 events over the TracePass v1 REST API. Speaks the full MCP protocol: tools, resources, resource templates, prompts. Read README.md for usage; this file is the agent guardrail layer.

This is a PUBLIC npm package (tracepass-mcp-server, integrators npx it). Nothing internal — no prod paths, SSH aliases, secrets, hosting details, or operational fingerprint — belongs in this repo. Deploy/ops artefacts and release keys live in private repos kept outside this one. Keep it that way when editing this file.

Architecture (the one rule everything serves)

One server core, every transport — the tool surface must never drift between the hosted endpoint and the local package.

• src/server.ts — createMcpServer(config): builds the McpServer with all tools/resources/prompts. Transport-agnostic — knows nothing about stdio vs HTTP.
• src/http.ts — hosted entrypoint (the Node service behind https://ai.tracepass.eu/mcp). Stateless: fresh server+transport per request, credential from Authorization: Bearer ….
• src/stdio.ts — local/npx entrypoint. Client launches it as a subprocess; key from TRACEPASS_API_KEY env.
• Both call the same createMcpServer. Only the transport + key source differ. Any change to the tool surface must go through the core so both forms stay identical.
• src/usage-log.ts — one mcp_usage JSON line per hosted request on stdout: JSON-RPC method, tool + action, credential KIND (none / api_key / oauth / supplier_token), status, user-agent. Never the IP, the token or tool arguments. It is how real tools/call use is told apart from catalog and liveness probes.
• src/supplier-server.ts — a second, separate server for suppliers answering one data request, served only by http.ts at /supplier/mcp/<token> (token in the path, for URL-only connectors) and /supplier/mcp (Bearer header). Its credential is the request token, not an account: no auth gate and no WWW-Authenticate challenge on that path, because an OAuth prompt is a dead end for someone with no TracePass account. A bad or missing token becomes a readable tool error (supplierResult). Its tools (the array returned in src/supplier-server.ts; the README's "For suppliers" table lists them — keep the two in lockstep) sit over the platform's /api/supplier/v1/*, which owns every rule (requested keys only, merge until review, rate limit). It is not in the eu.tracepass/tracepass listing, the server card or the main tool list, and its README table deliberately avoids the `name` — description pattern so mcppedia does not count its tools as the main server's.
• src/compliance-server.ts — a third server, the DPP Assistant, served by http.ts at /compliance/mcp. It answers what EU DPP law asks of a company (scope, required fields, what changed, registry guidance, the saved compliance profile) and can start a draft passport; the tool array is buildComplianceTools(). Unlike the supplier path it authenticates like the main endpoint (tp_ key or OAuth, with its own WWW-Authenticate challenge and per-path RFC 9728 metadata at /.well-known/oauth-protected-resource/compliance/mcp, whose resource is exactly https://ai.tracepass.eu/compliance/mcp), and it has its own card at /.well-known/mcp/compliance-server-card.json, not mirrored on www. Every platform call carries X-Source: assistant, so answers are logged and capped on that channel. The platform owns every answer; the server adds two things only:
  • the hard-rule block (HARD_RULES) in each tool description and the server instructions: answer from a tool result, never from memory, never rank vendors;
  • the closing disclaimer: withClosingDisclaimer repeats the envelope's disclaimer as a separate final text block ("End your answer with this line, word for word"). Left only inside the JSON, models drop it from most answers. A tool argument must exist in the v1 request. /api/v1/scope/check is strict (an undeclared field or fact is 400 invalid_input), so an argument the tool advertises but the API lacks fails on every call that uses it. The model then retries without it, so nothing looks broken. A test checks scope_check's posted body against the published OpenAPI schema. Its registry entry is server.compliance.json (eu.tracepass/compliance), a separate listing from server.json. Its behaviour is measured by an eval set in the private runner repo; a tool-description change can move the scores, so re-run it after one.