feat: add @topology/mcp package with MCP Server, Resources and Tools

Author: 7Jerrybf

CLAUDE.md

@@ -147,6 +147,12 @@ code-topology/
 │   │       ├── reporter/  # 報告生成 (Markdown/JSON)
 │   │       ├── plugins/   # 語言插件系統 + built-in plugins
 │   │       └── analyze.ts # 高階分析 API (AST + Semantic 雙引擎)
+│   ├── mcp/               # @topology/mcp - MCP Server (Model Context Protocol for AI agents)
+│   │   └── src/
+│   │       ├── index.ts   # bin entry: McpServer + stdio transport
+│   │       ├── state.ts   # TopologyState: 快取分析結果
+│   │       ├── tools.ts   # 6 個 MCP tools (analyze, dependencies, impact, etc.)
+│   │       └── resources.ts # 3 個 MCP resources (graph, stats, node)
 │   ├── server/            # @topology/server - L3: WebSocket 伺服器, 檔案監視
 │   └── web/               # @topology/web - L4: Next.js + React Flow + elkjs 視覺化
 ├── cli/                   # @topology/cli - 薄殼 CLI (commander → core + server)
@@ -157,7 +163,7 @@ code-topology/
 └── CLAUDE.md
 ```
 
-**Build DAG**: `protocol` → `core` → `server` → `cli` / `web`
+**Build DAG**: `protocol` → `core` → `server` / `mcp` → `cli` / `web`
 
 **關鍵技術**:
 - **佈局引擎**: elkjs (取代 dagre)
@@ -166,6 +172,7 @@ code-topology/
 - **插件系統**: LanguagePlugin interface + pluginRegistry
 - **向量引擎**: onnxruntime-node + Xenova/all-MiniLM-L6-v2 (384 維, int8 量化)
 - **本地緩存**: better-sqlite3 (ParseCache + EmbeddingCache)
+- **MCP Server**: @modelcontextprotocol/sdk (stdio transport, 6 tools + 3 resources)
 
 ---
 
@@ -199,7 +206,12 @@ code-topology/
 
 ### Phase 3: The "Arbiter" (Agent Interaction)
 
-* [ ] 實作 MCP Server：讓 Cursor/Claude 可以讀取拓撲圖數據。
+* [x] **MCP Server** (`@topology/mcp`): 實作 Model Context Protocol 伺服器，讓 Cursor/Claude Desktop 直接查詢拓撲圖。
+  * Stdio transport（零網路開銷）
+  * 3 Resources: `topology://graph`、`topology://stats`、`topology://node/{filePath}`
+  * 6 Tools: `analyze`、`get_dependencies`、`get_broken_edges`、`find_similar_files`、`get_file_impact`、`generate_report`
+  * TopologyState 快取管理（首次呼叫觸發分析，後續讀快取）
+  * BFS 依賴鏈搜尋（正向/反向，可設定深度）
 * [ ] 實作「衝突預警」：當兩個 Git 分支修改了語義相近的節點時，UI 發出警報。
 * [ ] 推出 Docker Image，支援團隊私有化部署。
 

packages/mcp/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@topology/mcp",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "MCP server for code-topology — expose topology data to AI agents",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "topology-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@topology/protocol": "workspace:*",
+    "@topology/core": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}

packages/mcp/src/index.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { TopologyState } from './state.js';
+import { registerResources } from './resources.js';
+import { registerTools } from './tools.js';
+
+const server = new McpServer({
+  name: 'code-topology',
+  version: '0.1.0',
+});
+
+const state = new TopologyState();
+
+registerResources(server, state);
+registerTools(server, state);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

packages/mcp/src/resources.ts

