project-knowledge-mcp

プロジェクトナレッジ MCP サーバー

Model Context Protocol（MCP）向けの、プロジェクト横断型ナレッジグラフです。 モバイル、バックエンド、管理画面の各コードベースにまたがる機能をマッピングし、テスト、コード作成、デバッグ、機能追加の際に、AI エージェントがフルスタックのコンテキストを把握できるようにします。

---

クイックスタート

npx -y project-knowledge-mcp --knowledge-file ./project-knowledge.json

次に、MCP の設定に追加します。

{
  "mcpServers": {
    "project-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "project-knowledge-mcp",
        "--knowledge-file", "C:\\projects\\project-knowledge.json"
      ],
      "autoApprove": []
    }
  }
}

---

目次

• 概要
• 機能
• 前提条件
• インストールと設定
• ナレッジファイルの管理
• ツールリファレンス
• 使用手順
• セキュリティ
• コントリビュート
• ライセンス

---

概要

課題

複数のコードベースを持つプロジェクト（たとえば、React Native のモバイルアプリ、NestJS のバックエンド、Next.js の管理画面）で作業する際、AI エージェントは単一の機能が3つすべてにどう流れるかを把握できません。そのため、コンテキストが不完全になり、依存関係を見落としたり、事前に防げたはずの破壊的変更が発生したりします。

解決策

この MCP サーバーは、機能のナレッジグラフを保存し、各ワークフローのステップを、すべてのプロジェクトにおける関連画面、エンドポイント、コントローラー、ファイルにマッピングします。これにより、AI エージェントはこのグラフをクエリして、機能のエンドツーエンドの流れを把握し、ファイル編集前にプロジェクト間への影響を検出し、コードベース間で型定義を同期できます。

---

機能

• 複数プロジェクトの認識 — モバイル、バックエンド、管理画面など、任意の数のプロジェクトを登録できます
• 機能ワークフローのマッピング — すべてのプロジェクトにまたがる順序付きのステップとして機能を定義できます
• 自動スキャン — NestJS のエンドポイント、Next.js のページ、React Native の画面を自動的に検出します
• 全文検索 — 機能、エンドポイント、ファイル、画面を横断して検索できます
• 相互参照の検索 — ファイルパスを指定して、そのファイルを参照する機能を検索できます
• 豊富なコンテキスト — 特定のワークフローステップにおける、機能のすべてのエンドポイント、画面、ファイルを取得できます
• 破壊的変更の検出 — ファイルを編集する前に、影響を受けるほかのプロジェクトを確認できます
• 型／スキーマの同期 — プロジェクト間で対応する型をマッピングできます（例：ProductCreateDto ↔ ProductFormSchema）
• アーキテクチャの調査 — キーワードによる絞り込みやコンテンツのハイライト表示を使って、任意のプロジェクトのディレクトリツリーを閲覧できます
• 健全性の検証 — 登録済みのすべてのファイルパスが引き続き存在することを確認し、古いエントリーを自動検出します
• 永続的なナレッジ — 変更のたびに JSON ファイルへ自動保存します。Git で追跡して共有できます
• 100％動的 — 設定はすべて CLI 引数と実行時ツールで行います。ソースコードの編集は不要です

---

前提条件

• Node.js >= 18
• npm >= 9（または pnpm／yarn 相当）
• MCP 対応クライアント（例：Cline を使用した VS Code、AI 搭載 IDE）

---

インストールと設定

npm からインストール（推奨）

npm install --save-dev project-knowledge-mcp

または、インストールせずに直接実行します。

npx -y project-knowledge-mcp --knowledge-file ./project-knowledge.json

ソースからビルド

git clone https://github.com/punic-pillars/project-knowledge-mcp.git
cd project-knowledge-mcp
npm install
npm run build

CLI フラグ

すべての設定は CLI 引数で指定します。環境変数や設定ファイルは必要ありません。

