@weavelogic/knowledge-graph-agent 0.2.0 → 0.3.0

package/dist/mcp-server/handlers/index.js

@@ -0,0 +1,235 @@
+import { McpError, ErrorCode } from "../../node_modules/@modelcontextprotocol/sdk/dist/esm/types.js";
+import { createLogger } from "../../utils/logger.js";
+import { getToolHandler } from "../tools/registry.js";
+const logger = createLogger("mcp-handler");
+async function handleToolCall(request) {
+  const startTime = Date.now();
+  const { name: toolName, arguments: params = {} } = request.params;
+  logger.debug("Handling tool call", { toolName, paramKeys: Object.keys(params || {}) });
+  ({
+    requestId: generateRequestId()
+  });
+  try {
+    const handler = getToolHandler(toolName);
+    if (!handler) {
+      logger.warn(`Unknown tool requested: ${toolName}`);
+      throw new McpError(
+        ErrorCode.MethodNotFound,
+        `Unknown tool: ${toolName}`
+      );
+    }
+    validateParams(params, toolName);
+    const result = await handler(params);
+    const executionTime = Date.now() - startTime;
+    logger.debug(`Tool ${toolName} completed in ${executionTime}ms`, {
+      success: result.success,
+      hasData: !!result.data
+    });
+    return formatResponse(result, executionTime);
+  } catch (error) {
+    const executionTime = Date.now() - startTime;
+    logger.error(
+      `Tool ${toolName} failed after ${executionTime}ms`,
+      error instanceof Error ? error : void 0
+    );
+    if (error instanceof McpError) {
+      throw error;
+    }
+    throw new McpError(
+      ErrorCode.InternalError,
+      `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+const VALIDATION_LIMITS = {
+  MAX_OBJECT_DEPTH: 10,
+  MAX_ARRAY_LENGTH: 1e3,
+  MAX_STRING_LENGTH: 1e5
+};
+function validateParams(params, toolName) {
+  if (params === null || params === void 0) {
+    return;
+  }
+  if (typeof params !== "object" || Array.isArray(params)) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      `Invalid parameters for tool ${toolName}: expected object, got ${Array.isArray(params) ? "array" : typeof params}`
+    );
+  }
+  validateValueRecursive(params, toolName, "", 0);
+}
+function validateValueRecursive(value, toolName, path, depth) {
+  if (depth > VALIDATION_LIMITS.MAX_OBJECT_DEPTH) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      `Parameter nesting too deep at ${path || "root"} for tool ${toolName}: maximum depth is ${VALIDATION_LIMITS.MAX_OBJECT_DEPTH} levels`
+    );
+  }
+  if (value === null || value === void 0) {
+    return;
+  }
+  if (typeof value === "string") {
+    validateString(value, toolName, path);
+  } else if (Array.isArray(value)) {
+    validateArray(value, toolName, path, depth);
+  } else if (typeof value === "object") {
+    validateObject(value, toolName, path, depth);
+  }
+}
+function validateString(value, toolName, path) {
+  const paramName = path || "value";
+  if (value.length > VALIDATION_LIMITS.MAX_STRING_LENGTH) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      `Parameter ${paramName} exceeds maximum length (${VALIDATION_LIMITS.MAX_STRING_LENGTH} characters) for tool ${toolName}`
+    );
+  }
+  if (isPathLike(path) && containsPathTraversal(value)) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      `Parameter ${paramName} contains invalid path traversal sequence for tool ${toolName}`
+    );
+  }
+  if (value.includes("\0")) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      `Parameter ${paramName} contains invalid null byte for tool ${toolName}`
+    );
+  }
+}
+function validateArray(value, toolName, path, depth) {
+  const paramName = path || "array";
+  if (value.length > VALIDATION_LIMITS.MAX_ARRAY_LENGTH) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      `Parameter ${paramName} exceeds maximum array length (${VALIDATION_LIMITS.MAX_ARRAY_LENGTH} items) for tool ${toolName}`
+    );
+  }
+  for (let i = 0; i < value.length; i++) {
+    validateValueRecursive(value[i], toolName, `${path}[${i}]`, depth + 1);
+  }
+}
+function validateObject(value, toolName, path, depth) {
+  for (const [key, propValue] of Object.entries(value)) {
+    const propPath = path ? `${path}.${key}` : key;
+    validateValueRecursive(propValue, toolName, propPath, depth + 1);
+  }
+}
+function isPathLike(paramPath) {
+  const pathIndicators = [
+    "path",
+    "file",
+    "dir",
+    "directory",
+    "folder",
+    "location",
+    "source",
+    "dest",
+    "destination",
+    "target",
+    "uri",
+    "url"
+  ];
+  const lowerPath = paramPath.toLowerCase();
+  return pathIndicators.some(
+    (indicator) => lowerPath.includes(indicator) || lowerPath.endsWith(indicator)
+  );
+}
+function containsPathTraversal(value) {
+  if (value.includes("..")) {
+    return true;
+  }
+  try {
+    const decoded = decodeURIComponent(value.toLowerCase());
+    if (decoded.includes("..")) {
+      return true;
+    }
+  } catch {
+  }
+  return false;
+}
+function formatResponse(result, executionTime) {
+  const enrichedResult = {
+    ...result,
+    metadata: {
+      ...result.metadata,
+      executionTime
+    }
+  };
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(enrichedResult, null, 2)
+      }
+    ]
+  };
+}
+function generateRequestId() {
+  return `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+}
+function handleError(error, context) {
+  logger.error(
+    `Tool execution error: ${context.toolName}`,
+    error instanceof Error ? error : void 0,
+    { requestId: context.requestId }
+  );
+  if (error instanceof McpError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    if (error.message.includes("not found") || error.message.includes("does not exist")) {
+      return new McpError(
+        ErrorCode.InvalidParams,
+        `${context.toolName} failed: ${error.message}`
+      );
+    }
+    if (error.message.includes("permission") || error.message.includes("unauthorized")) {
+      return new McpError(
+        ErrorCode.InvalidRequest,
+        `${context.toolName} failed: ${error.message}`
+      );
+    }
+    if (error.message.includes("timeout")) {
+      return new McpError(
+        ErrorCode.InternalError,
+        `${context.toolName} timed out: ${error.message}`
+      );
+    }
+    return new McpError(
+      ErrorCode.InternalError,
+      `${context.toolName} failed: ${error.message}`
+    );
+  }
+  return new McpError(
+    ErrorCode.InternalError,
+    `${context.toolName} failed: ${String(error)}`
+  );
+}
+function createErrorResult(error, toolName) {
+  return {
+    success: false,
+    error: error instanceof Error ? error.message : String(error),
+    metadata: {
+      toolName,
+      timestamp: Date.now()
+    }
+  };
+}
+function createSuccessResult(data, metadata) {
+  return {
+    success: true,
+    data,
+    metadata: {
+      ...metadata,
+      timestamp: Date.now()
+    }
+  };
+}
+export {
+  createErrorResult,
+  createSuccessResult,
+  handleError,
+  handleToolCall
+};
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/handlers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/mcp-server/handlers/index.ts"],"sourcesContent":["/**\n * MCP Tool Request Handler\n *\n * Handles incoming tool call requests from MCP clients.\n * Validates parameters, executes handlers, and formats responses.\n *\n * @module mcp-server/handlers\n */\n\nimport {\n  ErrorCode,\n  McpError,\n  type CallToolResult,\n} from '@modelcontextprotocol/sdk/types.js';\nimport type { ToolContext, ToolResult } from '../types/index.js';\nimport { createLogger } from '../../utils/index.js';\nimport { getToolHandler } from '../tools/registry.js';\n\nconst logger = createLogger('mcp-handler');\n\n/**\n * MCP CallToolRequest params structure\n */\ninterface CallToolParams {\n  name: string;\n  arguments?: Record<string, unknown>;\n}\n\n/**\n * MCP request structure\n */\ninterface MCPRequest {\n  params: CallToolParams;\n}\n\n/**\n * Handle tool call requests from MCP clients\n *\n * @param request - MCP call tool request\n * @returns MCP response with tool result\n * @throws McpError if tool not found or execution fails\n */\nexport async function handleToolCall(request: MCPRequest): Promise<CallToolResult> {\n  const startTime = Date.now();\n  const { name: toolName, arguments: params = {} } = request.params;\n\n  // Log only parameter keys, not values, to avoid exposing sensitive data\n  logger.debug('Handling tool call', { toolName, paramKeys: Object.keys(params || {}) });\n\n  const context: ToolContext = {\n    toolName,\n    params,\n    timestamp: startTime,\n    requestId: generateRequestId(),\n  };\n\n  try {\n    // Get handler from registry\n    const handler = getToolHandler(toolName);\n\n    if (!handler) {\n      logger.warn(`Unknown tool requested: ${toolName}`);\n      throw new McpError(\n        ErrorCode.MethodNotFound,\n        `Unknown tool: ${toolName}`\n      );\n    }\n\n    // Validate parameters\n    validateParams(params, toolName);\n\n    // Execute handler\n    const result = await handler(params);\n\n    const executionTime = Date.now() - startTime;\n    logger.debug(`Tool ${toolName} completed in ${executionTime}ms`, {\n      success: result.success,\n      hasData: !!result.data,\n    });\n\n    // Format response\n    return formatResponse(result, executionTime);\n  } catch (error) {\n    const executionTime = Date.now() - startTime;\n    logger.error(\n      `Tool ${toolName} failed after ${executionTime}ms`,\n      error instanceof Error ? error : undefined\n    );\n\n    // Re-throw MCP errors as-is\n    if (error instanceof McpError) {\n      throw error;\n    }\n\n    // Wrap other errors\n    throw new McpError(\n      ErrorCode.InternalError,\n      `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`\n    );\n  }\n}\n\n/**\n * Security constants for input validation\n *\n * SECURITY: These limits prevent various attack vectors:\n * - MAX_OBJECT_DEPTH: Prevents stack overflow from deeply nested objects\n * - MAX_ARRAY_LENGTH: Prevents memory exhaustion from large arrays\n * - MAX_STRING_LENGTH: Prevents DoS from excessively long strings\n */\nconst VALIDATION_LIMITS = {\n  MAX_OBJECT_DEPTH: 10,\n  MAX_ARRAY_LENGTH: 1000,\n  MAX_STRING_LENGTH: 100000,\n} as const;\n\n/**\n * Validate tool parameters with comprehensive security checks\n *\n * SECURITY: This function performs multi-layered input validation to protect against:\n * 1. Stack overflow attacks via deeply nested objects (max 10 levels)\n * 2. Memory exhaustion via large arrays (max 1000 items)\n * 3. DoS via excessively long strings (max 100000 chars)\n * 4. Path traversal attacks via '..' sequences and null bytes in paths\n *\n * @param params - Parameters to validate\n * @param toolName - Tool name for error messages\n * @throws McpError if parameters are invalid or potentially malicious\n */\nfunction validateParams(params: unknown, toolName: string): void {\n  // Null/undefined is valid (empty params)\n  if (params === null || params === undefined) {\n    return;\n  }\n\n  // Must be an object\n  if (typeof params !== 'object' || Array.isArray(params)) {\n    throw new McpError(\n      ErrorCode.InvalidParams,\n      `Invalid parameters for tool ${toolName}: expected object, got ${Array.isArray(params) ? 'array' : typeof params}`\n    );\n  }\n\n  // SECURITY: Perform recursive validation with depth tracking\n  validateValueRecursive(params, toolName, '', 0);\n}\n\n/**\n * Recursively validate a value with security checks\n *\n * SECURITY: Validates nested structures to prevent:\n * - Deep nesting attacks (stack overflow)\n * - Large array attacks (memory exhaustion)\n * - Path traversal in string values\n * - Null byte injection\n *\n * @param value - Value to validate\n * @param toolName - Tool name for error context\n * @param path - Current property path for error messages\n * @param depth - Current nesting depth\n * @throws McpError if validation fails\n */\nfunction validateValueRecursive(\n  value: unknown,\n  toolName: string,\n  path: string,\n  depth: number\n): void {\n  // SECURITY: Prevent stack overflow from deeply nested objects\n  // Attackers may send deeply nested JSON to exhaust call stack\n  if (depth > VALIDATION_LIMITS.MAX_OBJECT_DEPTH) {\n    throw new McpError(\n      ErrorCode.InvalidParams,\n      `Parameter nesting too deep at ${path || 'root'} for tool ${toolName}: ` +\n        `maximum depth is ${VALIDATION_LIMITS.MAX_OBJECT_DEPTH} levels`\n    );\n  }\n\n  // Handle null/undefined (valid leaf values)\n  if (value === null || value === undefined) {\n    return;\n  }\n\n  // Validate based on type\n  if (typeof value === 'string') {\n    validateString(value, toolName, path);\n  } else if (Array.isArray(value)) {\n    validateArray(value, toolName, path, depth);\n  } else if (typeof value === 'object') {\n    validateObject(value as Record<string, unknown>, toolName, path, depth);\n  }\n  // Primitives (number, boolean) are always valid\n}\n\n/**\n * Validate string values for security issues\n *\n * SECURITY: Checks for:\n * - Excessive length (DoS prevention)\n * - Path traversal sequences (..)\n * - Null byte injection (\\x00)\n *\n * @param value - String value to validate\n * @param toolName - Tool name for error context\n * @param path - Property path for error messages\n * @throws McpError if string contains malicious content\n */\nfunction validateString(value: string, toolName: string, path: string): void {\n  const paramName = path || 'value';\n\n  // SECURITY: Check for excessively long strings (potential DoS)\n  // Large strings can exhaust memory or cause slow processing\n  if (value.length > VALIDATION_LIMITS.MAX_STRING_LENGTH) {\n    throw new McpError(\n      ErrorCode.InvalidParams,\n      `Parameter ${paramName} exceeds maximum length (${VALIDATION_LIMITS.MAX_STRING_LENGTH} characters) for tool ${toolName}`\n    );\n  }\n\n  // SECURITY: Check for path traversal attacks\n  // Detects attempts to escape directory boundaries using '..' sequences\n  // This prevents unauthorized file system access\n  if (isPathLike(path) && containsPathTraversal(value)) {\n    throw new McpError(\n      ErrorCode.InvalidParams,\n      `Parameter ${paramName} contains invalid path traversal sequence for tool ${toolName}`\n    );\n  }\n\n  // SECURITY: Check for null byte injection\n  // Null bytes can truncate strings in C-based systems, potentially bypassing validation\n  // They have no legitimate use in parameter values\n  if (value.includes('\\x00')) {\n    throw new McpError(\n      ErrorCode.InvalidParams,\n      `Parameter ${paramName} contains invalid null byte for tool ${toolName}`\n    );\n  }\n}\n\n/**\n * Validate array values for security issues\n *\n * SECURITY: Prevents memory exhaustion from excessively large arrays\n *\n * @param value - Array to validate\n * @param toolName - Tool name for error context\n * @param path - Property path for error messages\n * @param depth - Current nesting depth\n * @throws McpError if array is too large or contains invalid items\n */\nfunction validateArray(\n  value: unknown[],\n  toolName: string,\n  path: string,\n  depth: number\n): void {\n  const paramName = path || 'array';\n\n  // SECURITY: Check for excessively large arrays (memory exhaustion prevention)\n  // Large arrays can consume excessive memory during processing\n  if (value.length > VALIDATION_LIMITS.MAX_ARRAY_LENGTH) {\n    throw new McpError(\n      ErrorCode.InvalidParams,\n      `Parameter ${paramName} exceeds maximum array length (${VALIDATION_LIMITS.MAX_ARRAY_LENGTH} items) for tool ${toolName}`\n    );\n  }\n\n  // Recursively validate each array element\n  for (let i = 0; i < value.length; i++) {\n    validateValueRecursive(value[i], toolName, `${path}[${i}]`, depth + 1);\n  }\n}\n\n/**\n * Validate object values recursively\n *\n * @param value - Object to validate\n * @param toolName - Tool name for error context\n * @param path - Property path for error messages\n * @param depth - Current nesting depth\n * @throws McpError if object contains invalid values\n */\nfunction validateObject(\n  value: Record<string, unknown>,\n  toolName: string,\n  path: string,\n  depth: number\n): void {\n  for (const [key, propValue] of Object.entries(value)) {\n    const propPath = path ? `${path}.${key}` : key;\n    validateValueRecursive(propValue, toolName, propPath, depth + 1);\n  }\n}\n\n/**\n * Check if a parameter path suggests it contains a file/directory path\n *\n * SECURITY: Identifies path-like parameters that should be checked for traversal attacks\n *\n * @param paramPath - The parameter's property path (e.g., \"config.filePath\")\n * @returns True if the parameter name suggests it's a path\n */\nfunction isPathLike(paramPath: string): boolean {\n  const pathIndicators = [\n    'path',\n    'file',\n    'dir',\n    'directory',\n    'folder',\n    'location',\n    'source',\n    'dest',\n    'destination',\n    'target',\n    'uri',\n    'url',\n  ];\n\n  const lowerPath = paramPath.toLowerCase();\n  return pathIndicators.some(\n    (indicator) => lowerPath.includes(indicator) || lowerPath.endsWith(indicator)\n  );\n}\n\n/**\n * Check if a string contains path traversal sequences\n *\n * SECURITY: Detects various forms of path traversal attacks:\n * - Direct '..' sequences\n * - URL-encoded '..' (%2e%2e)\n * - Mixed encoding\n *\n * @param value - String to check for path traversal\n * @returns True if path traversal detected\n */\nfunction containsPathTraversal(value: string): boolean {\n  // SECURITY: Check for literal '..' path traversal\n  if (value.includes('..')) {\n    return true;\n  }\n\n  // SECURITY: Check for URL-encoded path traversal\n  // %2e is URL-encoded '.', so %2e%2e or %2e. or .%2e are all '..'\n  try {\n    const decoded = decodeURIComponent(value.toLowerCase());\n    if (decoded.includes('..')) {\n      return true;\n    }\n  } catch {\n    // If decoding fails, the string may contain malformed encoding\n    // which is suspicious but not necessarily path traversal\n  }\n\n  return false;\n}\n\n/**\n * Format tool result as MCP response\n *\n * @param result - Tool execution result\n * @param executionTime - Execution time in milliseconds\n * @returns Formatted MCP response\n */\nfunction formatResponse(result: ToolResult, executionTime: number): CallToolResult {\n  // Add execution time to metadata\n  const enrichedResult: ToolResult = {\n    ...result,\n    metadata: {\n      ...result.metadata,\n      executionTime,\n    },\n  };\n\n  return {\n    content: [\n      {\n        type: 'text',\n        text: JSON.stringify(enrichedResult, null, 2),\n      },\n    ],\n  };\n}\n\n/**\n * Generate unique request ID for tracing\n */\nfunction generateRequestId(): string {\n  return `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;\n}\n\n/**\n * Handle errors and convert to MCP errors\n *\n * @param error - Original error\n * @param context - Tool execution context\n * @returns MCP error\n */\nexport function handleError(error: unknown, context: ToolContext): McpError {\n  logger.error(\n    `Tool execution error: ${context.toolName}`,\n    error instanceof Error ? error : undefined,\n    { requestId: context.requestId }\n  );\n\n  // Return as-is if already MCP error\n  if (error instanceof McpError) {\n    return error;\n  }\n\n  // Handle specific error types\n  if (error instanceof Error) {\n    // Check for known error patterns\n    if (error.message.includes('not found') || error.message.includes('does not exist')) {\n      return new McpError(\n        ErrorCode.InvalidParams,\n        `${context.toolName} failed: ${error.message}`\n      );\n    }\n\n    if (error.message.includes('permission') || error.message.includes('unauthorized')) {\n      return new McpError(\n        ErrorCode.InvalidRequest,\n        `${context.toolName} failed: ${error.message}`\n      );\n    }\n\n    if (error.message.includes('timeout')) {\n      return new McpError(\n        ErrorCode.InternalError,\n        `${context.toolName} timed out: ${error.message}`\n      );\n    }\n\n    // Generic error\n    return new McpError(\n      ErrorCode.InternalError,\n      `${context.toolName} failed: ${error.message}`\n    );\n  }\n\n  // Unknown error type\n  return new McpError(\n    ErrorCode.InternalError,\n    `${context.toolName} failed: ${String(error)}`\n  );\n}\n\n/**\n * Create error response for tool failures\n *\n * @param error - Error message or object\n * @param toolName - Tool that failed\n * @returns Tool result indicating failure\n */\nexport function createErrorResult(error: unknown, toolName: string): ToolResult {\n  return {\n    success: false,\n    error: error instanceof Error ? error.message : String(error),\n    metadata: {\n      toolName,\n      timestamp: Date.now(),\n    },\n  };\n}\n\n/**\n * Create success response for tool results\n *\n * @param data - Result data\n * @param metadata - Additional metadata\n * @returns Tool result indicating success\n */\nexport function createSuccessResult(\n  data: unknown,\n  metadata?: Record<string, unknown>\n): ToolResult {\n  return {\n    success: true,\n    data,\n    metadata: {\n      ...metadata,\n      timestamp: Date.now(),\n    },\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/mcp-server/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Knowledge Graph MCP Server
+ *
+ * Model Context Protocol server for knowledge graph operations.
+ * Exposes knowledge graph functionality to Claude Desktop and other MCP clients.
+ *
+ * @module mcp-server
+ *
+ * @example
+ * ```typescript
+ * import { createMCPServer, KnowledgeGraphMCPServer } from './mcp-server';
+ *
+ * // Create and run server
+ * const server = await createMCPServer({
+ *   name: 'my-kg-server',
+ *   version: '1.0.0',
+ * });
+ *
+ * // Check health
+ * const health = server.getHealth();
+ * console.log('Server status:', health.status);
+ * ```
+ */
+export { KnowledgeGraphMCPServer, createMCPServer, runServer, } from './server.js';
+export type { MCPServerConfig, ServerHealth, ToolCategory, ToolHandler, ToolHandlerEntry, ToolResult, ToolContext, ToolInputSchema, ToolDefinition, GraphQueryParams, GraphNodeResult, AgentInvokeParams, AgentResult, WorkflowParams, WorkflowResult, MemoryParams, MemoryResult, } from './types/index.js';
+export { initializeTools, registerTool, getToolHandler, getToolDefinition, getToolDefinitions, getToolCategories, hasToolRegistered, getToolCount, clearRegistry, getDatabase, getCache, getProjectRoot, } from './tools/index.js';
+export { handleToolCall, handleError, createErrorResult, createSuccessResult, } from './handlers/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp-server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,SAAS,GACV,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,cAAc,EACd,YAAY,EACZ,YAAY,GACb,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,eAAe,EACf,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,QAAQ,EACR,cAAc,GACf,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC"}

package/dist/mcp-server/server.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Knowledge Graph MCP Server
+ *
+ * Main MCP server implementation for exposing knowledge graph functionality
+ * to Claude Desktop and other MCP clients.
+ *
+ * @module mcp-server/server
+ */
+import type { MCPServerConfig, ServerHealth } from './types/index.js';
+import type { KnowledgeGraphDatabase } from '../core/database.js';
+import type { ShadowCache } from '../core/cache.js';
+/**
+ * Knowledge Graph MCP Server
+ *
+ * Provides MCP protocol implementation for knowledge graph operations.
+ * Supports tool listing and execution over stdio transport.
+ *
+ * @example
+ * ```typescript
+ * const server = new KnowledgeGraphMCPServer();
+ * await server.run();
+ * ```
+ */
+export declare class KnowledgeGraphMCPServer {
+    private server;
+    private isRunning;
+    private startTime;
+    private requestCount;
+    private config;
+    private requestCounts;
+    private readonly MAX_REQUESTS_PER_MINUTE;
+    private database?;
+    private cache?;
+    private projectRoot?;
+    /**
+     * Create new MCP server instance
+     *
+     * @param config - Server configuration
+     * @param database - Knowledge graph database instance
+     * @param cache - Shadow cache instance
+     * @param projectRoot - Project root path
+     */
+    constructor(config?: Partial<MCPServerConfig>, database?: KnowledgeGraphDatabase, cache?: ShadowCache, projectRoot?: string);
+    /**
+     * Check rate limit and throw if exceeded
+     *
+     * Implements a fixed-window rate limit of MAX_REQUESTS_PER_MINUTE per minute.
+     * Cleans up old entries to prevent memory leaks.
+     *
+     * @throws McpError if rate limit is exceeded
+     */
+    private checkRateLimit;
+    /**
+     * Setup MCP request handlers
+     */
+    private setupHandlers;
+    /**
+     * Start the MCP server
+     *
+     * @throws Error if server is already running
+     */
+    run(): Promise<void>;
+    /**
+     * Shutdown the MCP server gracefully
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get server health status
+     *
+     * @returns Health status object
+     */
+    getHealth(): ServerHealth;
+    /**
+     * Check if server is currently running
+     *
+     * @returns true if server is running
+     */
+    isServerRunning(): boolean;
+    /**
+     * Get server configuration
+     *
+     * @returns Server configuration
+     */
+    getConfig(): MCPServerConfig;
+    /**
+     * Get request count
+     *
+     * @returns Number of requests handled
+     */
+    getRequestCount(): number;
+    /**
+     * Get server uptime in milliseconds
+     *
+     * @returns Uptime in milliseconds, 0 if not running
+     */
+    getUptime(): number;
+}
+/**
+ * Create and start an MCP server
+ *
+ * Convenience function for creating and running an MCP server in one call.
+ *
+ * @param config - Server configuration
+ * @param database - Knowledge graph database instance
+ * @param cache - Shadow cache instance
+ * @param projectRoot - Project root path
+ * @returns Running MCP server instance
+ *
+ * @example
+ * ```typescript
+ * const server = await createMCPServer(
+ *   { name: 'my-kg-server' },
+ *   database,
+ *   cache,
+ *   '/my/project'
+ * );
+ * ```
+ */
+export declare function createMCPServer(config?: Partial<MCPServerConfig>, database?: KnowledgeGraphDatabase, cache?: ShadowCache, projectRoot?: string): Promise<KnowledgeGraphMCPServer>;
+/**
+ * Run MCP server as standalone process
+ *
+ * Entry point for running the MCP server from command line.
+ *
+ * @param options - Server options
+ */
+export declare function runServer(options?: {
+    config?: Partial<MCPServerConfig>;
+    database?: KnowledgeGraphDatabase;
+    cache?: ShadowCache;
+    projectRoot?: string;
+}): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/mcp-server/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp-server/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAyBpD;;;;;;;;;;;GAWG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,MAAM,CAAkB;IAGhC,OAAO,CAAC,aAAa,CAAkC;IACvD,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAO;IAE/C,OAAO,CAAC,QAAQ,CAAC,CAAyB;IAC1C,OAAO,CAAC,KAAK,CAAC,CAAc;IAC5B,OAAO,CAAC,WAAW,CAAC,CAAS;IAE7B;;;;;;;OAOG;gBAED,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,QAAQ,CAAC,EAAE,sBAAsB,EACjC,KAAK,CAAC,EAAE,WAAW,EACnB,WAAW,CAAC,EAAE,MAAM;IAoCtB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAoBtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAyDrB;;;;OAIG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B1B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B/B;;;;OAIG;IACH,SAAS,IAAI,YAAY;IAczB;;;;OAIG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;OAIG;IACH,SAAS,IAAI,eAAe;IAI5B;;;;OAIG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;OAIG;IACH,SAAS,IAAI,MAAM;CAGpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CACnC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,QAAQ,CAAC,EAAE,sBAAsB,EACjC,KAAK,CAAC,EAAE,WAAW,EACnB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,uBAAuB,CAAC,CAIlC;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,OAAO,CAAC,EAAE;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsChB"}