@@ -0,0 +1,115 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { TopologyState } from './state.js';
+
+export function registerResources(server: McpServer, state: TopologyState): void {
+  // Resource 1: Full topology graph
+  server.resource(
+    'graph',
+    'topology://graph',
+    { description: 'Full topology graph with all nodes and edges (dependency + semantic)' },
+    async () => {
+      const graph = await state.ensureGraph();
+      return {
+        contents: [
+          {
+            uri: 'topology://graph',
+            mimeType: 'application/json',
+            text: JSON.stringify(graph, null, 2),
+          },
+        ],
+      };
+    },
+  );
+
+  // Resource 2: Summary statistics
+  server.resource(
+    'stats',
+    'topology://stats',
+    { description: 'Summary statistics: node count, edge count, broken edges, semantic edges, languages' },
+    async () => {
+      const graph = await state.ensureGraph();
+
+      const languageCounts: Record<string, number> = {};
+      for (const node of graph.nodes) {
+        const lang = node.language ?? 'unknown';
+        languageCounts[lang] = (languageCounts[lang] ?? 0) + 1;
+      }
+
+      const stats = {
+        nodeCount: graph.nodes.length,
+        edgeCount: graph.edges.length,
+        dependencyEdges: graph.edges.filter((e) => e.linkType !== 'semantic').length,
+        semanticEdges: graph.edges.filter((e) => e.linkType === 'semantic').length,
+        brokenEdges: graph.edges.filter((e) => e.isBroken).length,
+        languages: languageCounts,
+        timestamp: graph.timestamp,
+      };
+
+      return {
+        contents: [
+          {
+            uri: 'topology://stats',
+            mimeType: 'application/json',
+            text: JSON.stringify(stats, null, 2),
+          },
+        ],
+      };
+    },
+  );
+
+  // Resource 3: Node detail by file path (ResourceTemplate)
+  server.resource(
+    'node',
+    new ResourceTemplate('topology://node/{filePath}', { list: undefined }),
+    { description: 'Node details and related edges for a specific file (use URL-encoded path)' },
+    async (uri, params) => {
+      const graph = await state.ensureGraph();
+      const filePath = decodeURIComponent(params.filePath as string);
+
+      const node = graph.nodes.find((n) => n.id === filePath);
+      if (!node) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: 'application/json',
+              text: JSON.stringify({ error: `Node not found: ${filePath}` }),
+            },
+          ],
+        };
+      }
+
+      const imports = graph.edges.filter(
+        (e) => e.source === filePath && e.linkType !== 'semantic',
+      );
+      const importedBy = graph.edges.filter(
+        (e) => e.target === filePath && e.linkType !== 'semantic',
+      );
+      const similar = graph.edges.filter(
+        (e) =>
+          e.linkType === 'semantic' &&
+          (e.source === filePath || e.target === filePath),
+      );
+
+      const detail = {
+        node,
+        imports: imports.map((e) => ({ target: e.target, isBroken: e.isBroken })),
+        importedBy: importedBy.map((e) => ({ source: e.source, isBroken: e.isBroken })),
+        similar: similar.map((e) => ({
+          file: e.source === filePath ? e.target : e.source,
+          similarity: e.similarity,
+        })),
+      };
+
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: 'application/json',
+            text: JSON.stringify(detail, null, 2),
+          },
+        ],
+      };
+    },
+  );
+}

packages/mcp/src/state.ts

@@ -0,0 +1,43 @@
+import { analyzeDirectory, type AnalyzeOptions } from '@topology/core';
+import type { TopologyGraph } from '@topology/protocol';
+
+export class TopologyState {
+  private graph: TopologyGraph | null = null;
+  private analyzeInProgress: Promise<TopologyGraph> | null = null;
+  private readonly analyzePath: string;
+
+  constructor(path?: string) {
+    this.analyzePath = path ?? process.cwd();
+  }
+
+  async ensureGraph(options?: AnalyzeOptions): Promise<TopologyGraph> {
+    if (this.graph) {
+      return this.graph;
+    }
+    return this.refresh(options);
+  }
+
+  async refresh(options?: AnalyzeOptions): Promise<TopologyGraph> {
+    // Deduplicate concurrent calls
+    if (this.analyzeInProgress) {
+      return this.analyzeInProgress;
+    }
+
+    this.analyzeInProgress = analyzeDirectory(this.analyzePath, options)
+      .then((graph) => {
+        this.graph = graph;
+        this.analyzeInProgress = null;
+        return graph;
+      })
+      .catch((err) => {
+        this.analyzeInProgress = null;
+        throw err;
+      });
+
+    return this.analyzeInProgress;
+  }
+
+  getGraph(): TopologyGraph | null {
+    return this.graph;
+  }
+}