barcoding-mcp

An MCP server that encodes 100+ barcode symbologies (via bwip-js) and decodes all the common 1D/2D formats (via zxing-wasm), with zero native dependencies. Node runtime, served over both stdio and streamable HTTP. Plus an ASCII/Unicode terminal QR for output that needs no image channel.

The funnel is asymmetric on purpose: encode 100+, decode the common set, round-trip-verified where both overlap. We do not claim "decode anything."

Tools

Related MCP server: barcode-mcp

Install & run

npm (stdio — for Claude Code, Cursor, local agents)

npx @cordfuse/barcoding-mcp          # stdio transport (default)
npx @cordfuse/barcoding-mcp --http   # streamable HTTP on :3900

MCP client config (stdio):

{
  "mcpServers": {
    "barcoding": { "command": "npx", "args": ["-y", "@cordfuse/barcoding-mcp"] }
  }
}

Docker / GHCR (streamable HTTP — for remote wiring)

docker run -p 3900:3900 ghcr.io/cordfuse/barcoding-mcp:latest
# or, from a checkout:
docker compose -f docker/compose.yaml up

Serves streamable HTTP at http://<host>:3900/mcp, with a liveness probe at /health. Port is settable via the PORT env. stdio is per-invocation and not containerised — the image is the HTTP endpoint.

Repository layout (monorepo)

barcoding-mcp/
  packages/
    mcp/          @cordfuse/barcoding-mcp  (the server)  →  packages/mcp/README.md
  docker/         Dockerfile + compose.yaml (the --http server)
  .github/        CI + release workflows

npm workspace; node_modules hoists to the root.

Development

npm ci                                     # install (root)
npm run build   -w @cordfuse/barcoding-mcp # tsc + copy option catalog into dist
npm test        -w @cordfuse/barcoding-mcp # node:test smoke suite
npm run gen:options -w @cordfuse/barcoding-mcp  # regenerate the option catalog from bwip-js

The list_symbology_options catalog is generated from bwip-js's own sources (dist/bwip-js-gen.d.ts for common options, barcode.ps for the per-symbology option preambles) into packages/mcp/src/data/symbology-options.json.

CI / Release

• CI (.github/workflows/ci.yml) — typecheck + build + test on Node 20 & 22 for every push and PR to main.

• Release (.github/workflows/release.yml) — pushing a v* tag publishes:

  • the npm package @cordfuse/barcoding-mcp (guards that the tag matches the package version), and

  • the Docker image ghcr.io/cordfuse/barcoding-mcp:<version> + :latest.

npm version patch -w @cordfuse/barcoding-mcp
git commit -am "release vX.Y.Z" && git tag vX.Y.Z && git push --follow-tags

Secrets: npm publish needs the org NPM_TOKEN (this repo must be on the org token's selected-repo allow-list). GHCR uses the built-in GITHUB_TOKEN (packages: write) — no secret required.

License

MIT