フラグ	説明	デフォルト
--backend-path	バックエンドプロジェクトの絶対パス	—
--backend-framework	バックエンドフレームワーク（nestjs、nextjs、react-native、または auto）	auto
--backend-name	バックエンドプロジェクトのカスタム名	backend
--mobile-path	モバイルプロジェクトの絶対パス	—
--mobile-framework	モバイルフレームワーク	auto
--mobile-name	モバイルプロジェクトのカスタム名	mobile
--admin-path	管理プロジェクトの絶対パス	—
--admin-framework	管理フレームワーク	auto
--admin-name	管理プロジェクトのカスタム名	admin
--knowledge-file	ナレッジ JSON を保存する絶対パス	./project-knowledge.json

MCP クライアントの設定

基本セットアップ — ツールを使って実行時にプロジェクトを登録します。

{
  "mcpServers": {
    "project-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "project-knowledge-mcp",
        "--knowledge-file", "C:\\projects\\project-knowledge.json"
      ],
      "autoApprove": []
    }
  }
}

ブートストラップセットアップ — 起動時にプロジェクトを事前登録します。

{
  "mcpServers": {
    "project-knowledge": {
      "command": "npx",
      "args": [
        "-y",
        "project-knowledge-mcp",
        "--knowledge-file", "C:\\projects\\project-knowledge.json",
        "--backend-path", "C:\\projects\\backend",
        "--mobile-path", "C:\\projects\\mobile",
        "--admin-path", "C:\\projects\\admin"
      ],
      "autoApprove": []
    }
  }
}

---

ナレッジファイルの管理

ナレッジファイルは、登録済みのすべてのプロジェクト、機能のワークフロー、型のマッピングを保存するプレーンな JSON ファイルです。ナレッジグラフの一貫性を保つには、ファイルの保存場所を把握することが重要です。

共有ファイルのパターン

フルスタックプロジェクトが別々のディレクトリ（例：backend/、mobile/、admin/）にある場合、IDE の各ウィンドウは異なる作業ディレクトリから MCP サーバーを起動します。--knowledge-file を指定しないと、各インスタンスはそれぞれ独自の断片を作成します。

backend/
└── project-knowledge.json   ← only backend context

mobile/
└── project-knowledge.json   ← only mobile context

admin/
└── project-knowledge.json   ← only admin context

これではプロジェクト間の連携を把握する目的が損なわれます。すべての IDE ウィンドウが同じファイルを参照するよう、常に --knowledge-file に絶対パスを指定してください。

projects/
├── project-knowledge.json   ← single source of truth
├── backend/
├── mobile/
└── admin/

開いているサブプロジェクトにかかわらず、IDE のすべてのウィンドウで同じ --knowledge-file のパスを使用してください。すべてのインスタンスが同じファイルを読み書きするため、ナレッジグラフを完全かつ一貫した状態に保てます。

デフォルトが安全な場合

デフォルトのパス（--knowledge-file を指定しない場合）が安全なのは、すべてのサブプロジェクトを含む単一のディレクトリであるモノレポのルートを開く場合に限られます。

my-monorepo/              ← open this in your IDE
├── project-knowledge.json   ← created here, covers everything
├── backend/
├── mobile/
└── admin/

プロジェクトが別々のリポジトリやディレクトリにある場合は、必ず --knowledge-file を使用してください。

チームとの共有

ナレッジファイルはプレーンな JSON なので、バージョン管理にコミットしてチームと共有できます。

# Track the knowledge graph
git add project-knowledge.json
git commit -m "chore: add project knowledge graph"

# Or keep it local
echo "project-knowledge.json" >> .gitignore

ガイドライン：フルスタックプロジェクト 1 つにつき、ナレッジファイル 1 つを使用します。プロジェクトが別々のディレクトリにある場合は、必ず --knowledge-file に絶対パスを指定してください。

---

ツールリファレンス

プロジェクト管理

ツール	説明
register_project	名前、パス、フレームワークを指定してプロジェクトを登録します
remove_project	登録済みのプロジェクトを削除します
scan_project	プロジェクトからエンドポイント、画面、ページを自動検出します

機能管理

ツール	説明
register_feature	複数プロジェクトにまたがるワークフローのステップとともに機能を定義します
remove_feature	機能を削除します
get_feature	機能の詳細全体を取得します（コンパクトまたは詳細形式。オプションでヘルスチェック付き）

