sw-dev-knowledge-base-mcp

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

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

Register it as a stdio server. In an .mcp.json-style client configuration:

{
  "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

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.