@xache/mcp-server 0.4.0 → 0.5.0

package/README.md

@@ -182,6 +182,78 @@ Extract insights from this API integration session and contribute any valuable p
 Domain: "api-integration"
 ```
 
+### Knowledge Graph
+
+#### `xache_graph_extract`
+
+Extract entities and relationships from text into the knowledge graph.
+
+**Parameters:**
+- `trace` (required): The text to extract entities from
+- `domain` (optional): Domain hint (e.g., "engineering", "customer-support")
+- `mode` (optional): LLM mode - "byok" or "xache-managed"
+- `provider` (optional): LLM provider
+- `model` (optional): Specific model to use
+
+#### `xache_graph_load`
+
+Load the full knowledge graph.
+
+**Parameters:**
+- `entityTypes` (optional): Filter to specific entity types
+- `validAt` (optional): Load graph at a specific time (ISO8601)
+
+#### `xache_graph_query`
+
+Query the knowledge graph around a specific entity.
+
+**Parameters:**
+- `startEntity` (required): Entity name to start from
+- `depth` (optional): Number of hops (default: 2)
+
+#### `xache_graph_ask`
+
+Ask a natural language question about the knowledge graph.
+
+**Parameters:**
+- `question` (required): The question to ask
+- `mode` (optional): LLM mode
+- `provider` (optional): LLM provider
+
+#### `xache_graph_add_entity`
+
+Add an entity to the knowledge graph.
+
+**Parameters:**
+- `name` (required): Entity name
+- `type` (required): Entity type (person, organization, tool, concept, etc.)
+- `summary` (optional): Brief description
+
+#### `xache_graph_add_relationship`
+
+Create a relationship between two entities.
+
+**Parameters:**
+- `fromEntity` (required): Source entity name
+- `toEntity` (required): Target entity name
+- `type` (required): Relationship type (works_at, knows, uses, manages, etc.)
+- `description` (optional): Relationship description
+
+#### `xache_graph_merge_entities`
+
+Merge two entities into one. The source is superseded and the target is updated.
+
+**Parameters:**
+- `sourceName` (required): Entity to merge FROM
+- `targetName` (required): Entity to merge INTO
+
+#### `xache_graph_entity_history`
+
+Get the full version history of an entity.
+
+**Parameters:**
+- `name` (required): Entity name to look up
+
 ### Reputation
 
 #### `xache_check_reputation`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xache/mcp-server",
-  "version": "0.4.0",
-  "description": "MCP server for Xache Protocol - collective intelligence, verifiable memory, extraction, and reputation for AI agents",
+  "version": "0.5.0",
+  "description": "MCP server for Xache Protocol - collective intelligence, verifiable memory, and reputation for AI agents",
   "main": "dist/index.js",
   "bin": {
     "xache-mcp": "./dist/index.js"
@@ -19,7 +19,6 @@
     "agents",
     "collective-intelligence",
     "memory",
-    "extraction",
     "blockchain",
     "receipts",
     "reputation"
@@ -28,12 +27,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/xacheai/xache-protocol"
+    "url": "https://github.com/oliveskin/xache"
   },
   "homepage": "https://xache.xyz",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "@xache/sdk": "^5.4.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@xache/sdk": "^5.5.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -47,7 +47,13 @@ import {
   ListToolsRequestSchema,
   Tool,
 } from '@modelcontextprotocol/sdk/types.js';
-import { XacheClient, type DID, type LLMProvider, type LLMApiFormat } from '@xache/sdk';
+import {
+  XacheClient,
+  type DID,
+  type LLMProvider,
+  type LLMApiFormat,
+  type SubjectContext,
+} from '@xache/sdk';
 import crypto from 'crypto';
 
 // =============================================================================
@@ -84,77 +90,14 @@ function getDID(): DID {
 }
 
 function validateConfig(): void {
-  // Required: wallet address
   if (!config.walletAddress) {
     console.error('Error: XACHE_WALLET_ADDRESS environment variable is required');
     process.exit(1);
   }
-
-  // Required: private key
   if (!config.privateKey) {
     console.error('Error: XACHE_PRIVATE_KEY environment variable is required');
     process.exit(1);
   }
-
-  // Validate chain
-  if (!['base', 'solana'].includes(config.chain)) {
-    console.error('Error: XACHE_CHAIN must be "base" or "solana"');
-    process.exit(1);
-  }
-
-  // Validate wallet address format based on chain
-  if (config.chain === 'solana') {
-    // Solana: base58 (32-44 chars)
-    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(config.walletAddress)) {
-      console.error('Error: Invalid Solana wallet address format');
-      process.exit(1);
-    }
-  } else {
-    // EVM: 0x + 40 hex chars
-    if (!/^0x[a-fA-F0-9]{40}$/.test(config.walletAddress)) {
-      console.error('Error: Invalid EVM wallet address format (expected 0x + 40 hex chars)');
-      process.exit(1);
-    }
-  }
-
-  // Validate private key format (hex string)
-  const cleanKey = config.privateKey.startsWith('0x')
-    ? config.privateKey.slice(2)
-    : config.privateKey;
-  if (!/^[a-fA-F0-9]{64}$/.test(cleanKey) && !/^[a-fA-F0-9]{128}$/.test(cleanKey)) {
-    console.error('Error: XACHE_PRIVATE_KEY must be a 64 or 128 character hex string');
-    process.exit(1);
-  }
-
-  // Validate API URL format
-  try {
-    new URL(config.apiUrl);
-  } catch {
-    console.error('Error: XACHE_API_URL is not a valid URL');
-    process.exit(1);
-  }
-
-  // Validate LLM provider if specified
-  if (config.llmProvider && !SUPPORTED_PROVIDERS.includes(config.llmProvider)) {
-    console.error(`Error: XACHE_LLM_PROVIDER must be one of: ${SUPPORTED_PROVIDERS.join(', ')}`);
-    process.exit(1);
-  }
-
-  // Validate LLM endpoint URL if specified
-  if (config.llmEndpoint) {
-    try {
-      new URL(config.llmEndpoint);
-    } catch {
-      console.error('Error: XACHE_LLM_ENDPOINT is not a valid URL');
-      process.exit(1);
-    }
-  }
-
-  // Validate LLM format
-  if (!['openai', 'anthropic', 'cohere'].includes(config.llmFormat)) {
-    console.error('Error: XACHE_LLM_FORMAT must be "openai", "anthropic", or "cohere"');
-    process.exit(1);
-  }
 }
 
 // =============================================================================
@@ -165,6 +108,21 @@ function hashPattern(pattern: string): string {
   return crypto.createHash('sha256').update(pattern).digest('hex');
 }
 
+function getDefaultSubjectContext(): SubjectContext {
+  return { scope: 'GLOBAL' };
+}
+
+function buildSubjectContext(args: Record<string, unknown>): SubjectContext {
+  const subject = args.subject as Record<string, unknown> | undefined;
+  if (!subject) return getDefaultSubjectContext();
+  return {
+    scope: (subject.scope as SubjectContext['scope']) || 'GLOBAL',
+    subjectId: subject.subjectId as string | undefined,
+    segmentId: subject.segmentId as string | undefined,
+    tenantId: subject.tenantId as string | undefined,
+  };
+}
+
 // =============================================================================
 // Tool Definitions
 // =============================================================================
@@ -265,6 +223,16 @@ const TOOLS: Tool[] = [
           enum: ['hot', 'warm', 'cold'],
           description: 'Storage tier (default: warm)',
         },
+        subject: {
+          type: 'object',
+          description: 'Optional subject context for memory scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'], description: 'Memory scope (default: GLOBAL)' },
+            subjectId: { type: 'string', description: 'HMAC-derived subject ID (64 hex chars)' },
+            segmentId: { type: 'string', description: 'Segment identifier' },
+            tenantId: { type: 'string', description: 'Tenant identifier' },
+          },
+        },
       },
       required: ['data'],
     },
@@ -279,6 +247,16 @@ const TOOLS: Tool[] = [
           type: 'string',
           description: 'The storage key from when the memory was stored',
         },
+        subject: {
+          type: 'object',
+          description: 'Optional subject context for memory scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'], description: 'Memory scope (default: GLOBAL)' },
+            subjectId: { type: 'string', description: 'HMAC-derived subject ID (64 hex chars)' },
+            segmentId: { type: 'string', description: 'Segment identifier' },
+            tenantId: { type: 'string', description: 'Tenant identifier' },
+          },
+        },
       },
       required: ['storageKey'],
     },
@@ -297,6 +275,16 @@ const TOOLS: Tool[] = [
           type: 'number',
           description: 'Max results (default 20)',
         },
+        subject: {
+          type: 'object',
+          description: 'Optional subject context for memory scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'], description: 'Memory scope (default: GLOBAL)' },
+            subjectId: { type: 'string', description: 'HMAC-derived subject ID (64 hex chars)' },
+            segmentId: { type: 'string', description: 'Segment identifier' },
+            tenantId: { type: 'string', description: 'Tenant identifier' },
+          },
+        },
       },
       required: [],
     },
@@ -401,6 +389,300 @@ const TOOLS: Tool[] = [
       required: ['trace', 'domain'],
     },
   },
+
+  // =========================================================================
+  // Knowledge Graph Tools
+  // =========================================================================
+  {
+    name: 'xache_graph_extract',
+    description:
+      'Extract entities and relationships from an agent trace into the knowledge graph. Uses LLM to identify people, organizations, tools, concepts, and their relationships. Automatically stores results.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        trace: {
+          type: 'string',
+          description: 'The agent trace/conversation to extract entities and relationships from',
+        },
+        domain: {
+          type: 'string',
+          description: 'Domain hint for better extraction (e.g., "customer-support", "engineering")',
+        },
+        mode: {
+          type: 'string',
+          enum: ['api-key', 'endpoint', 'xache-managed'],
+          description: 'LLM mode (default: auto-detected from env vars)',
+        },
+        provider: {
+          type: 'string',
+          enum: ['anthropic', 'openai', 'google', 'mistral', 'groq', 'together', 'fireworks', 'cohere', 'xai', 'deepseek'],
+          description: 'LLM provider for api-key mode (default: anthropic)',
+        },
+        model: {
+          type: 'string',
+          description: 'Specific model to use (optional)',
+        },
+        confidenceThreshold: {
+          type: 'number',
+          description: 'Minimum confidence for extraction (0.0-1.0, default: 0.7)',
+        },
+        maxEntities: {
+          type: 'number',
+          description: 'Maximum entities to extract (default: provider limit)',
+        },
+        subject: {
+          type: 'object',
+          description: 'Subject context for graph scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+            subjectId: { type: 'string' },
+            segmentId: { type: 'string' },
+            tenantId: { type: 'string' },
+          },
+        },
+      },
+      required: ['trace'],
+    },
+  },
+  {
+    name: 'xache_graph_load',
+    description:
+      'Load the full knowledge graph. Returns all entities and relationships. Optionally filter by entity type or load a historical snapshot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entityTypes: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter to specific entity types (e.g., ["person", "organization"])',
+        },
+        validAt: {
+          type: 'string',
+          description: 'Load graph as it existed at this time (ISO8601 date string)',
+        },
+        subject: {
+          type: 'object',
+          description: 'Subject context for graph scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+            subjectId: { type: 'string' },
+            segmentId: { type: 'string' },
+            tenantId: { type: 'string' },
+          },
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'xache_graph_query',
+    description:
+      'Query a subgraph around a specific entity. Returns the entity and all connected entities/relationships within the specified depth.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        startEntity: {
+          type: 'string',
+          description: 'Name of the starting entity (e.g., "John Smith", "Acme Corp")',
+        },
+        depth: {
+          type: 'number',
+          description: 'Number of hops from start entity (default: 2)',
+        },
+        relationshipTypes: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter to specific relationship types (e.g., ["works_at", "manages"])',
+        },
+        validAt: {
+          type: 'string',
+          description: 'Query as of this point in time (ISO8601)',
+        },
+        subject: {
+          type: 'object',
+          description: 'Subject context for graph scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+            subjectId: { type: 'string' },
+            segmentId: { type: 'string' },
+            tenantId: { type: 'string' },
+          },
+        },
+      },
+      required: ['startEntity'],
+    },
+  },
+  {
+    name: 'xache_graph_ask',
+    description:
+      'Ask a natural language question about the knowledge graph. Uses LLM to analyze the graph and generate an answer with source citations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        question: {
+          type: 'string',
+          description: 'Natural language question (e.g., "Who manages the engineering team?")',
+        },
+        mode: {
+          type: 'string',
+          enum: ['api-key', 'endpoint', 'xache-managed'],
+          description: 'LLM mode (default: auto-detected from env vars)',
+        },
+        provider: {
+          type: 'string',
+          enum: ['anthropic', 'openai', 'google', 'mistral', 'groq', 'together', 'fireworks', 'cohere', 'xai', 'deepseek'],
+          description: 'LLM provider for api-key mode (default: anthropic)',
+        },
+        model: {
+          type: 'string',
+          description: 'Specific model to use (optional)',
+        },
+        subject: {
+          type: 'object',
+          description: 'Subject context for graph scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+            subjectId: { type: 'string' },
+            segmentId: { type: 'string' },
+            tenantId: { type: 'string' },
+          },
+        },
+      },
+      required: ['question'],
+    },
+  },
+  {
+    name: 'xache_graph_add_entity',
+    description:
+      'Manually add an entity to the knowledge graph. Use when you want to explicitly create a person, organization, tool, concept, etc.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Entity display name (e.g., "John Smith", "React")',
+        },
+        type: {
+          type: 'string',
+          description: 'Entity type: "person", "organization", "tool", "concept", "location", "event", "product", "project", or custom',
+        },
+        summary: {
+          type: 'string',
+          description: 'Brief description of the entity',
+        },
+        attributes: {
+          type: 'object',
+          description: 'Arbitrary key-value attributes',
+        },
+        subject: {
+          type: 'object',
+          description: 'Subject context for graph scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+            subjectId: { type: 'string' },
+            segmentId: { type: 'string' },
+            tenantId: { type: 'string' },
+          },
+        },
+      },
+      required: ['name', 'type'],
+    },
+  },
+  {
+    name: 'xache_graph_add_relationship',
+    description:
+      'Create a relationship between two entities in the knowledge graph. Both entities must already exist.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromEntity: {
+          type: 'string',
+          description: 'Source entity name',
+        },
+        toEntity: {
+          type: 'string',
+          description: 'Target entity name',
+        },
+        type: {
+          type: 'string',
+          description: 'Relationship type: "works_at", "knows", "uses", "manages", "reports_to", "part_of", "created", "owns", "located_in", "related_to", or custom',
+        },
+        description: {
+          type: 'string',
+          description: 'Human-readable description of the relationship',
+        },
+        attributes: {
+          type: 'object',
+          description: 'Arbitrary key-value attributes',
+        },
+        subject: {
+          type: 'object',
+          description: 'Subject context for graph scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+            subjectId: { type: 'string' },
+            segmentId: { type: 'string' },
+            tenantId: { type: 'string' },
+          },
+        },
+      },
+      required: ['fromEntity', 'toEntity', 'type'],
+    },
+  },
+  {
+    name: 'xache_graph_merge_entities',
+    description:
+      'Merge two entities into one. The source entity is superseded and the target entity is updated with merged attributes. Relationships are transferred.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sourceName: {
+          type: 'string',
+          description: 'Entity to merge FROM (will be superseded)',
+        },
+        targetName: {
+          type: 'string',
+          description: 'Entity to merge INTO (will be updated)',
+        },
+        subject: {
+          type: 'object',
+          description: 'Subject context for graph scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+            subjectId: { type: 'string' },
+            segmentId: { type: 'string' },
+            tenantId: { type: 'string' },
+          },
+        },
+      },
+      required: ['sourceName', 'targetName'],
+    },
+  },
+  {
+    name: 'xache_graph_entity_history',
+    description:
+      'Get the full version history of an entity. Shows how the entity has changed over time, including all temporal versions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Entity name to look up history for',
+        },
+        subject: {
+          type: 'object',
+          description: 'Subject context for graph scoping',
+          properties: {
+            scope: { type: 'string', enum: ['SUBJECT', 'SEGMENT', 'GLOBAL'] },
+            subjectId: { type: 'string' },
+            segmentId: { type: 'string' },
+            tenantId: { type: 'string' },
+          },
+        },
+      },
+      required: ['name'],
+    },
+  },
 ];
 
 // =============================================================================
@@ -803,6 +1085,347 @@ async function handleExtractAndContribute(
   return output;
 }
 
+// =============================================================================
+// Graph Tool Handlers
+// =============================================================================
+
+/**
+ * Build LLM config from args + env vars (shared by graph extract/ask and extraction tools)
+ */
+function buildLLMConfig(args: {
+  mode?: 'api-key' | 'endpoint' | 'xache-managed';
+  provider?: LLMProvider;
+  model?: string;
+}): { llmConfig: Record<string, unknown>; modeDescription: string } {
+  let mode = args.mode;
+  if (!mode) {
+    if (config.llmEndpoint) mode = 'endpoint';
+    else if (config.llmApiKey && config.llmProvider) mode = 'api-key';
+    else mode = 'xache-managed';
+  }
+
+  const provider = args.provider || config.llmProvider || 'anthropic';
+  const model = args.model || config.llmModel || undefined;
+
+  if (mode === 'api-key') {
+    if (!config.llmApiKey) {
+      throw new Error('api-key mode requires XACHE_LLM_API_KEY environment variable.');
+    }
+    if (!SUPPORTED_PROVIDERS.includes(provider)) {
+      throw new Error(`Unsupported provider: ${provider}. Supported: ${SUPPORTED_PROVIDERS.join(', ')}`);
+    }
+    return {
+      llmConfig: { type: 'api-key' as const, provider, apiKey: config.llmApiKey, model },
+      modeDescription: `api-key (${provider})`,
+    };
+  } else if (mode === 'endpoint') {
+    if (!config.llmEndpoint) {
+      throw new Error('endpoint mode requires XACHE_LLM_ENDPOINT environment variable.');
+    }
+    return {
+      llmConfig: {
+        type: 'endpoint' as const,
+        url: config.llmEndpoint,
+        authToken: config.llmAuthToken || undefined,
+        format: config.llmFormat,
+        model,
+      },
+      modeDescription: `endpoint (${config.llmEndpoint.substring(0, 40)}...)`,
+    };
+  } else {
+    return {
+      llmConfig: {
+        type: 'xache-managed' as const,
+        provider: provider === 'anthropic' || provider === 'openai' ? provider : 'anthropic',
+        model,
+      },
+      modeDescription: `xache-managed (${provider})`,
+    };
+  }
+}
+
+async function handleGraphExtract(
+  client: XacheClient,
+  args: {
+    trace: string;
+    domain?: string;
+    mode?: 'api-key' | 'endpoint' | 'xache-managed';
+    provider?: LLMProvider;
+    model?: string;
+    confidenceThreshold?: number;
+    maxEntities?: number;
+    subject?: Record<string, unknown>;
+  }
+): Promise<string> {
+  const { llmConfig, modeDescription } = buildLLMConfig(args);
+  const subject = buildSubjectContext(args as Record<string, unknown>);
+
+  const result = await client.graph.extract({
+    trace: args.trace,
+    llmConfig: llmConfig as any,
+    subject,
+    options: {
+      contextHint: args.domain,
+      confidenceThreshold: args.confidenceThreshold ?? 0.7,
+      maxEntities: args.maxEntities,
+    },
+  });
+
+  const entities = result.entities || [];
+  const relationships = result.relationships || [];
+
+  if (entities.length === 0 && relationships.length === 0) {
+    return 'No entities or relationships extracted from trace.';
+  }
+
+  let output = `Extracted ${entities.length} entities and ${relationships.length} relationships.\n`;
+  output += `Mode: ${modeDescription}\n`;
+
+  if (entities.length > 0) {
+    output += '\nEntities:\n';
+    for (const e of entities) {
+      output += `  • ${e.name} [${e.type}]${e.isNew ? ' (new)' : ''}${e.updated ? ' (updated)' : ''}\n`;
+    }
+  }
+
+  if (relationships.length > 0) {
+    output += '\nRelationships:\n';
+    for (const r of relationships) {
+      output += `  • ${r.from} → ${r.type} → ${r.to}${r.isNew ? ' (new)' : ''}\n`;
+    }
+  }
+
+  if (result.temporalUpdates && result.temporalUpdates.length > 0) {
+    output += `\n${result.temporalUpdates.length} temporal update(s) detected.`;
+  }
+
+  output += `\nStored: ${result.stored} items`;
+  return output;
+}
+
+async function handleGraphLoad(
+  client: XacheClient,
+  args: {
+    entityTypes?: string[];
+    validAt?: string;
+    subject?: Record<string, unknown>;
+  }
+): Promise<string> {
+  const subject = buildSubjectContext(args as Record<string, unknown>);
+
+  const graph = await client.graph.load({
+    subject,
+    entityTypes: args.entityTypes,
+    validAt: args.validAt,
+  });
+
+  const data = graph.toJSON();
+  const entities = data.entities || [];
+  const relationships = data.relationships || [];
+
+  if (entities.length === 0) {
+    return 'Knowledge graph is empty.';
+  }
+
+  let output = `Knowledge graph: ${entities.length} entities, ${relationships.length} relationships\n`;
+
+  output += '\nEntities:\n';
+  for (const e of entities) {
+    output += `  • ${e.name} [${e.type}]`;
+    if (e.summary) output += ` — ${e.summary.substring(0, 80)}`;
+    output += '\n';
+  }
+
+  if (relationships.length > 0) {
+    output += '\nRelationships:\n';
+    for (const r of relationships) {
+      output += `  • ${r.fromKey.substring(0, 8)}... → ${r.type} → ${r.toKey.substring(0, 8)}...`;
+      if (r.description) output += ` (${r.description.substring(0, 60)})`;
+      output += '\n';
+    }
+  }
+
+  return output;
+}
+
+async function handleGraphQuery(
+  client: XacheClient,
+  args: {
+    startEntity: string;
+    depth?: number;
+    relationshipTypes?: string[];
+    validAt?: string;
+    subject?: Record<string, unknown>;
+  }
+): Promise<string> {
+  const subject = buildSubjectContext(args as Record<string, unknown>);
+
+  const graph = await client.graph.query({
+    subject,
+    startEntity: args.startEntity,
+    depth: args.depth ?? 2,
+    relationshipTypes: args.relationshipTypes,
+    validAt: args.validAt,
+  });
+
+  const data = graph.toJSON();
+  const entities = data.entities || [];
+  const relationships = data.relationships || [];
+
+  if (entities.length === 0) {
+    return `No entities found connected to "${args.startEntity}".`;
+  }
+
+  let output = `Subgraph around "${args.startEntity}": ${entities.length} entities, ${relationships.length} relationships\n`;
+
+  output += '\nEntities:\n';
+  for (const e of entities) {
+    output += `  • ${e.name} [${e.type}]`;
+    if (e.summary) output += ` — ${e.summary.substring(0, 80)}`;
+    output += '\n';
+  }
+
+  if (relationships.length > 0) {
+    output += '\nRelationships:\n';
+    for (const r of relationships) {
+      output += `  • ${r.fromKey.substring(0, 8)}... → ${r.type} → ${r.toKey.substring(0, 8)}...`;
+      if (r.description) output += ` (${r.description.substring(0, 60)})`;
+      output += '\n';
+    }
+  }
+
+  return output;
+}
+
+async function handleGraphAsk(
+  client: XacheClient,
+  args: {
+    question: string;
+    mode?: 'api-key' | 'endpoint' | 'xache-managed';
+    provider?: LLMProvider;
+    model?: string;
+    subject?: Record<string, unknown>;
+  }
+): Promise<string> {
+  const { llmConfig, modeDescription } = buildLLMConfig(args);
+  const subject = buildSubjectContext(args as Record<string, unknown>);
+
+  const answer = await client.graph.ask({
+    subject,
+    question: args.question,
+    llmConfig: llmConfig as any,
+  });
+
+  let output = `Answer: ${answer.answer}\n`;
+  output += `Confidence: ${(answer.confidence * 100).toFixed(0)}%\n`;
+  output += `Mode: ${modeDescription}\n`;
+
+  if (answer.sources && answer.sources.length > 0) {
+    output += '\nSources:\n';
+    for (const s of answer.sources) {
+      output += `  • ${s.name} [${s.type}]\n`;
+    }
+  }
+
+  return output;
+}
+
+async function handleGraphAddEntity(
+  client: XacheClient,
+  args: {
+    name: string;
+    type: string;
+    summary?: string;
+    attributes?: Record<string, unknown>;
+    subject?: Record<string, unknown>;
+  }
+): Promise<string> {
+  const subject = buildSubjectContext(args as Record<string, unknown>);
+
+  const entity = await client.graph.addEntity({
+    subject,
+    name: args.name,
+    type: args.type,
+    summary: args.summary,
+    attributes: args.attributes,
+  });
+
+  return `Created entity "${entity.name}" [${entity.type}]\nKey: ${entity.key}\nStorage Key: ${entity.storageKey}`;
+}
+
+async function handleGraphAddRelationship(
+  client: XacheClient,
+  args: {
+    fromEntity: string;
+    toEntity: string;
+    type: string;
+    description?: string;
+    attributes?: Record<string, unknown>;
+    subject?: Record<string, unknown>;
+  }
+): Promise<string> {
+  const subject = buildSubjectContext(args as Record<string, unknown>);
+
+  const rel = await client.graph.addRelationship({
+    subject,
+    from: args.fromEntity,
+    to: args.toEntity,
+    type: args.type,
+    description: args.description,
+    attributes: args.attributes,
+  });
+
+  return `Created relationship: ${args.fromEntity} → ${rel.type} → ${args.toEntity}\nStorage Key: ${rel.storageKey}`;
+}
+
+async function handleGraphMergeEntities(
+  client: XacheClient,
+  args: {
+    sourceName: string;
+    targetName: string;
+    subject?: Record<string, unknown>;
+  }
+): Promise<string> {
+  const subject = buildSubjectContext(args as Record<string, unknown>);
+
+  const merged = await client.graph.mergeEntities({
+    subject,
+    sourceName: args.sourceName,
+    targetName: args.targetName,
+  });
+
+  return `Merged "${args.sourceName}" into "${args.targetName}".\nResult: ${merged.name} [${merged.type}] (v${merged.version})\nKey: ${merged.key}`;
+}
+
+async function handleGraphEntityHistory(
+  client: XacheClient,
+  args: {
+    name: string;
+    subject?: Record<string, unknown>;
+  }
+): Promise<string> {
+  const subject = buildSubjectContext(args as Record<string, unknown>);
+
+  const versions = await client.graph.getEntityHistory({
+    subject,
+    name: args.name,
+  });
+
+  if (versions.length === 0) {
+    return `No history found for entity "${args.name}".`;
+  }
+
+  let output = `History for "${args.name}": ${versions.length} version(s)\n`;
+
+  for (const v of versions) {
+    output += `\n  v${v.version} — ${v.name} [${v.type}]`;
+    if (v.summary) output += `\n    Summary: ${v.summary.substring(0, 100)}`;
+    output += `\n    Valid: ${v.validFrom}${v.validTo ? ` → ${v.validTo}` : ' → current'}`;
+  }
+
+  return output;
+}
+
 // =============================================================================
 // Server Setup
 // =============================================================================
@@ -813,7 +1436,7 @@ async function main(): Promise<void> {
   const server = new Server(
     {
       name: 'xache-mcp-server',
-      version: '0.2.0',
+      version: '0.3.0',
     },
     {
       capabilities: {
@@ -872,6 +1495,30 @@ async function main(): Promise<void> {
         case 'xache_extract_and_contribute':
           result = await handleExtractAndContribute(client, args as any);
           break;
+        case 'xache_graph_extract':
+          result = await handleGraphExtract(client, args as any);
+          break;
+        case 'xache_graph_load':
+          result = await handleGraphLoad(client, args as any);
+          break;
+        case 'xache_graph_query':
+          result = await handleGraphQuery(client, args as any);
+          break;
+        case 'xache_graph_ask':
+          result = await handleGraphAsk(client, args as any);
+          break;
+        case 'xache_graph_add_entity':
+          result = await handleGraphAddEntity(client, args as any);
+          break;
+        case 'xache_graph_add_relationship':
+          result = await handleGraphAddRelationship(client, args as any);
+          break;
+        case 'xache_graph_merge_entities':
+          result = await handleGraphMergeEntities(client, args as any);
+          break;
+        case 'xache_graph_entity_history':
+          result = await handleGraphEntityHistory(client, args as any);
+          break;
         default:
           throw new Error(`Unknown tool: ${name}`);
       }