Heptabase MCP

Implementation Reference

• src/tools/analysis.ts:20-108 (handler)

  Main handler function that analyzes the knowledge graph or specific whiteboard, computing metrics like node/edge counts, centrality, clustering coefficient, and density. Formats results as text and optionally exports to JSON.

  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 input schema defining optional parameters: whiteboardId, metrics array (centrality/clustering/density), 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-712 (registration)

  Registers the analyzeGraph tool both internally (this.tools.analyzeGraph) and with the MCP server (this.server.tool), wrapping the handler with data service initialization.

  this.tools.analyzeGraph = {
    inputSchema: analyzeGraphSchema,
    handler: async (params) => {
      await this.ensureDataServiceInitialized();
      return analyzeGraph(this.dataService, params);
    }
  };
  
  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;
  }

• src/tools/analysis.ts:237-281 (helper)

  Helper function to calculate the average clustering coefficient for the graph.

  async function calculateClustering(dataService: HeptabaseDataService, whiteboardId?: string): Promise<number> {
    const connections = whiteboardId 
      ? (await dataService.getWhiteboard(whiteboardId, { includeConnections: true })).connections || []
      : await dataService.getConnections();
  
    // Simple clustering coefficient calculation
    // In a real implementation, this would be more sophisticated
    if (connections.length === 0) return 0;
  
    // Build adjacency list
    const adjacency: Record<string, Set<string>> = {};
    
    for (const connection of connections) {
      if (!adjacency[connection.beginId]) adjacency[connection.beginId] = new Set();
      if (!adjacency[connection.endId]) adjacency[connection.endId] = new Set();
      
      adjacency[connection.beginId].add(connection.endId);
      adjacency[connection.endId].add(connection.beginId);
    }
  
    // Calculate local clustering coefficient for each node
    let totalClustering = 0;
    let nodeCount = 0;
  
    for (const [node, neighbors] of Object.entries(adjacency)) {
      if (neighbors.size < 2) continue;
  
      let triangles = 0;
      const neighborArray = Array.from(neighbors);
      
      for (let i = 0; i < neighborArray.length; i++) {
        for (let j = i + 1; j < neighborArray.length; j++) {
          if (adjacency[neighborArray[i]]?.has(neighborArray[j])) {
            triangles++;
          }
        }
      }
  
      const possibleTriangles = (neighbors.size * (neighbors.size - 1)) / 2;
      totalClustering += triangles / possibleTriangles;
      nodeCount++;
    }
  
    return nodeCount > 0 ? totalClustering / nodeCount : 0;
  }