検索とクエリ

ツール	説明
search	機能、エンドポイント、ファイル、画面を横断して検索します
reverse_lookup	ファイルへのプロジェクト間参照（グラフへの登録済みおよびスキャンで検出されたもの）と、そのファイルを参照する機能をすべて検索します
get_context	機能またはステップのプロジェクト間コンテキストを取得します（オプションで影響分析付き）

型／スキーマの同期

ツール	説明
register_type_mappings	1 つ以上の型マッピングを登録します（単一のオブジェクトまたは配列を受け付けます）
check_type_mapping	プロジェクト全体で、型を定義または参照しているファイルをすべて検索します
suggest_type_mappings	すべてのプロジェクトをスキャンし、型マッピングの候補を自動検出します

アーキテクチャの調査

ツール	説明
get_architecture	オプションの filter（パスのキーワード）、highlight（★マーカーを付けるコンテンツのキーワード）、showAll（一致箇所にマークを付けた完全なツリー）を指定して、プロジェクトのディレクトリツリーを調査します

検証

ツール	説明
validate_knowledge	登録済みのすべてのファイルパスを確認して古いエントリーを検出します。必要に応じて fix=true で自動修正できます

永続化

ツール	説明
export_knowledge	ナレッジファイルのパスを確認し、明示的な保存を実行します（自動永続化により、変更のたびに保存されます）
import_knowledge	JSON ファイルからナレッジを読み込みます（プレビュー付きで、マージまたは置換できます）

---

使用方法の概要

この概要では、実際の複数プロジェクト構成（NestJS バックエンド、React Native モバイルアプリ、Next.js 管理パネル）を使って、基本的なワークフローを説明します。ドメイン名は匿名化されており、「stations」の代わりに「products」、「reports」の代わりに「orders」を使用していますが、記載されているすべてのコマンドは実際のプロジェクトで実行したものです。

ステップ 1：プロジェクトを登録する

register_project { name: "backend", path: "C:/projects/backend", framework: "nestjs" }
register_project { name: "mobile", path: "C:/projects/mobile", framework: "react-native" }
register_project { name: "admin", path: "C:/projects/admin", framework: "auto" }

ステップ 2：プロジェクトをスキャンする

エンドポイント、画面、ページを自動的に検出します。

scan_project { projectName: "backend" }
scan_project { projectName: "mobile" }
scan_project { projectName: "admin" }

スキャナーは、登録済みのすべてのプロジェクトから 150 以上のエンドポイント、200 以上の画面、複数の管理ページを検出します。

ステップ 3：機能を定義する

3 つのプロジェクトすべてに関わるシンプルなフローとして、auth 機能を登録します。

