TECRID Connect

Open-source client, CLI, Claude Code MCP server, and LIMS connector profiles for TECRID: the neutral trust layer between laboratories, suppliers, brands, retailers, certification programs, government, and the public.

TECRID stands for Test Evidence Credential Record Identifier. A TECRID is a persistent identifier for a versioned laboratory evidence record. The canonical definition, trust boundary, privacy model, and role-by-role explanation live at tecrid.com/what-is-a-tecrid.

This repository is designed around one narrow operational win: a laboratory issues one structured, signed report credential at final release; the brand receives a complete TECRID receipt in its own workspace; approved certifiers, retailers, or government programs receive their separately authorized scopes. No recipient has to download, rename, re-upload, OCR, or re-key the same PDF.

Choose your implementation path

The role chips lead to bounded implementation instructions. Coding agents should read AGENTS.md; Claude Code should also read CLAUDE.md. Both files point back to the same role and integrity rules so platform-specific instructions do not silently diverge.

What works in the production API

Workflow	Production status
Reserve a TECRID before final report rendering	Live
Return report-template identifier, resolver URL, and QR payload	Live
Show an explicit reserved—not issued—resolver state	Live
Finalize the preprinted TECRID with final-PDF SHA-256 and Ed25519 proof	Live
Deliver a full controller receipt to the brand or supplier	Live
Fan out independently scoped recipient packages	Live
Portfolio insights with source TECRIDs and missing-analyte exceptions	Live
API upload of historical PDFs for laboratory claim	Live
Durable in-product notifications	Live
Outbound email notification	Not yet configured; requires a production sending provider
Vendor-certified LabWare, LabVantage, or STARLIMS package	Not yet; profiles in this repo are implementation starters

Five-minute setup

Requirements: Node.js 22.13 or later and a TECRID organization API key.

npm install
export TECRID_API_KEY='tec_live_…'
npm run cli -- doctor
npm run cli -- connector-plan --adapter labware

Create a local config without putting a secret in it:

npm run cli -- init

The API base defaults to https://tecrid.com. Set TECRID_API_BASE only for an authorized test environment.

Claude Code

The checked-in .mcp.json starts a local stdio MCP server and reads TECRID_API_KEY from the environment. Claude Code asks for approval before using a project-scoped MCP server.

export TECRID_API_KEY='tec_live_…'
claude

Then run /mcp and enable tecrid. Available tools:

• reserve_report_tecrid
• list_report_reservations
• finalize_report_tecrid
• import_legacy_report
• get_evidence_insights
• get_lims_connector_profile

You can also register it explicitly:

claude mcp add --transport stdio --scope project --env TECRID_API_KEY="$TECRID_API_KEY" tecrid -- npx tsx src/mcp-server.ts

The correct final-report sequence

1. Brand or supplier creates a routing token for a verified laboratory and SKU. External recipient grants are optional.
2. Laboratory calls POST /api/v1/report-reservations before rendering the report.
3. LIMS places tecrid_identifier and tecrid_resolver_url into the approved report template. The resolver URL is also the QR payload.
4. LIMS renders the final PDF and calculates SHA-256 over those exact bytes.
5. Laboratory canonicalizes the structured findings and signs that exact payload with its ICS-reviewed Ed25519 key.
6. Laboratory finalizes the reservation. The identifier printed on the PDF becomes the issued TECRID.
7. TECRID places the full signed receipt in the controller workspace and creates scoped recipient packages for every active grant.

This two-pass design avoids a circular hash: the identifier exists before the PDF, while the final PDF fingerprint exists only after the identifier is printed.

CLI examples

Reserve from a JSON input:

npm run cli -- reserve --input examples/reserve-report.json

After report rendering and signature:

npm run cli -- finalize \
  --reservation reservation_… \
  --input examples/finalize-report.example.json

Import a historical report:

npm run cli -- legacy-import \
  --pdf /authorized/path/report.pdf \
  --metadata templates/legacy-report.metadata.json

The import response returns a laboratory confirmation path. Uploading is not issuance; the named laboratory still has to claim, reconcile, confirm, and sign.

Organization roles

• Laboratories reserve, render, fingerprint, sign, finalize, revise, and revoke.
• Brands and ingredient suppliers authorize laboratory delivery by SKU, receive full controller receipts, and control each external recipient.
• Retailers, certification programs, and government workspaces request a precise SKU, purpose, analyte scope, and delivery mode.
• Every recipient gets its own frozen fingerprinted view. Permission for one recipient never implies permission for another.

See examples/role-workflows.md for implementation checklists.

Put the TECRID profile in brand email signatures

A participating brand or supplier may use the official TECRID mark as a compact hyperlink to its canonical public participant profile—the organizational equivalent of a researcher linking an ORCID iD. The recommended presentation is:

[TECRID mark] View Organization name’s TECRID profile

The link must resolve to https://tecrid.com/participants/ORGANIZATION_CODE. Public discoverability is opt-in; the profile link does not make private reports public and does not represent product certification, approval, safety, or compliance.

Use the unmodified transparent artwork at assets/tecrid-logo.png. Copy-ready HTML, plain-text fallbacks, email-client steps, website markup, privacy boundaries, and an AI implementation prompt are in docs/brand-profile-and-signature.md.

First connector profiles

The repo includes generic JSON/CSV plus LabWare, LabVantage, and STARLIMS profiles. These three are first implementation priorities, not a claim that public market data proves them to be the three most common LIMS products.

• LabWare publicly documents REST/JSON, XML, ASTM, HL7, and CSV integration options.
• LabVantage publicly documents REST and SOAP web services.
• STARLIMS publicly documents REST/OpenAPI System Interfacing and automated reporting to external systems.

Each laboratory still needs an authorized administrator to bind its site-specific objects, release event, report template, security model, and validation plan. TECRID should be called from the controlled release workflow; it should never write directly into a production LIMS database.

Is it 10× better?

Potentially for the evidence handoff, not automatically for the entire laboratory workflow. Measure it in a pilot.

Record these timestamps for at least 100 reports:

• final technical approval
• TECRID reservation
• final PDF rendered
• TECRID finalized
• brand controller receipt created
• first recipient package created
• first exception opened and closed

Compare against the prior process:

manual minutes per report = lab email + brand filing/keying + recipient upload/OCR/keying + verification callbacks
TECRID minutes per report = automated issuance + exception-review minutes
workflow improvement = manual minutes / TECRID minutes

A 10× claim is justified only when measured median human-touch time drops by at least 90% without increasing error, rework, or unresolved exceptions. Keep lab turnaround time, analytical work, and technical review outside this narrow claim unless those steps are separately measured.

Security and integrity

• Never commit tec_live_…, tec_route_…, signing keys, private PDFs, or customer data.
• API and routing keys belong in a secret manager and are displayed once by TECRID.
• The registry stores API and routing tokens as one-way SHA-256 hashes.
• Only a verified laboratory may publish production TECRIDs.
• A controlled credential requires current controller authorization.
• Reservations expire; expired identifiers must not be reused.
• Insights are descriptive. They do not determine product safety, legal compliance, or comparability across units and methods.

Development

npm run typecheck
npm test
npm run mcp

License: MIT.

The MIT license covers the software. Use of the TECRID name and mark is governed separately by BRAND-USAGE.md.