analyzeGraph
Analyzes graph data from Heptabase whiteboards, calculating centrality, clustering, and density metrics, and exports results to a specified path.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| exportPath | No | ||
| metrics | No | ||
| whiteboardId | No |
Implementation Reference
- src/tools/analysis.ts:20-108 (handler)Core handler function executing the analyzeGraph tool logic, fetching graph data, computing metrics (centrality, clustering, density), generating analysis text, and optionally exporting to file.export async function analyzeGraph( dataService: HeptabaseDataService, params: z.infer<typeof analyzeGraphSchema> ) { let analysis: any = { timestamp: new Date().toISOString(), metrics: {} }; if (params.whiteboardId) { // Analyze specific whiteboard const data = await dataService.getWhiteboard(params.whiteboardId, { includeCards: true, includeConnections: true }); analysis.whiteboard = data.whiteboard.name; analysis.nodes = data.cards?.length || 0; analysis.edges = data.connections?.length || 0; } else { // Analyze entire knowledge graph const whiteboards = await dataService.getWhiteboards(); const cards = await dataService.getCards(); const connections = await dataService.getConnections(); analysis.whiteboards = whiteboards.length; analysis.nodes = cards.length; analysis.edges = connections.length; } // Calculate metrics if requested if (params.metrics?.includes('centrality')) { analysis.metrics.centrality = await calculateCentrality(dataService, params.whiteboardId); } if (params.metrics?.includes('clustering')) { analysis.metrics.clustering = await calculateClustering(dataService, params.whiteboardId); } if (params.metrics?.includes('density')) { analysis.metrics.density = analysis.edges / (analysis.nodes * (analysis.nodes - 1)); } // Format response let text = 'Knowledge Graph Analysis\n\n'; if (params.whiteboardId) { text += `Whiteboard: ${analysis.whiteboard}\n`; } else { text += `Total whiteboards: ${analysis.whiteboards}\n`; } text += `Total nodes: ${analysis.nodes}\n`; text += `Total edges: ${analysis.edges}\n`; if (analysis.metrics.centrality) { text += '\nCentrality:\n'; text += 'Most central nodes:\n'; const sorted = Object.entries(analysis.metrics.centrality) .sort(([, a]: any, [, b]: any) => b - a) .slice(0, 5); for (const [nodeId, score] of sorted) { text += `- ${nodeId}: ${score}\n`; } } if (analysis.metrics.clustering) { text += `\nClustering coefficient: ${analysis.metrics.clustering}\n`; } if (analysis.metrics.density) { text += `\nGraph density: ${analysis.metrics.density.toFixed(3)}\n`; } // Export if requested if (params.exportPath) { await fs.mkdir(path.dirname(params.exportPath), { recursive: true }); await fs.writeFile(params.exportPath, JSON.stringify(analysis, null, 2), 'utf8'); text += `\nAnalysis saved to ${params.exportPath}`; } return { content: [{ type: 'text', text }] }; }
- src/tools/analysis.ts:7-11 (schema)Zod schema defining input parameters for the analyzeGraph tool: optional whiteboardId, metrics array, and exportPath.export const analyzeGraphSchema = z.object({ whiteboardId: z.string().optional(), metrics: z.array(z.enum(['centrality', 'clustering', 'density'])).optional(), exportPath: z.string().optional() });
- src/server.ts:702-708 (registration)Registers the analyzeGraph tool in the tools object with schema and wrapped handler.this.tools.analyzeGraph = { inputSchema: analyzeGraphSchema, handler: async (params) => { await this.ensureDataServiceInitialized(); return analyzeGraph(this.dataService, params); } };
- src/server.ts:710-712 (registration)Registers the analyzeGraph tool with the MCP server using the schema and handler.this.server.tool('analyzeGraph', analyzeGraphSchema.shape, async (params: z.infer<typeof analyzeGraphSchema>) => { return this.tools.analyzeGraph.handler(params); });
- src/tools/analysis.ts:221-235 (helper)Helper function to calculate degree centrality for nodes in the graph.async function calculateCentrality(dataService: HeptabaseDataService, whiteboardId?: string): Promise<Record<string, number>> { const connections = whiteboardId ? (await dataService.getWhiteboard(whiteboardId, { includeConnections: true })).connections || [] : await dataService.getConnections(); const centrality: Record<string, number> = {}; // Calculate degree centrality for (const connection of connections) { centrality[connection.beginId] = (centrality[connection.beginId] || 0) + 1; centrality[connection.endId] = (centrality[connection.endId] || 0) + 1; } return centrality; }