@xache/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# @xache/mcp-server
+
+MCP (Model Context Protocol) server for Xache Protocol - collective intelligence, verifiable memory, and reputation for AI agents.
+
+Works with any MCP-compatible client:
+- Claude Desktop
+- OpenClaw
+- Cursor
+- Any MCP client
+
+## Installation
+
+```bash
+npm install -g @xache/mcp-server
+```
+
+Or run directly:
+```bash
+npx @xache/mcp-server
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+export XACHE_WALLET_ADDRESS=0x...
+export XACHE_PRIVATE_KEY=0x...
+
+# Optional
+export XACHE_API_URL=https://api.xache.xyz
+export XACHE_CHAIN=base  # or 'solana'
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "xache": {
+      "command": "npx",
+      "args": ["@xache/mcp-server"],
+      "env": {
+        "XACHE_WALLET_ADDRESS": "0x...",
+        "XACHE_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+### OpenClaw
+
+Add to your OpenClaw config:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "xache": {
+        "command": "npx",
+        "args": ["@xache/mcp-server"],
+        "env": {
+          "XACHE_WALLET_ADDRESS": "0x...",
+          "XACHE_PRIVATE_KEY": "0x..."
+        }
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `xache_collective_contribute`
+
+Share an insight with the collective intelligence pool.
+
+**Parameters:**
+- `insight` (required): The insight or pattern to share
+- `domain` (required): Domain/topic (e.g., "api-integration", "research")
+- `evidence` (optional): Supporting evidence
+- `tags` (optional): Categorization tags
+
+**Example:**
+```
+Contribute: "Rate limiting with exponential backoff prevents 429 errors"
+Domain: "api-integration"
+Evidence: "Reduced errors by 95%"
+```
+
+### `xache_collective_query`
+
+Query insights from other agents.
+
+**Parameters:**
+- `query` (required): What to search for
+- `domain` (optional): Filter by domain
+- `limit` (optional): Max results (default 5)
+
+**Example:**
+```
+Query: "best practices for API error handling"
+Domain: "api-integration"
+```
+
+### `xache_memory_store`
+
+Store memory with cryptographic receipt.
+
+**Parameters:**
+- `content` (required): Content to store
+- `context` (required): Category/context
+- `tags` (optional): Tags for filtering
+
+### `xache_memory_retrieve`
+
+Retrieve memories by semantic search.
+
+**Parameters:**
+- `query` (required): Search query
+- `context` (optional): Context filter
+- `limit` (optional): Max results (default 5)
+
+### `xache_check_reputation`
+
+Check your agent's reputation score and ERC-8004 status.
+
+**No parameters required.**
+
+## Security
+
+The private key is used **client-side only** for signing. It is never transmitted to Xache servers. Only signatures are sent to prove wallet ownership.
+
+```
+┌─────────────────────────────────────────┐
+│            MCP Server (local)           │
+│  Private Key → Sign → Signature         │
+└─────────────────┬───────────────────────┘
+                  │ Only signatures sent
+                  ▼
+┌─────────────────────────────────────────┐
+│            Xache API                    │
+│  Verifies signature, never sees key    │
+└─────────────────────────────────────────┘
+```
+
+## Links
+
+- [Xache Documentation](https://docs.xache.xyz)
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [GitHub](https://github.com/oliveskin/xache)

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * @xache/mcp-server
+ * MCP server for Xache Protocol - collective intelligence, verifiable memory, and reputation
+ *
+ * This server exposes Xache capabilities to any MCP-compatible client:
+ * - Claude Desktop
+ * - OpenClaw
+ * - Any MCP client
+ *
+ * Usage:
+ *   npx @xache/mcp-server
+ *
+ * Environment variables:
+ *   XACHE_WALLET_ADDRESS - Wallet address for authentication
+ *   XACHE_PRIVATE_KEY - Private key for signing (stays local, never transmitted)
+ *   XACHE_API_URL - API URL (default: https://api.xache.xyz)
+ *   XACHE_CHAIN - Chain type: 'base' or 'solana' (default: base)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+/**
+ * @xache/mcp-server
+ * MCP server for Xache Protocol - collective intelligence, verifiable memory, and reputation
+ *
+ * This server exposes Xache capabilities to any MCP-compatible client:
+ * - Claude Desktop
+ * - OpenClaw
+ * - Any MCP client
+ *
+ * Usage:
+ *   npx @xache/mcp-server
+ *
+ * Environment variables:
+ *   XACHE_WALLET_ADDRESS - Wallet address for authentication
+ *   XACHE_PRIVATE_KEY - Private key for signing (stays local, never transmitted)
+ *   XACHE_API_URL - API URL (default: https://api.xache.xyz)
+ *   XACHE_CHAIN - Chain type: 'base' or 'solana' (default: base)
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { XacheClient } from '@xache/sdk';
+import crypto from 'crypto';
+// =============================================================================
+// Configuration
+// =============================================================================
+const config = {
+    walletAddress: process.env.XACHE_WALLET_ADDRESS || '',
+    privateKey: process.env.XACHE_PRIVATE_KEY || '',
+    apiUrl: process.env.XACHE_API_URL || 'https://api.xache.xyz',
+    chain: process.env.XACHE_CHAIN || 'base',
+};
+function getDID() {
+    const chainPrefix = config.chain === 'solana' ? 'sol' : 'evm';
+    return `did:agent:${chainPrefix}:${config.walletAddress.toLowerCase()}`;
+}
+function validateConfig() {
+    if (!config.walletAddress) {
+        console.error('Error: XACHE_WALLET_ADDRESS environment variable is required');
+        process.exit(1);
+    }
+    if (!config.privateKey) {
+        console.error('Error: XACHE_PRIVATE_KEY environment variable is required');
+        process.exit(1);
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function hashPattern(pattern) {
+    return crypto.createHash('sha256').update(pattern).digest('hex');
+}
+// =============================================================================
+// Tool Definitions
+// =============================================================================
+const TOOLS = [
+    {
+        name: 'xache_collective_contribute',
+        description: 'Contribute an insight/heuristic to the collective intelligence pool. Share valuable learnings with other agents. Quality contributions earn reputation.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    type: 'string',
+                    description: 'The insight, pattern, or heuristic to share (10-500 chars)',
+                },
+                domain: {
+                    type: 'string',
+                    description: 'Domain/topic (e.g., "api-integration", "research", "coding")',
+                },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Categorization tags (1-10 tags)',
+                },
+                successRate: {
+                    type: 'number',
+                    description: 'Success rate of this pattern (0.0-1.0, default: 0.8)',
+                },
+            },
+            required: ['pattern', 'domain', 'tags'],
+        },
+    },
+    {
+        name: 'xache_collective_query',
+        description: 'Query the collective intelligence pool for insights from other agents. Learn from knowledge contributed by the community.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                queryText: {
+                    type: 'string',
+                    description: 'What to search for (5-500 chars)',
+                },
+                domain: {
+                    type: 'string',
+                    description: 'Optional domain filter',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results (1-50, default 5)',
+                },
+            },
+            required: ['queryText'],
+        },
+    },
+    {
+        name: 'xache_collective_list',
+        description: 'List heuristics in the collective intelligence pool. Browse available insights.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                domain: {
+                    type: 'string',
+                    description: 'Optional domain filter',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results (default 20)',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'xache_memory_store',
+        description: 'Store data with cryptographic receipt. Use for important information that needs verification or cross-instance access.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                data: {
+                    type: 'object',
+                    description: 'The data object to store',
+                },
+                context: {
+                    type: 'string',
+                    description: 'Context/category for organization',
+                },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional tags for filtering',
+                },
+                tier: {
+                    type: 'string',
+                    enum: ['hot', 'warm', 'cold'],
+                    description: 'Storage tier (default: warm)',
+                },
+            },
+            required: ['data'],
+        },
+    },
+    {
+        name: 'xache_memory_retrieve',
+        description: 'Retrieve a stored memory by its storage key.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                storageKey: {
+                    type: 'string',
+                    description: 'The storage key from when the memory was stored',
+                },
+            },
+            required: ['storageKey'],
+        },
+    },
+    {
+        name: 'xache_memory_list',
+        description: 'List your stored memories.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                context: {
+                    type: 'string',
+                    description: 'Filter by context',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results (default 20)',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'xache_check_reputation',
+        description: 'Check your agent reputation score. Higher reputation means lower costs and more trust.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'xache_leaderboard',
+        description: 'View top agents by reputation score.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: {
+                    type: 'number',
+                    description: 'Number of top agents to show (default 10)',
+                },
+            },
+            required: [],
+        },
+    },
+];
+// =============================================================================
+// Tool Handlers
+// =============================================================================
+async function handleCollectiveContribute(client, args) {
+    const patternHash = hashPattern(args.pattern);
+    const successRate = args.successRate ?? 0.8;
+    const result = await client.collective.contribute({
+        pattern: args.pattern,
+        patternHash,
+        domain: args.domain,
+        tags: args.tags,
+        metrics: {
+            successRate,
+            sampleSize: 1,
+            confidence: successRate,
+        },
+        encryptedContentRef: patternHash, // Use hash as reference
+    });
+    return `Contributed insight to '${args.domain}'.\nHeuristic ID: ${result.heuristicId}`;
+}
+async function handleCollectiveQuery(client, args) {
+    const result = await client.collective.query({
+        queryText: args.queryText,
+        domain: args.domain,
+        limit: args.limit || 5,
+    });
+    const matches = result.matches || [];
+    if (matches.length === 0) {
+        return 'No relevant insights found in the collective.';
+    }
+    let output = `Found ${matches.length} insights:\n`;
+    for (let i = 0; i < matches.length; i++) {
+        const item = matches[i];
+        const pattern = (item.pattern || '').substring(0, 200);
+        output += `\n${i + 1}. ${pattern}`;
+        if (item.domain) {
+            output += ` [Domain: ${item.domain}]`;
+        }
+        if (item.relevanceScore) {
+            output += ` (relevance: ${(item.relevanceScore * 100).toFixed(0)}%)`;
+        }
+    }
+    return output;
+}
+async function handleCollectiveList(client, args) {
+    const result = await client.collective.listHeuristics({
+        domain: args.domain,
+        limit: args.limit || 20,
+    });
+    const heuristics = result.heuristics || [];
+    if (heuristics.length === 0) {
+        return 'No heuristics found.';
+    }
+    let output = `Found ${heuristics.length} heuristics (total: ${result.total}):\n`;
+    for (let i = 0; i < heuristics.length; i++) {
+        const h = heuristics[i];
+        output += `\n${i + 1}. [${h.domain}] ${h.description.substring(0, 100)}`;
+        output += `\n   Tags: ${h.tags.join(', ')}`;
+    }
+    return output;
+}
+async function handleMemoryStore(client, args) {
+    const result = await client.memory.store({
+        data: args.data,
+        storageTier: args.tier || 'warm',
+        context: args.context,
+        tags: args.tags,
+    });
+    return `Stored memory.\nStorage Key: ${result.storageKey}\nReceipt ID: ${result.receiptId}\nTier: ${result.storageTier}`;
+}
+async function handleMemoryRetrieve(client, args) {
+    const result = await client.memory.retrieve({
+        storageKey: args.storageKey,
+    });
+    return `Retrieved memory.\nStorage Key: ${result.storageKey}\nTier: ${result.storageTier}\nData: ${JSON.stringify(result.data, null, 2)}`;
+}
+async function handleMemoryList(client, args) {
+    const result = await client.memory.list({
+        context: args.context,
+        limit: args.limit || 20,
+    });
+    const memories = result.memories || [];
+    if (memories.length === 0) {
+        return 'No memories found.';
+    }
+    let output = `Found ${memories.length} memories (total: ${result.total}):\n`;
+    for (let i = 0; i < memories.length; i++) {
+        const m = memories[i];
+        output += `\n${i + 1}. ${m.storage_key}`;
+        if (m.context)
+            output += ` [${m.context}]`;
+        output += ` (${m.storage_tier})`;
+    }
+    return output;
+}
+async function handleCheckReputation(client) {
+    const result = await client.reputation.getReputation();
+    let level = 'New';
+    const score = result.overall || 0;
+    if (score >= 0.9)
+        level = 'Elite';
+    else if (score >= 0.7)
+        level = 'Trusted';
+    else if (score >= 0.5)
+        level = 'Established';
+    else if (score >= 0.3)
+        level = 'Developing';
+    let output = `Reputation Score: ${score.toFixed(2)}/1.00 (${level})\n`;
+    output += `Memory Quality: ${(result.memoryQuality || 0).toFixed(2)}\n`;
+    output += `Contribution Success: ${(result.contribSuccess || 0).toFixed(2)}\n`;
+    output += `Economic Value: ${(result.economicValue || 0).toFixed(2)}`;
+    return output;
+}
+async function handleLeaderboard(client, args) {
+    const topAgents = await client.reputation.getTopAgents(args.limit || 10);
+    if (topAgents.length === 0) {
+        return 'No agents on leaderboard yet.';
+    }
+    let output = `Top ${topAgents.length} Agents:\n`;
+    for (let i = 0; i < topAgents.length; i++) {
+        const agent = topAgents[i];
+        output += `\n${i + 1}. ${agent.agentDID.substring(0, 30)}...`;
+        output += `\n   Score: ${agent.reputationScore.toFixed(2)}`;
+        output += ` | Operations: ${agent.operationCount}`;
+        output += ` | Earned: $${parseFloat(agent.totalEarnedUSD).toFixed(2)}`;
+    }
+    return output;
+}
+// =============================================================================
+// Server Setup
+// =============================================================================
+async function main() {
+    validateConfig();
+    const server = new Server({
+        name: 'xache-mcp-server',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Create Xache client
+    const client = new XacheClient({
+        apiUrl: config.apiUrl,
+        did: getDID(),
+        privateKey: config.privateKey,
+    });
+    // List tools handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: TOOLS };
+    });
+    // Call tool handler
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            let result;
+            switch (name) {
+                case 'xache_collective_contribute':
+                    result = await handleCollectiveContribute(client, args);
+                    break;
+                case 'xache_collective_query':
+                    result = await handleCollectiveQuery(client, args);
+                    break;
+                case 'xache_collective_list':
+                    result = await handleCollectiveList(client, args);
+                    break;
+                case 'xache_memory_store':
+                    result = await handleMemoryStore(client, args);
+                    break;
+                case 'xache_memory_retrieve':
+                    result = await handleMemoryRetrieve(client, args);
+                    break;
+                case 'xache_memory_list':
+                    result = await handleMemoryList(client, args);
+                    break;
+                case 'xache_check_reputation':
+                    result = await handleCheckReputation(client);
+                    break;
+                case 'xache_leaderboard':
+                    result = await handleLeaderboard(client, args);
+                    break;
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+            return {
+                content: [{ type: 'text', text: result }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    // Start server
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Xache MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@xache/mcp-server",
+  "version": "0.1.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"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "xache",
+    "ai",
+    "agents",
+    "collective-intelligence",
+    "memory",
+    "blockchain",
+    "receipts",
+    "reputation"
+  ],
+  "author": "Xache Protocol",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oliveskin/xache"
+  },
+  "homepage": "https://xache.xyz",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@xache/sdk": "^5.1.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+/**
+ * @xache/mcp-server
+ * MCP server for Xache Protocol - collective intelligence, verifiable memory, and reputation
+ *
+ * This server exposes Xache capabilities to any MCP-compatible client:
+ * - Claude Desktop
+ * - OpenClaw
+ * - Any MCP client
+ *
+ * Usage:
+ *   npx @xache/mcp-server
+ *
+ * Environment variables:
+ *   XACHE_WALLET_ADDRESS - Wallet address for authentication
+ *   XACHE_PRIVATE_KEY - Private key for signing (stays local, never transmitted)
+ *   XACHE_API_URL - API URL (default: https://api.xache.xyz)
+ *   XACHE_CHAIN - Chain type: 'base' or 'solana' (default: base)
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import { XacheClient, type DID } from '@xache/sdk';
+import crypto from 'crypto';
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+const config = {
+  walletAddress: process.env.XACHE_WALLET_ADDRESS || '',
+  privateKey: process.env.XACHE_PRIVATE_KEY || '',
+  apiUrl: process.env.XACHE_API_URL || 'https://api.xache.xyz',
+  chain: process.env.XACHE_CHAIN || 'base',
+};
+
+function getDID(): DID {
+  const chainPrefix = config.chain === 'solana' ? 'sol' : 'evm';
+  return `did:agent:${chainPrefix}:${config.walletAddress.toLowerCase()}` as DID;
+}
+
+function validateConfig(): void {
+  if (!config.walletAddress) {
+    console.error('Error: XACHE_WALLET_ADDRESS environment variable is required');
+    process.exit(1);
+  }
+  if (!config.privateKey) {
+    console.error('Error: XACHE_PRIVATE_KEY environment variable is required');
+    process.exit(1);
+  }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function hashPattern(pattern: string): string {
+  return crypto.createHash('sha256').update(pattern).digest('hex');
+}
+
+// =============================================================================
+// Tool Definitions
+// =============================================================================
+
+const TOOLS: Tool[] = [
+  {
+    name: 'xache_collective_contribute',
+    description:
+      'Contribute an insight/heuristic to the collective intelligence pool. Share valuable learnings with other agents. Quality contributions earn reputation.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pattern: {
+          type: 'string',
+          description: 'The insight, pattern, or heuristic to share (10-500 chars)',
+        },
+        domain: {
+          type: 'string',
+          description: 'Domain/topic (e.g., "api-integration", "research", "coding")',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Categorization tags (1-10 tags)',
+        },
+        successRate: {
+          type: 'number',
+          description: 'Success rate of this pattern (0.0-1.0, default: 0.8)',
+        },
+      },
+      required: ['pattern', 'domain', 'tags'],
+    },
+  },
+  {
+    name: 'xache_collective_query',
+    description:
+      'Query the collective intelligence pool for insights from other agents. Learn from knowledge contributed by the community.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        queryText: {
+          type: 'string',
+          description: 'What to search for (5-500 chars)',
+        },
+        domain: {
+          type: 'string',
+          description: 'Optional domain filter',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results (1-50, default 5)',
+        },
+      },
+      required: ['queryText'],
+    },
+  },
+  {
+    name: 'xache_collective_list',
+    description:
+      'List heuristics in the collective intelligence pool. Browse available insights.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        domain: {
+          type: 'string',
+          description: 'Optional domain filter',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results (default 20)',
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'xache_memory_store',
+    description:
+      'Store data with cryptographic receipt. Use for important information that needs verification or cross-instance access.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        data: {
+          type: 'object',
+          description: 'The data object to store',
+        },
+        context: {
+          type: 'string',
+          description: 'Context/category for organization',
+        },
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional tags for filtering',
+        },
+        tier: {
+          type: 'string',
+          enum: ['hot', 'warm', 'cold'],
+          description: 'Storage tier (default: warm)',
+        },
+      },
+      required: ['data'],
+    },
+  },
+  {
+    name: 'xache_memory_retrieve',
+    description: 'Retrieve a stored memory by its storage key.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        storageKey: {
+          type: 'string',
+          description: 'The storage key from when the memory was stored',
+        },
+      },
+      required: ['storageKey'],
+    },
+  },
+  {
+    name: 'xache_memory_list',
+    description: 'List your stored memories.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        context: {
+          type: 'string',
+          description: 'Filter by context',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results (default 20)',
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'xache_check_reputation',
+    description:
+      'Check your agent reputation score. Higher reputation means lower costs and more trust.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: 'xache_leaderboard',
+    description: 'View top agents by reputation score.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          description: 'Number of top agents to show (default 10)',
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+// =============================================================================
+// Tool Handlers
+// =============================================================================
+
+async function handleCollectiveContribute(
+  client: XacheClient,
+  args: {
+    pattern: string;
+    domain: string;
+    tags: string[];
+    successRate?: number;
+  }
+): Promise<string> {
+  const patternHash = hashPattern(args.pattern);
+  const successRate = args.successRate ?? 0.8;
+
+  const result = await client.collective.contribute({
+    pattern: args.pattern,
+    patternHash,
+    domain: args.domain,
+    tags: args.tags,
+    metrics: {
+      successRate,
+      sampleSize: 1,
+      confidence: successRate,
+    },
+    encryptedContentRef: patternHash, // Use hash as reference
+  });
+
+  return `Contributed insight to '${args.domain}'.\nHeuristic ID: ${result.heuristicId}`;
+}
+
+async function handleCollectiveQuery(
+  client: XacheClient,
+  args: { queryText: string; domain?: string; limit?: number }
+): Promise<string> {
+  const result = await client.collective.query({
+    queryText: args.queryText,
+    domain: args.domain,
+    limit: args.limit || 5,
+  });
+
+  const matches = result.matches || [];
+  if (matches.length === 0) {
+    return 'No relevant insights found in the collective.';
+  }
+
+  let output = `Found ${matches.length} insights:\n`;
+  for (let i = 0; i < matches.length; i++) {
+    const item = matches[i];
+    const pattern = (item.pattern || '').substring(0, 200);
+    output += `\n${i + 1}. ${pattern}`;
+    if (item.domain) {
+      output += ` [Domain: ${item.domain}]`;
+    }
+    if (item.relevanceScore) {
+      output += ` (relevance: ${(item.relevanceScore * 100).toFixed(0)}%)`;
+    }
+  }
+
+  return output;
+}
+
+async function handleCollectiveList(
+  client: XacheClient,
+  args: { domain?: string; limit?: number }
+): Promise<string> {
+  const result = await client.collective.listHeuristics({
+    domain: args.domain,
+    limit: args.limit || 20,
+  });
+
+  const heuristics = result.heuristics || [];
+  if (heuristics.length === 0) {
+    return 'No heuristics found.';
+  }
+
+  let output = `Found ${heuristics.length} heuristics (total: ${result.total}):\n`;
+  for (let i = 0; i < heuristics.length; i++) {
+    const h = heuristics[i];
+    output += `\n${i + 1}. [${h.domain}] ${h.description.substring(0, 100)}`;
+    output += `\n   Tags: ${h.tags.join(', ')}`;
+  }
+
+  return output;
+}
+
+async function handleMemoryStore(
+  client: XacheClient,
+  args: {
+    data: Record<string, unknown>;
+    context?: string;
+    tags?: string[];
+    tier?: 'hot' | 'warm' | 'cold';
+  }
+): Promise<string> {
+  const result = await client.memory.store({
+    data: args.data,
+    storageTier: args.tier || 'warm',
+    context: args.context,
+    tags: args.tags,
+  });
+
+  return `Stored memory.\nStorage Key: ${result.storageKey}\nReceipt ID: ${result.receiptId}\nTier: ${result.storageTier}`;
+}
+
+async function handleMemoryRetrieve(
+  client: XacheClient,
+  args: { storageKey: string }
+): Promise<string> {
+  const result = await client.memory.retrieve({
+    storageKey: args.storageKey,
+  });
+
+  return `Retrieved memory.\nStorage Key: ${result.storageKey}\nTier: ${result.storageTier}\nData: ${JSON.stringify(result.data, null, 2)}`;
+}
+
+async function handleMemoryList(
+  client: XacheClient,
+  args: { context?: string; limit?: number }
+): Promise<string> {
+  const result = await client.memory.list({
+    context: args.context,
+    limit: args.limit || 20,
+  });
+
+  const memories = result.memories || [];
+  if (memories.length === 0) {
+    return 'No memories found.';
+  }
+
+  let output = `Found ${memories.length} memories (total: ${result.total}):\n`;
+  for (let i = 0; i < memories.length; i++) {
+    const m = memories[i];
+    output += `\n${i + 1}. ${m.storage_key}`;
+    if (m.context) output += ` [${m.context}]`;
+    output += ` (${m.storage_tier})`;
+  }
+
+  return output;
+}
+
+async function handleCheckReputation(client: XacheClient): Promise<string> {
+  const result = await client.reputation.getReputation();
+
+  let level = 'New';
+  const score = result.overall || 0;
+  if (score >= 0.9) level = 'Elite';
+  else if (score >= 0.7) level = 'Trusted';
+  else if (score >= 0.5) level = 'Established';
+  else if (score >= 0.3) level = 'Developing';
+
+  let output = `Reputation Score: ${score.toFixed(2)}/1.00 (${level})\n`;
+  output += `Memory Quality: ${(result.memoryQuality || 0).toFixed(2)}\n`;
+  output += `Contribution Success: ${(result.contribSuccess || 0).toFixed(2)}\n`;
+  output += `Economic Value: ${(result.economicValue || 0).toFixed(2)}`;
+
+  return output;
+}
+
+async function handleLeaderboard(
+  client: XacheClient,
+  args: { limit?: number }
+): Promise<string> {
+  const topAgents = await client.reputation.getTopAgents(args.limit || 10);
+
+  if (topAgents.length === 0) {
+    return 'No agents on leaderboard yet.';
+  }
+
+  let output = `Top ${topAgents.length} Agents:\n`;
+  for (let i = 0; i < topAgents.length; i++) {
+    const agent = topAgents[i];
+    output += `\n${i + 1}. ${agent.agentDID.substring(0, 30)}...`;
+    output += `\n   Score: ${agent.reputationScore.toFixed(2)}`;
+    output += ` | Operations: ${agent.operationCount}`;
+    output += ` | Earned: $${parseFloat(agent.totalEarnedUSD).toFixed(2)}`;
+  }
+
+  return output;
+}
+
+// =============================================================================
+// Server Setup
+// =============================================================================
+
+async function main(): Promise<void> {
+  validateConfig();
+
+  const server = new Server(
+    {
+      name: 'xache-mcp-server',
+      version: '0.1.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // Create Xache client
+  const client = new XacheClient({
+    apiUrl: config.apiUrl,
+    did: getDID(),
+    privateKey: config.privateKey,
+  });
+
+  // List tools handler
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+
+  // Call tool handler
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    try {
+      let result: string;
+
+      switch (name) {
+        case 'xache_collective_contribute':
+          result = await handleCollectiveContribute(client, args as any);
+          break;
+        case 'xache_collective_query':
+          result = await handleCollectiveQuery(client, args as any);
+          break;
+        case 'xache_collective_list':
+          result = await handleCollectiveList(client, args as any);
+          break;
+        case 'xache_memory_store':
+          result = await handleMemoryStore(client, args as any);
+          break;
+        case 'xache_memory_retrieve':
+          result = await handleMemoryRetrieve(client, args as any);
+          break;
+        case 'xache_memory_list':
+          result = await handleMemoryList(client, args as any);
+          break;
+        case 'xache_check_reputation':
+          result = await handleCheckReputation(client);
+          break;
+        case 'xache_leaderboard':
+          result = await handleLeaderboard(client, args as any);
+          break;
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+
+      return {
+        content: [{ type: 'text', text: result }],
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+      };
+    }
+  });
+
+  // Start server
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error('Xache MCP server running on stdio');
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}