sw-dev-knowledge-base-mcp

sw-dev-knowledge-base-mcp

一个只读、离线的 MCP 服务，让编码 Agent 无需离开当前会话，就能对精选的 Shopware 开发者和商家知识库执行 ls/grep/cat 操作；同时也提供构建该知识库的工具。

语料库随软件包一同发布，因此服务在运行时无需网络、无需 API 密钥，也无需索引：它只是一个纯 Markdown 文件系统视图。

安装

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

Node >= 20。发布的软件包不声明任何依赖——它的两个第三方库 @modelcontextprotocol/sdk 和 zod 已内联到 dist/server.js 中，其余导入均为 node: 内置模块。它们的许可证见 THIRD-PARTY-NOTICES.md。

将其配置为 MCP 服务

将其注册为 stdio 服务。在 .mcp.json 风格的客户端配置中：

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

请固定到精确版本：语料库是软件包的一部分，因此版本也代表内容版本。

选项均为可选：

标志	环境变量	作用
--wiki-root <dir>	WIKI_ROOT	使用任意 wiki 根目录，而非软件包内的 wiki/
--corpus <name>	KB_CORPUS	选择 kb.config.json 中定义的语料库（软件包仅包含 wiki）
--project-wiki <dir>	KB_PROJECT_WIKI	将自己的项目 wiki 添加为 project 层；off 可禁用此层

提供的工具

工具	Shell 等效命令	返回内容
list_docs	ls（带 depth、glob）	目录条目、frontmatter 中的标题、目录的 index.md
grep_docs	在 *.md 中执行 grep -rin	带上下文的匹配行，或 files/count 模式
read_doc	cat / sed -n	页面或行范围、其 frontmatter，以及可引用的 path:from-to
kb_status	cat <layer>/manifest.json	所提供的层和语料库，以及来源信息和计数

行号与 Shell 中的行号完全一致，因此 grep_docs 命中后可直接定位到 read_doc。 这里没有排序功能，也没有搜索引擎：发现内容的质量取决于语料库自身的 index.md 行、关键词、主题中心页和同义词文件。服务不会写入任何内容，也不会建立网络连接。

语料库内容

wiki/platform/ — 对 Shopware 官方文档进行的检索导向改写：包括 6.6 和 6.7 的开发者文档、商家/功能文档、主题中心页、按版本整理的精选指南文件，以及同义词索引。内容按路径寻址：版本和文档类型以目录表示（platform/dev/6.7/…、platform/func/…），而非参数。wiki/README.md 介绍了目录布局，以及如何使用纯 Shell 浏览内容。

发布的 tarball 大小为 2.7 MB（解压后为 10.0 MB，共 2006 个文件）；顶层内容恰好为 LICENSE README.md THIRD-PARTY-NOTICES.md dist kb.config.json package.json wiki。

在此代码库中开发

最终用户无需克隆此代码库——它是用于构建上述软件包的工厂：

路径	内容
src/	MCP 服务源代码（构建 dist/server.js）
ingest/	确定性导入命令行工具：sync、pages、hubs、guidelines、build、synonyms、lint
wiki/	生成的文档语料库——不得手动编辑，wiki/platform/index.md 除外
test/	服务和导入测试套件（node --test）：465 项测试，零跳过
scripts/	setup-sources.mjs、setup-docs.mjs、pack.mjs
docs/	维护者指南——参见文档
.claude/	kb-factory-* 技能、固定版本的 writer/verify Agent，以及两个 kb-verify-* hooks
.sources/	被 Git 忽略，由 npm run setup 创建——固定版本的 Shopware 源码和文档克隆

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/

每次克隆后、运行 verify 套件或导入 writer 之前，请运行一次 /kb-factory-setup（Claude Code 技能，见 CONTRIBUTING.md）——它会安装两个 hooks，确保每个 Agent 只在自己的语料库中操作；没有这两个 hooks，就无法信任任何一个 Agent。

一次性设置 — npm run setup 实际会执行什么

npm run setup 会将两个你没有明确要求的内容获取到被 git 忽略的 .sources/ 中：

• 约 250 MB 的固定版本 Shopware 源码（.sources/shopware/<version>/，稀疏检出并固定到指定标签的 git 仓库——不是 composer install，不需要 PHP），供代码检查和代码证据流程读取。
• 约 1 GB 的官方文档克隆仓库（.sources/docs/{developer,merchant}/），由 docs 测试语料库提供服务。

该操作具有幂等性、可恢复性；满足条件后，在离线状态下也不会执行任何操作。**merchant 文档镜像是私有仓库。**在无法访问该仓库的主机上，设置过程会说明哪些内容不可用并继续执行——这是有意为之：缺少可选输入会降低运行效果，而非导致失败；无论如何，已提交的 wiki/platform/func/ 层仍可使用。完整说明请参阅： docs/sources.md。

文档

• docs/producer-manual.md — 构建、检查代码、验证和发布语料库；完整的技能驱动型导入工作流。
• docs/sources.md — .sources/ 中的内容，以及 npm run setup 如何构建它。
• docs/releasing.md — npm 设置、打标签、发布和发布后的验证。
• CONTRIBUTING.md — 工具链、测试／lint 门禁、CI 的零跳过规则。
• CHANGELOG.md — Keep a Changelog 格式。
• THIRD-PARTY-NOTICES.md — 内联到 dist/server.js 中的代码所采用的许可证。

许可证

MIT，Execuro UG（haftungsbeschränkt）。有关内联到 dist/server.js 中的第三方代码所采用的许可证，请参阅 THIRD-PARTY-NOTICES.md。