register_feature {
  name: "auth",
  description: "Authentication flow — login, register, forgot password, email confirmation",
  workflow: [
    {
      step: 1, name: "Login",
      description: "User logs in with email and password",
      mobile: { screen: "LoginScreen", api: "POST /api/v1/auth/email/login" },
      backend: { endpoint: "POST /api/v1/auth/email/login", controller: "AuthController", file: "src/auth/auth.controller.ts" },
      admin: { page: "/login", file: "src/pages/Login" }
    },
    {
      step: 2, name: "Register",
      description: "User registers a new account",
      mobile: { screen: "RegisterScreen", api: "POST /api/v1/auth/email/register" },
      backend: { endpoint: "POST /api/v1/auth/email/register", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    },
    {
      step: 3, name: "Email Confirmation",
      description: "Confirm email address",
      mobile: { api: "POST /api/v1/auth/email/confirm" },
      backend: { endpoint: "POST /api/v1/auth/email/confirm", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    },
    {
      step: 4, name: "Forgot Password",
      description: "Request password reset",
      mobile: { screen: "ForgotPasswordScreen", api: "POST /api/v1/auth/forgot/password" },
      backend: { endpoint: "POST /api/v1/auth/forgot/password", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    },
    {
      step: 5, name: "Reset Password",
      description: "Reset password with token",
      mobile: { screen: "ResetPasswordScreen", api: "POST /api/v1/auth/reset/password" },
      backend: { endpoint: "POST /api/v1/auth/reset/password", controller: "AuthController", file: "src/auth/auth.controller.ts" }
    }
  ],
  test_scenarios: [
    "Login with valid credentials returns token",
    "Login with invalid email returns 401",
    "Register with existing email returns conflict",
    "Forgot password sends email",
    "Reset password with valid token works"
  ]
}

ステップ 4：機能を照会する

コンパクトモード — 概要を取得します。

get_feature { name: "auth" }

結果：5 つのステップ、5 つのテストシナリオ、モバイル画面 5 件、バックエンドエンドポイント 5 件、管理ページ 1 件。

詳細モード — ワークフローの詳細をすべて取得します。

get_feature { name: "auth", verbose: true }

5 つのステップすべてについて、モバイル画面、バックエンドエンドポイント、コントローラー、ファイルパスの詳細が返されます。

ヘルスチェック付き — 登録済みのすべてのパスが存在することを確認します。

get_feature { name: "auth", includeHealth: true }

結果：ヘルスチェック：バックエンド 5/5 件が正常、モバイル 5/5 件、管理パネル 1/5 件、テストシナリオ 5 件。

ステップ 5：検索と相互参照

ナレッジグラフ全体を検索します。

search { query: "product" }

機能、ワークフローのステップ、バックエンドのマッピング、モバイルのマッピング、型のマッピング、ファイルの内容から 100 件以上の結果が返されます。

ファイルへのプロジェクト横断の参照を検索します。

reverse_lookup { filePath: "auth.controller.ts" }

結果：

• 機能との関連付け：このファイルを参照する機能（auth 機能のステップ 1～5）
• グラフに登録済み：完全一致 5 件（auth 機能のステップ 1～5。すべてバックエンド）、および管理パネルの Login ページ
• スキャンで検出：すべてのプロジェクトから、auth.controller.ts をインポートまたは参照しているファイルすべて

ステップ 6：型のマッピング

プロジェクトをまたぐ型のマッピングを登録します。

register_type_mappings {
  mapping: {
    typeName: "productId",
    sourceProject: "backend",
    sourceFile: "src/products/infrastructure/persistence/relational/entities/product.entity.ts",
    targetProject: "mobile",
    targetFile: "app/_types/ProductTypes.ts",
    description: "Standardizing productId as numeric INTEGER across all projects"
  }
}

型を変更する前に、その型を参照している箇所を確認します。

check_type_mapping { typeName: "productId" }

すべてのプロジェクトから、productId を定義または参照しているファイルがすべて返されます。

型のマッピング候補を自動検出します。

suggest_type_mappings { limit: 5, confidence: "high" }

登録済みのすべてのプロジェクトをスキャンし、型名が完全に一致するものを検出します。登録に使えるソースとターゲットのファイルパスを含む候補が返されます。

ステップ 7：検証とエクスポート

ナレッジの状態を検証します。

validate_knowledge

すべての機能と型のマッピングに含まれる、登録済みのファイルパスをすべて確認します。存在するエントリーと見つからないエントリーのレポートが返されます。

永続化を確認します。

ナレッジグラフは変更のたびに自動的に永続化されます。register_project、register_feature、register_type_mappings、および fix=true を指定した validate_knowledge は、すべてディスクに即時書き込みを行います。バージョン管理にコミットする前に、export_knowledge を使ってファイルパスを確認してください。

export_knowledge

ナレッジファイルのパスが返されます。このファイルを Git で管理すると、チームでコンテキストを共有できます。

---

セキュリティ

• ナレッジファイルはプレーンな JSON です — 保存場所とアクセス権限は自分で管理できます
• 認証情報は保存されません — この MCP が保存するのはプロジェクトのパスと機能のマッピングのみです
• ファイルのスキャンは読み取り専用です — スキャナーはファイルを読み取るだけで、変更は行いません

---

コントリビューション

コントリビューションを歓迎します。改善、バグ修正、機能のリクエストがある場合は、Issue またはプルリクエストを作成してください。

---

ライセンス

MIT