passwerk
io.github.ShahriarBijoyPublished by GitHub account ShahriarBijoyv0.1.1Updated Oct 24, 2026
Offline EU Battery Passport compiler: ingest documents, map, validate (IDTA 02035), emit AASX.
Overview
Offline MCP server that turns supplier documents into a validated EU Digital Battery Passport in AAS/AASX format, with a gap report.
- What you can do
- Passwerk ingests messy supplier documents (PDF, XLSX, DOCX, CSV, TXT), extracts and maps data points, validates them against IDTA 02035 templates and the EC data-point matrix, and emits a Digital Battery Passport as AAS JSON, AASX or HTML, plus a data carrier (UID, GS1 Digital Link, QR). It also produces a legally cited gap report of missing required data points and an obligations lookup by battery type, role and market date. The server exposes twelve tools over stdio or Streamable HTTP, along with reference resources and workflow prompts.
- When to use it
- Use it when a supplier or manufacturer needs to answer an EU battery-passport data request and has to assemble roughly 90 data points from ERP exports, spreadsheets and PDFs. It suits Tier-2 and mid-sized suppliers that lack commercial OEM-oriented tooling, and teams that want the ingest-map-validate-fix-emit workflow driven by an agent or a CI job.
- Requirements
- Runs locally as a Node.js process (Node 22.13 or newer) via npx @passwerk/server, or as a Docker image. No API keys and no accounts. Optional environment variables: PASSWERK_ROOT sets the directory that ingest_documents may read and emit_passport may write (default: the working directory); PASSWERK_LOG_LEVEL sets info or debug logging on stderr. The Docker variant uses PASSWERK_AUTH_TOKEN. Desktop-only; no web executable.
Installation
In SourceWeft
- Open passwerk in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
Passwerk
Offline EU Battery Passport Compiler.
Drop in a supplier's messy documents (BOMs, Excel exports, energy bills, supplier declarations). Get back a conformant Digital Battery Passport in the official AAS format (IDTA 02035-1 to -7) plus a legally cited gap report of what is still missing.
100 % offline. Zero API keys. Agent-agnostic: an MCP server for Claude Desktop, Claude Code, Codex, Cursor and OpenCode, a scriptable CLI, a plain TypeScript library, and a client-side web app with QR preview.
[passwerk in Claude Desktop: from five supplier documents to the gap report and the workbench]
Claude Desktop with the .mcpb bundle: the model ingests the Musterwerk documents, maps and validates, then opens the workbench inside the chat. Full-resolution MP4, 71 seconds.
Quick start
Let your agent install it. Paste this into Claude Code, Codex, Cursor, OpenCode or any other coding agent. It checks Node, picks the right commands for its host, installs passwerk and tells you how to check that it works:
Or run the commands yourself (Node >= 22.13):
Start a new session afterwards, then ask the agent to call list_capabilities.
Claude Desktop: download passwerk-<version>.mcpb from the
releases page and open it. Claude Desktop
installs the server, asks for your document folder, and the twelve passwerk tools are ready
after a restart. Details in docs/install/claude-desktop.md.
Everything else:
Host snippets for Codex, Cursor, OpenCode and plain HTTP are in docs/install. The agent workflow (ingest, map, validate, fix, emit) is taught by the bundled skill in skills/passwerk.
Why
Regulation (EU) 2023/1542, Art. 77: from 18 February 2027 every EV, light-means-of-transport and industrial >2 kWh battery placed on the EU market needs a Digital Battery Passport. The passport is roughly 90 data points scattered across a supplier's ERP, spreadsheets and PDFs. Every commercial platform sells to OEMs and Tier-1s. passwerk is the on-ramp for the Tier-2 and Mittelstand supplier who receives the data request and has no tooling to answer it.
Conformance is measured, not asserted. Every emitted golden passport is replayed through the
official aas-test-engines oracle on every CI run (docs/CONFORMANCE.md);
the badge reports verdict parity with that oracle, expected failures included. Mapping quality
on unseen supplier documents is scored in docs/EVALUATION.md. A
sovereignty test and a --network none Docker job prove zero network calls. None of this is a
certification of battery-passport compliance; the template (L3) and plausibility (L4) checks
are passwerk's own.
Packages
rules, core, server and cli make no network call and no model call, ever. The two
exceptions are opt-in and bring-your-own-key: the web app's mapping assist, which only ever
sees labels and values and only ever names attributes, and the passwerk chat demo loop.
Point the assist at http://localhost:11434/v1 and it runs against Ollama without a byte
leaving the building.
Command line
The CLI runs the same tools as the MCP server, in-process and offline, with exit codes a CI
job can gate on (audit: 0 valid, 1 warnings, 2 invalid; gaps: 0 when no required data
point is open).
Web app
apps/web runs the whole pipeline in the browser as six steps: project, documents, facts,
review, gaps and export. Documents never leave the browser; the autosave keeps your decisions,
facts and proposals in IndexedDB, never the uploaded files. Inside Claude Desktop the same
workbench runs as a fixed-height instrument in the host's iframe.
Development
Requires Node 22.13 or newer and pnpm 10.
Contributor instructions for humans and coding agents live in AGENTS.md. Architecture and
scope are in docs/BUILD_PLAN.md, every non-obvious choice in docs/DECISIONS.md.
Security and privacy
PRIVACY.md says what passwerk sends and stores, with the tests that enforce it: nothing
leaves the machine unless you switch on one of the two optional model features. SECURITY.md
says how to report a vulnerability privately and where the trust boundaries are, the document
parsers first.
Not legal advice
passwerk cites the regulation and the standards it implements, but it is a tool, not a
lawyer. Every legal claim it emits carries its sources and an isNotLegalAdvice: true flag.
License
Apache-2.0. See LICENSE and NOTICE. Bundled third-party artefacts are documented with
their sources, versions, checksums and licences in packages/rules/PROVENANCE.md.
Source: README.md at commit cfb2c40
Tools
0Version history
1- v0.1.1LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts