sw-dev-knowledge-base-mcp

sw-dev-knowledge-base-mcp

読み取り専用でオフライン動作するMCPサーバーです。コーディングエージェントはセッションを離れることなく、厳選された 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 で無効になります

提供するツール

ツール	シェルでの同等コマンド	返される内容
list_docs	ls（depth、glob を指定）	ディレクトリエントリー、フロントマターから取得したタイトル、ディレクトリの index.md
grep_docs	*.md に対する grep -rin	コンテキスト付きの一致行、または files／count モード
read_doc	cat／sed -n	ページまたは行範囲、そのフロントマター、引用可能な path:from-to
kb_status	cat <layer>/manifest.json	提供中のレイヤーとコーパス（出典情報と件数を含む）

行番号はシェルと同じなので、grep_docs の検索結果から read_doc に直接進めます。 ランキングも検索エンジンもありません。探索の品質は、コーパス内の index.md の記述、キーワード、ハブ、同義語ファイルによって決まります。サーバーは何も書き込まず、ネットワーク接続も開きません。

コーパスの内容

wiki/platform/ — Shopware の公式ドキュメントを検索向けに書き直したものです。6.6 と 6.7 の開発者向けドキュメント、マーチャント／機能向けドキュメント、トピック別ハブページ、バージョンごとに厳選されたガイドラインファイル、同義語インデックスが含まれています。パスで参照する構成になっており、バージョンとドキュメント種別はディレクトリ（platform/dev/6.7/…、platform/func/…）で表し、パラメーターにはしません。wiki/README.md にレイアウトと、プレーンなシェルでのナビゲーション方法が記載されています。

公開 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/	決定論的な取り込み CLI：sync、pages、hubs、guidelines、build、synonyms、lint
wiki/	生成されたドキュメントコーパス — wiki/platform/index.md を除き、手動編集は禁止
test/	サーバーと取り込みのテストスイート（node --test）：465 テスト、スキップ 0 件
scripts/	setup-sources.mjs、setup-docs.mjs、pack.mjs
docs/	メンテナー向けガイド — ドキュメントを参照
.claude/	kb-factory-* スキル、固定された writer／verify エージェント、および 2 つの kb-verify-* フック
.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/

検証スイートまたは取り込み writer を実行する前に、クローンごとに一度 /kb-factory-setup（Claude Code のスキル。CONTRIBUTING.md を参照）を実行してください。これにより、各エージェントをそれぞれのコーパス内に留める 2 つのフックがインストールされます。このフックがなければ、どちらも信頼できません。

初回セットアップ — npm run setupで実際に行われること

npm run setupは、名前を指定して要求していない2つのものを、gitignore対象の.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 — ツールチェーン、テスト／リンターのゲート、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をご覧ください。