mcp-adr-analysis-server
Version:
MCP server for analyzing Architectural Decision Records and project architecture
129 lines • 4.28 kB
TypeScript
/**
* Knowledge Graph Resource - Read-only knowledge graph data
* URI Pattern: knowledge://graph
*
* Provides direct access to the knowledge graph structure with nodes, edges, and metadata.
* This replaces querying KnowledgeGraphManager as a Tool, following ADR-018 atomic tools pattern.
*/
import { URLSearchParams } from 'url';
import { ResourceGenerationResult } from './index.js';
import type { KnowledgeGraphManager } from '../utils/knowledge-graph-manager.js';
export interface GraphNode {
id: string;
type: 'intent' | 'adr' | 'code' | 'tool' | 'decision';
name?: string;
title?: string;
status?: string;
timestamp?: string;
language?: string;
relevanceScore?: number;
}
export interface GraphEdge {
source: string;
target: string;
relationship: 'implements' | 'uses' | 'created' | 'depends-on' | 'supersedes';
strength?: number;
success?: boolean;
}
export interface KnowledgeGraphData {
nodes: GraphNode[];
edges: GraphEdge[];
metadata: {
lastUpdated: string;
nodeCount: number;
edgeCount: number;
intentCount: number;
adrCount: number;
toolCount: number;
version: string;
};
analytics: {
totalIntents: number;
completedIntents: number;
activeIntents: number;
averageGoalCompletion: number;
mostUsedTools: Array<{
toolName: string;
usageCount: number;
}>;
};
}
/**
* Generate knowledge graph resource providing read-only access to graph structure.
*
* Returns comprehensive graph data including nodes (intents, ADRs, tools, code files)
* and edges (relationships between nodes). This is a read-only view - use the
* update_knowledge tool to modify the graph.
*
* **URI Pattern:** `knowledge://graph`
*
* **Query Parameters:** (none)
*
* @param params - URL path parameters (none for this resource)
* @param searchParams - URL query parameters (none used)
* @param kgManager - KnowledgeGraphManager instance (injected by MCP server)
*
* @returns Promise resolving to resource generation result containing:
* - data: Knowledge graph with nodes, edges, and metadata
* - contentType: "application/json"
* - lastModified: ISO timestamp of generation
* - cacheKey: Unique identifier "knowledge-graph"
* - ttl: Cache duration (60 seconds)
* - etag: Entity tag for cache validation
*
* @throws {McpAdrError} When:
* - RESOURCE_GENERATION_ERROR: KnowledgeGraphManager not provided or graph loading fails
*
* @example
* ```typescript
* // Get knowledge graph
* const graph = await generateKnowledgeGraphResource(
* {},
* new URLSearchParams(),
* kgManager
* );
*
* console.log(`Nodes: ${graph.data.nodes.length}`);
* console.log(`Edges: ${graph.data.edges.length}`);
* console.log(`Active Intents: ${graph.data.analytics.activeIntents}`);
*
* // Expected output structure:
* {
* data: {
* nodes: [
* { id: "adr-001", type: "adr", title: "Use React", status: "accepted" },
* { id: "intent-123", type: "intent", name: "Add auth", status: "executing" },
* { id: "tool-analyze", type: "tool", name: "analyze_project_ecosystem" }
* ],
* edges: [
* { source: "intent-123", target: "adr-001", relationship: "created" },
* { source: "intent-123", target: "tool-analyze", relationship: "uses" }
* ],
* metadata: {
* lastUpdated: "2025-12-16T13:00:00.000Z",
* nodeCount: 42,
* edgeCount: 18,
* intentCount: 15,
* adrCount: 8,
* toolCount: 5,
* version: "1.0.0"
* },
* analytics: {
* totalIntents: 15,
* completedIntents: 10,
* activeIntents: 5,
* averageGoalCompletion: 0.67,
* mostUsedTools: [...]
* }
* },
* contentType: "application/json",
* cacheKey: "knowledge-graph",
* ttl: 60
* }
* ```
*
* @since v2.2.0
* @see {@link KnowledgeGraphManager.loadKnowledgeGraph} for graph data source
*/
export declare function generateKnowledgeGraphResource(_params: Record<string, string>, _searchParams: URLSearchParams, kgManager?: KnowledgeGraphManager): Promise<ResourceGenerationResult>;
//# sourceMappingURL=knowledge-graph-resource.d.ts.map