mcp-architector

MCP Architector

アーキテクチャとシステム設計のための Model Context Protocol (MCP) サーバー

ローカルファーストの MCP サーバーで、プロジェクトのアーキテクチャ情報を保存・管理します。プライバシーと機密性を最大限に保つため、すべてのデータはローカルの ~/.mcp-architector に保存されます。

📦 インストール: npm install -g mcp-architector または npx 経由で使用 🌐 npm: https://www.npmjs.com/package/mcp-architector 🔗 GitHub: https://github.com/theSharque/mcp-architect

Claude Desktop / IDE への接続方法

MCP 設定にサーバーを追加します。claude_desktop_config.json の例：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Cursor IDE の場合：Settings → Features → Model Context Protocol → Edit Config の順に開き、mcpServers 内に同じブロックを追加します。他のオプションについては、連携 セクションを参照してください。

Cursor ルール（推奨）

Cursor IDE と Cursor Cloud Agents では、エージェントがリポジトリ全体を一度にコンテキストへ読み込まないよう、段階的なオンボーディングルールを使用してください。

1. .cursor/rules/architector-onboarding.mdc をプロジェクト（ドキュメント化するリポジトリ）にコピーします：

   mkdir -p /path/to/your-app/.cursor/rules
   cp /path/to/mcp-architector/.cursor/rules/architector-onboarding.mdc /path/to/your-app/.cursor/rules/
   

2. MCP Architector が接続されていることを確認します。エージェントは list-projects を呼び出し、書き込みのたびに projectId を渡す必要があります。省略に頼らないでください。

3. チャットで、たとえば 「このリポジトリを architector に登録して — まずフェーズ 0 の計画から」 または 「アーキテクチャをモジュールごとにインポートして」 と依頼します。

このルールは alwaysApply: false です。Cursor は、タスクがアーキテクチャのインポート／オンボーディングに該当するときにこのルールを適用します。このルールにより、構造 → 1 ステップにつき 1 モジュール → 各ステップ後に validate → コンパクトなツールのみ、という流れが徹底されます。

このサーバーのリポジトリを開発する場合は、このファイルをここにも置いておき、コントリビューターと Cloud Agents が ~/.mcp-architector/_qs_mcp-architector/ を更新するときに同じワークフローに従えるようにしてください。

概要

プロジェクトのアーキテクチャ、モジュール、スクリプト、データフロー、使用例を、完全なプライバシーを保ちながら、すべてローカルで保存・管理します。

機能

• ローカルストレージ: すべてのデータを ~/.mcp-architector に保存（プライバシーを最優先）
• プロジェクトアーキテクチャ: プロジェクト全体のアーキテクチャを保存・取得
• モジュールの詳細: 各モジュールの詳細情報
• リソース: リソースを通じてアーキテクチャデータにアクセス

ストレージ構造

~/.mcp-architector/
└── {projectId}/
    ├── architecture.json      # Modules + dataFlow (vertical structure)
    ├── modules/
    │   ├── {moduleId}.json
    │   └── ...
    ├── entries/
    │   ├── index.json         # Catalog (no duplicate bodies)
    │   └── {entryId}.json     # Canonical facts (API, domain, flows, …)
    ├── slices/
    │   └── {sliceId}.json     # Custom filters only (no items)

データモデル

レイヤー	目的	ツール
Modules	垂直構造：コンポーネント、依存関係、dataFlow	set-project-architecture, set-module-details, set-module-data-flow, rebuild-data-flow, validate-architecture
Entries	水平方向の情報に対する信頼できる唯一の情報源（1 つの情報 = 1 ファイル）	set-entry, set-entries, get-entry, list-entries
Slices	entries に対する読み取り専用ビュー（組み込みまたはカスタムのフィルター）	list-slices, get-slice

