sw-dev-knowledge-base-mcp

A read-only, offline MCP server that lets a coding agent ls/grep/cat a curated Shopware developer and merchant knowledge base without leaving its session — plus the factory that builds that knowledge base.

The corpus ships inside the package, so the server needs no network at runtime, no API key and no index: it is a filesystem view over plain Markdown.

Install

Terminal

npx -y @execuro-sw-ecosystem/sw-dev-knowledge-base-mcp@<version>

Node >= 20. The published package declares no dependencies — its two third-party libraries, @modelcontextprotocol/sdk and zod, are inlined into dist/server.js, and every other import is a node: builtin. Their licences are in THIRD-PARTY-NOTICES.md.

Configure it as an MCP server

config.json

{
  "mcpServers": {
    "ShopwareDevKnowledgeBase": {
      "command": "npx",
      "args": ["-y", "@execuro-sw-ecosystem/sw-dev-knowledge-base-mcp@<version>"]
    }
  }
}

Pin an exact version: the corpus is part of the package, so the version is the content.

Options, all optional:

Flag	Environment variable	Effect
`--wiki-root <dir>`	`WIKI_ROOT`	Serve an arbitrary wiki root instead of the packaged `wiki/`
`--corpus <name>`	`KB_CORPUS`	Select a corpus defined in `kb.config.json` (the package ships only `wiki`)
`--project-wiki <dir>`	`KB_PROJECT_WIKI`	Add your own project wiki as a `project` layer; `off` disables it

The tools it exposes

Tool	Shell equivalent	What it returns
`list_docs`	`ls` (with `depth`, `glob`)	Directory entries, titles from frontmatter, the directory's `index.md`
`grep_docs`	`grep -rin` over `*.md`	Match lines with context, or `files`/`count` modes
`read_doc`	`cat` / `sed -n`	A page or line range, its frontmatter and a citable `path:from-to`
`kb_status`	`cat <layer>/manifest.json`	Which layers and corpus are served, with provenance and counts

Line numbers are identical to the shell's, so a grep_docs hit pages straight into read_doc. There is no ranking and no search engine: discovery quality comes from the corpus's own index.md lines, keywords, hubs and synonyms file. The server writes nothing and opens no network connection.

What is in the corpus

wiki/platform/ — a retrieval-oriented rewrite of Shopware's official documentation: developer docs for 6.6 and 6.7, merchant/functional docs, topic hub pages, curated per-version guideline files and a synonyms index. It is path-addressed: version and doc type are directories (platform/dev/6.7/…, platform/func/…), never parameters. wiki/README.md describes the layout and how to navigate it with a plain shell.

The published tarball is 2.7 MB (10.0 MB unpacked, 2006 files); its top level is exactly LICENSE README.md THIRD-PARTY-NOTICES.md dist kb.config.json package.json wiki.

Working on this repository

End users never clone this repository — it is the factory that produces the package above:

Path	What it is
`src/`	MCP server source (builds `dist/server.js`)
`ingest/`	The deterministic ingest CLI: sync, pages, hubs, guidelines, build, synonyms, lint
`wiki/`	The generated documentation corpus — never hand-edited, except `wiki/platform/index.md`
`test/`	Server and ingest test suite (`node --test`): 465 tests, zero skips
`scripts/`	`setup-sources.mjs`, `setup-docs.mjs`, `pack.mjs`
`docs/`	Maintainer guides — see Documentation
`.claude/`	`kb-factory-` skills, pinned writer/verify agents, and the two `kb-verify-` hooks
`.sources/`	Gitignored, created by `npm run setup` — pinned Shopware source and docs clones

Terminal

npm ci
npm run setup     # fetches .sources/ — see "One-time setup" below
npm run build     # typecheck + bundle src/ -> dist/server.js
npm test          # build, then the full test suite
npm run wiki:lint # blocking schema/link/id/size checks over wiki/platform/

Run /kb-factory-setup (a Claude Code skill, see CONTRIBUTING.md) once per clone before running the verify suite or an ingest writer — it installs the two hooks that keep each agent inside its own corpus, without which neither is trustworthy.

One-time setup — what `npm run setup` actually does

npm run setup fetches two things you did not ask for by name into a gitignored .sources/:

~250 MB of pinned Shopware source (.sources/shopware/<version>/, a sparse tag-pinned git checkout — not a composer install, no PHP needed) that the code check and code-evidence lanes read.
~1 GB of official documentation clones (.sources/docs/{developer,merchant}/) that the docs test corpus serves.

It is idempotent, resumable and an offline no-op once satisfied. The merchant documentation mirror is a private repository. On a host without access, setup prints what is unavailable and continues — that is deliberate: a missing optional input degrades the run rather than failing it, and the committed wiki/platform/func/ layer stays usable either way. Full detail: docs/sources.md.

Documentation

docs/producer-manual.md — building, code-checking, verifying and shipping the corpus; the full skill-driven ingest workflow.
docs/sources.md — what .sources/ holds and how npm run setup builds it.
docs/releasing.md — npm setup, tagging, publishing and post-publish verification.
CONTRIBUTING.md — toolchain, test/lint gates, CI's zero-skips rule.
CHANGELOG.md — Keep a Changelog format.
THIRD-PARTY-NOTICES.md — licences of the code inlined into dist/server.js.

Licence

MIT, Execuro UG (haftungsbeschränkt). See THIRD-PARTY-NOTICES.md for the licences of the third-party code inlined into dist/server.js.