アンチパターン（重複禁止）： module.description を entry.summary にコピーしないでください。refs.moduleName でリンクします。Slices に項目のコピーは保存せず、slices/*.json にフィルターのみを保存します。

~/.mcp-architector を直接編集しないでください — タイムスタンプ、マージのセマンティクス、dataFlow の逆方向同期に一貫性を保つため、必ず MCP ツールを使用してください。

エージェントのワークフロー

1. list-projects — このワークスペースの projectId を見つけます（フォルダー名で検索）。ほかのすべてのツールに渡してください。省略しないでください。default-project は使用しないでください。
2. 構造に関するタスク → get-project-architecture / set-project-architecture。
3. 各モジュール → set-module-details で files と facts[]（エンドポイント、エンティティ、用語集）を同じ呼び出しで指定するか、refs.moduleName を指定して set-entries / set-entry を使用します。
4. 単一モジュールのグラフエッジ → set-module-data-flow。
5. フローの一括再構築（多数のモジュール） → rebuild-data-flow。
6. 編集後はすべて検証 → validate（概要 + issues[]。プロジェクト全体は読み込みません）。
7. カテゴリが必要な場合（すべての API、すべてのドメイン用語など）→ list-slices → format=compact または table を指定して get-slice を実行します。hasMore が true の場合は offset を使用します。
8. 名前で検索 → search-entries → 完全なペイロードを取得するには get-entry を実行します。
9. コードのリファクタリング後（同じモジュール） → refactor-architecture：scan → dryRun プレビュー → confirm=true を指定して適用します。

シナリオ	ツール
1 つのモジュールとその API／ファクトを更新	facts[] を指定した set-module-details
ドメインのファクトを一括登録	moduleName を指定した set-entries
1 つのモジュールの dataFlow をパッチ	set-module-data-flow
すべてのモジュールエッジを再構築	rebuild-data-flow
グラフと空のスライスを診断	validate（または validate-architecture）
カタログ JSON が破損（JSON の後に余分なデータがある）	fix-data
リファクタリング後にパス／名前を同期	refactor-architecture（dryRun の後に確定）
インデックスが同期していない	rebuild-entry-index
プロジェクトを一から作成	replaceModules: true を指定した set-project-architecture
新しい git clone のオンボーディング（段階的）	.cursor/rules/architector-onboarding.mdc をコピー → エージェントに段階ごとのオンボーディングを依頼

プロジェクト全体の概要： モジュールだけではスライスにデータが追加されません。http-endpoint（およびその他の種類）のエントリーがなければ、スライス api は空のままです。新しいモジュールを追加するときは、同じ手順で facts またはエントリーも追加してください。

例：facts: [{ kind: "http-endpoint", title: "POST /orders", ... }] を指定して set-module-details を実行し、その後 sliceId=api と format=table を指定して get-slice を実行します。

クイックスタート

ユーザー向け（npm パッケージを使用）

# No installation needed - use directly in Cursor/Claude Desktop
# Just configure it as described in Integration section below

開発者向け

1. リポジトリをクローンします：

git clone https://github.com/theSharque/mcp-architect.git
cd mcp-architect

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

使用方法

開発モード

ホットリロードを有効にして実行します：

npm run dev

本番モード

サーバーを起動します：

npm start

MCP Inspector

MCP Inspector でサーバーをデバッグおよびテストします：

npm run inspector

統合

Cursor IDE

1. Cursor の設定 → 機能 → Model Context Protocol を開きます
2. 「Edit Config」ボタンをクリックします
3. 以下の設定のいずれかを追加します

オプション 1：npm 経由（推奨）

npm レジストリから自動的にインストールします：

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

オプション 2：npm link 経由（開発用）

変更を即時反映するローカル開発の場合：

{
  "mcpServers": {
    "architector": {
      "command": "mcp-architector",
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

必要なコマンド：cd /path/to/mcp-architector && npm link -g

オプション 3：直接パス

{
  "mcpServers": {
    "architector": {
      "command": "node",
      "args": ["/path/to/mcp-architector/dist/index.js"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します：

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

Continue.dev

.continue/config.json を編集します：

{
  "mcpServers": {
    "architector": {
      "command": "npx",
      "args": ["-y", "mcp-architector"],
      "env": {
        "MCP_PROJECT_ID": "${workspaceFolder}"
      }
    }
  }
}

プロジェクト ID の使用

list-projects を除くすべてのツールで、projectId の指定が必須です。デフォルトのダンププロジェクトはありません。

1. 最初に list-projects を呼び出します（任意で query にワークスペースのフォルダー名を指定します）
2. 一致する projectId をほかのすべてのツールに渡します
3. 一致するものがない場合は、ワークスペースのパスから安定した ID（例：_qs_my-app）を使用して set-project-architecture で作成します

MCP_PROJECT_ID はヒントにすぎません（isCurrent / suggestedProjectId）。暗黙的な書き込み先としては使用されません。default-project と、置換されていない ${workspaceFolder} の ID は使用できません。

ツール

set-project-architecture

プロジェクト全体のアーキテクチャを作成または更新します。デフォルトでは、モジュールと dataFlow を名前でマージします。既存のフローを保持するには、dataFlow を省略してください。dependsOn が正規の値であり、保存時に providesTo が再計算されます。

入力：

• projectId（必須）：list-projects から取得したプロジェクト ID。省略しないでください。default-project は使用できません。
• description：プロジェクト全体の説明
• modules：モジュールオブジェクトの配列。各オブジェクトには以下を指定します。
  • name：モジュール名
  • description：モジュールの簡単な説明
  • inputs（任意）：このモジュールの動作に必要なもの
  • outputs（任意）：このモジュールが生成または出力するもの
• dataFlow（任意）：モジュール間のデータフローを記述するオブジェクト（既存の設定を保持するには省略します）。
  • キー：モジュール名
  • 値：以下を含むオブジェクト
    • dependsOn（任意）：このモジュールが依存するモジュール名の配列
    • providesTo（任意）：すべての dependsOn エッジから保存時に導出されます
    • dataTransformation（任意）：モジュール間でデータがどのように変換されるか
• replaceModules（任意）：モジュールリスト全体を置き換えます（デフォルトの false では名前でマージします）
• replaceDataFlow（任意）：dataFlow 全体を置き換えます（デフォルトの false ではモジュール名でマージします）

出力：

• プロジェクト ID と成功メッセージ

get-project-architecture

プロジェクト全体のアーキテクチャを取得します。

入力：

• projectId（必須）：list-projects から取得したプロジェクト ID。省略しないでください。default-project は使用できません。

出力：

• プロジェクトアーキテクチャ全体

list-projects

ローカルストレージ（~/.mcp-architector）内のすべてのプロジェクトを一覧表示します。最初にこれを呼び出してください。 フォルダー名を使って現在のワークスペースを特定し、その後、他のすべてのツールに projectId を渡してください。

入力：

• query（任意）：projectId または説明に含まれる部分文字列で絞り込みます（大文字と小文字を区別しません）

出力：

• projects[]：projectId、description、moduleCount、updatedAt、isCurrent（MCP_PROJECT_ID に基づくヒント）、forbidden（default-project および未置換の workspaceFolder のダンプ）
• suggestedProjectId：有効な ID の場合は現在の MCP_PROJECT_ID、それ以外の場合は null
• reminder：常に projectId を渡し、default-project は使用しないでください

エントリーとスライス

ツール	目的
set-entry	1 件の情報を追加または更新します。モジュールが不足している場合やリンクされていない場合、応答に reminder が含まれることがあります
set-entries	一括で追加または更新します（最大 200 件）。任意の moduleName を指定すると、すべての項目に refs.moduleName が設定されます
get-entry	id でエントリー全体を取得します
delete-entry	エントリーを削除します
list-entries	ペイロードを含まないカタログを表示します。kind、tags、query で絞り込みます
search-entries	snippet、slices、moduleName、ページネーションを含む簡潔なテキスト検索です。フィルター：moduleName、kind、tags
list-slices	組み込みスライスとカスタムスライスをエントリー数とともに表示します
get-slice	フィルターされたビュー：sliceId、format、query、limit、offset、hasMore
set-slice	カスタムフィルター（kinds、tags）を保存します。アイテムは含まれません
delete-slice	カスタムスライスを削除します
rebuild-entry-index	エントリーファイルから entries/index.json を再構築します
fix-data	残存または破損したカタログ JSON を修復し、インデックスを再構築します

組み込みの sliceId 値： api、persistence、events、domain、flows、integrations、config、runtime、decisions、scripts。

search-entries

簡潔なナビゲーション検索です。ヒットを選ぶのに十分なコンテキストを返し、その後 get-entry を呼び出してペイロード全体を取得します。

入力： query（必須）、moduleName、kind、tags、limit（デフォルト 10、最大 50）、offset（デフォルト 0）

出力： summary、total、returned、offset、hasMore、snippet、matchedIn、slices、moduleName に加えてレガシー形式の summary、tags、refs を含む results[]

推奨される kind の例（任意の文字列を使用できます）：

sliceId	kinds
api	http-endpoint、grpc-method、mcp-tool、cli-command、…
persistence	db-table、entity、repository
domain	glossary、invariant、lifecycle
scripts	script — set-entry / get-slice sliceId=scripts を使用します

set-module-details

モジュールの詳細情報を作成または更新します。スライスはモジュールのテキストではなくエントリーを読み取ります — facts[] を渡すと、1 回の呼び出しでリンクされたエントリーを作成できます。

入力：

• projectId（必須）：list-projects のプロジェクト ID
• name：モジュール名
• description：モジュールの詳細な説明
• inputs：モジュールが入力として受け付けるもの
• outputs：モジュールが出力として生成するもの
• dependencies（任意）：モジュール依存関係のリスト（指定すると dataFlow.dependsOn に同期されます）
• files（任意）：このモジュールに属するファイルのリスト
• facts（任意）：横断的なファクトの配列（kind、title、summary、…） — それぞれ refs.moduleName = モジュール名のエントリーとしてアップサートされます
• usageExamples（任意）：次のフィールドを持つ使用例の配列：
  • title：例のタイトル
  • description（任意）：例の説明
  • command（任意）：コマンドまたはコードスニペット
  • input（任意）：入力データ
  • output（任意）：想定される出力
  • notes（任意）：例に関する追加の注意事項
• notes（任意）：追加の注意事項

出力：

• モジュール ID と成功メッセージ

set-module-data-flow

アーキテクチャ全体を送信せずに、単一モジュールの dataFlow にパッチを適用します。

入力：

• projectId（必須）：list-projects のプロジェクト ID
• moduleName：モジュール名
• dependsOn（任意）：このモジュールが依存するモジュール（正規の値）
• dataTransformation（任意）：データの変換方法
• syncInverse（任意）：providesTo を再計算します（デフォルトは true）

出力：

• モジュール名と成功メッセージ

rebuild-data-flow

モジュールファイルの dependencies または既存の dependsOn エッジから、すべてのモジュールの dataFlow を再構築します。architecture.json の一括手動編集に代わるものです。

入力：

• projectId（必須）：list-projects のプロジェクト ID
• source（任意）：module-dependencies（デフォルト）または dataFlow-dependsOn
• syncInverse（任意）：providesTo を再計算します（デフォルトは true）
• pruneOrphans（任意）：無効なモジュール参照を削除します（デフォルトは true）

出力：

• edgesAdded、edgesRemoved、modulesUpdated、メッセージ

validate

編集後に行う主なチェックです。 エージェント向けに簡潔にまとめたレポートを提供する読み取り専用の検証です。データは変更しません。

チェック項目（保存された JSON から検証可能なルールのみ）：

• dataFlow：逆方向の不整合、参照先のない dependsOn／providesTo、孤立したフローキー
• module.dependencies と dataFlow.dependsOn の不一致
• エントリー：entries-without-modules、entry-unlinked、orphan-entry-module、module-no-entries、module-missing-api / module-missing-persistence、entry-slice-orphan、module-too-many-entries、module-too-few-entries
• ストレージ：modules/{id}.json の欠落、孤立したモジュールファイル、エントリーインデックスの不整合
• スライス：モジュールが存在する場合に、組み込みの api / domain / persistence が空であること

入力： projectId、checkInverse、checkModuleDeps、checkEntryCoverage、checkStorage、checkEmptySlices、checkSliceCoverage、checkModuleEntryCounts、moduleEntryMax（デフォルトは 50）、moduleEntryMin（任意。省略すると最小値チェックを無効化） — 注記があるものを除き、すべてのブール値フラグのデフォルトは true です

出力： valid、issueCount、summary、stats、issuesByKind、issues[]、coverage、checksRun

fix-data

カタログの JSON が破損している場合（たとえば、list-modules / validate が JSON の後に余分なデータがあるというエラーで失敗する場合）に実行します。architecture.json、modules/、entries/、slices/ の最初の有効な JSON オブジェクト以降に残っているバイトを切り詰め、残存する .tmp ファイルを削除して、エントリーインデックスを再構築します。ファクトは削除しません。カタログへの書き込みには一時ファイルとリネームを使用するため、この残存データが再発することはありません。

入力： projectId、dryRun（任意、デフォルトは false）

出力： summary、scanned、repaired、unreadable、tmpRemoved、indexItemCount、files[]（修復済みまたは読み取り不能のファイルのみ）

refactor-architecture

モジュール境界が変わらないコードリファクタリング後に、アーキテクチャ内の同期をプレビューまたは適用します。情報の正となるのはエージェントです。ワークスペースや Git にはアクセスしません。dryRun=true がデフォルトです。

ワークフロー：（1）file または text を指定して scan → ヒットを簡潔に表示、（2）変更操作を作成、（3）dryRun でプレビュー、（4）dryRun=false と confirm=true を指定して適用します。

操作（1 回あたり最大 10 件）： scan、move-file、replace-path-prefix、rename-text、patch-entry、merge-files、remove-file-ref。

対象範囲（任意）： moduleName、kinds、tags — 変更対象のエントリやモジュールを制限します。

refs.files が空で、refs.entryIds がない孤立したエントリは、ファイル操作の後に削除されます。

入力： projectId、operations[]、scope、dryRun（デフォルトは true）、confirm（適用時に必須）、limit、offset

出力： summary、stats、hits（スキャン時）、またはページ分割された changes、warnings、hasMore

validate-architecture

validate と同じです（旧名称のエイリアス）。編集後は validate を優先してください。

出力：

• valid（ブール値）、issues 配列

get-module-details

特定のモジュールの詳細情報を取得します。

入力：

• projectId（必須）：list-projects で取得したプロジェクト ID
• moduleName：取得するモジュールの名前

出力：

• モジュールの詳細情報一式

list-modules

プロジェクトのアーキテクチャにあるすべてのモジュールを一覧表示します。

入力：

• projectId（必須）：list-projects で取得したプロジェクト ID

出力：

• モジュール概要の配列

delete-module

プロジェクトのアーキテクチャからモジュールを削除します。

入力：

• projectId（必須）：list-projects で取得したプロジェクト ID
• moduleName：削除するモジュールの名前

出力：

• 成功メッセージ

リソース

architecture

プロジェクトのアーキテクチャにリソースとしてアクセスできます。

使用方法： URI arch://{projectId} からアクセスします。

module

モジュールの詳細にリソースとしてアクセスできます。

使用方法： URI module://{projectId}/{moduleId} からアクセスします。

開発

プロジェクト構成

mcp-architector/
├── src/
│   ├── index.ts          # Main server implementation
│   ├── types.ts          # Type definitions
│   └── storage.ts        # Storage utilities
├── dist/                 # Compiled output (generated)
├── package.json
├── tsconfig.json
└── README.md

プロジェクト ID

サーバーは各プロジェクトを ~/.mcp-architector/{projectId}/ に保存します。list-projects 以外のすべてのツールでは、projectId を明示的に渡す必要があります。

• list-projects を呼び出し、query にワークスペースフォルダー名を指定して ID を確認します
• MCP_PROJECT_ID は一覧表示のヒント（isCurrent / suggestedProjectId）に限られ、暗黙の書き込み先にはなりません
• default-project および置換されていない ${workspaceFolder} の ID は使用できません

新しいプロジェクトを開始するには、ワークスペースのパスから導出した安定した ID（例：_qs_my-app）を set-project-architecture に渡します。

サーバーの拡張

新しいツール、リソース、またはプロンプトを追加するには、src/index.ts を編集します。

// Add a tool
server.registerTool(
  "tool-name",
  { /* tool config */ },
  async (params) => { /* handler */ }
);

// Add a resource
server.registerResource(
  "resource-name",
  new ResourceTemplate("uri-template", { /* options */ }),
  { /* resource config */ },
  async (uri, params) => { /* handler */ }
);

// Add a prompt
server.registerPrompt(
  "prompt-name",
  { /* prompt config */ },
  (args) => { /* handler */ }
);

ライセンス

MIT