@ekkos/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# @ekkos/mcp-server
+
+Stdio-to-SSE bridge for [ekkOS](https://ekkos.dev) Memory substrate. Enables AI tools like Claude Code and Cursor to access your persistent memory via the Model Context Protocol (MCP).
+
+## Quick Start
+
+### Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "ekkos-memory": {
+      "command": "npx",
+      "args": ["-y", "@ekkos/mcp-server"],
+      "env": {
+        "EKKOS_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "ekkos-memory": {
+      "command": "npx",
+      "args": ["-y", "@ekkos/mcp-server"],
+      "env": {
+        "EKKOS_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Get Your API Key
+
+1. Go to [platform.ekkos.dev](https://platform.ekkos.dev)
+2. Sign up or log in
+3. Navigate to **Settings → API Keys**
+4. Click **"Generate New Key"**
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `EKKOS_API_KEY` | ✅ Yes | Your ekkOS API key from platform.ekkos.dev |
+| `EKKOS_USER_ID` | ❌ No | Your user ID (optional, for better tracking) |
+| `EKKOS_MCP_URL` | ❌ No | Custom MCP gateway URL (default: https://mcp.ekkos.dev/api/v1/mcp/sse) |
+| `EKKOS_DEBUG` | ❌ No | Set to `true` for debug logs |
+
+## How It Works
+
+This package creates a bridge between:
+- **Stdio transport** (used by AI tools like Claude Code)
+- **SSE transport** (used by ekkOS cloud memory substrate)
+
+When your AI tool starts the MCP server, this bridge:
+1. Connects to ekkOS cloud via SSE using your API key
+2. Exposes a stdio interface for your AI tool
+3. Forwards all MCP messages between stdio and SSE
+4. Handles authentication, reconnection, and error handling
+
+## Available Memory Tools
+
+Once connected, your AI will have access to these ekkOS memory tools:
+
+### The 5 Verbs
+- `ekko` - Search memory for patterns and solutions
+- `crystallize` - Save important decisions permanently
+- `reflex` - Validate suggestions against your history
+- `trace` - Explain why a suggestion was made
+- `consolidate` - Get summary of recent memory activity
+
+### Core Operations
+- `search_memory` - Search across all 10 memory layers
+- `forge_pattern` - Create new patterns from learnings
+- `forge_directive` - Set MUST/NEVER/PREFER/AVOID rules
+- `get_context` - Get relevant context for a task
+- `recall_conversation` - Recall what was discussed at a specific time
+- `search_codebase` - Search project code embeddings
+
+### Golden Loop Tracking
+- `track_application` - Track when memories are applied
+- `record_outcome` - Record if applied memories helped
+- `detect_usage` - Auto-detect pattern usage via semantic similarity
+- `check_conflict` - Check for conflicts with directives
+
+[See full MCP tools reference](https://docs.ekkos.dev/api-reference/mcp-tools)
+
+## Troubleshooting
+
+### "EKKOS_API_KEY environment variable is required"
+You need to set your API key in the MCP config. Get one at [platform.ekkos.dev](https://platform.ekkos.dev/dashboard/settings/api-keys).
+
+### MCP server not loading
+1. Check Node.js version: `node --version` (must be 18+)
+2. Verify config JSON is valid
+3. Try running manually: `EKKOS_API_KEY=xxx npx @ekkos/mcp-server`
+4. Enable debug mode: `EKKOS_DEBUG=true` in env
+
+### Connection errors
+1. Check your internet connection
+2. Verify API key is correct and active
+3. Check https://status.ekkos.dev for service status
+
+## Support
+
+- 📚 [Documentation](https://docs.ekkos.dev)
+- 💬 [Discord Community](https://discord.gg/ekkos)
+- 🐛 [Report Issues](https://github.com/ekkos-ai/ekkos/issues)
+- 📧 [Email Support](mailto:support@ekkos.dev)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * @ekkos/mcp-server
+ *
+ * Simple stdio proxy to ekkOS cloud MCP gateway.
+ * This creates a local MCP server that forwards all requests to https://mcp.ekkos.dev
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * @ekkos/mcp-server
+ *
+ * Simple stdio proxy to ekkOS cloud MCP gateway.
+ * This creates a local MCP server that forwards all requests to https://mcp.ekkos.dev
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+// Configuration
+const EKKOS_API_KEY = process.env.EKKOS_API_KEY || '';
+const EKKOS_USER_ID = process.env.EKKOS_USER_ID || '';
+const EKKOS_MCP_URL = process.env.EKKOS_MCP_URL || 'https://mcp.ekkos.dev/api/v1/mcp';
+const DEBUG = process.env.EKKOS_DEBUG === 'true';
+if (!EKKOS_API_KEY) {
+    console.error('[ekkOS] ERROR: EKKOS_API_KEY environment variable is required');
+    console.error('[ekkOS] Get your API key at https://platform.ekkos.dev/dashboard/settings/api-keys');
+    process.exit(1);
+}
+// Simple HTTP client for MCP gateway
+async function callGateway(endpoint, method, params) {
+    const url = `${EKKOS_MCP_URL}/${endpoint}`;
+    const headers = {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${EKKOS_API_KEY}`,
+    };
+    if (EKKOS_USER_ID) {
+        headers['X-User-ID'] = EKKOS_USER_ID;
+    }
+    if (DEBUG) {
+        console.error(`[ekkOS] → ${method} ${endpoint}`);
+    }
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ method, params: params || {} }),
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (DEBUG) {
+        console.error(`[ekkOS] ← ${method} OK`);
+    }
+    return data;
+}
+// Create MCP server
+const server = new Server({
+    name: 'ekkos-memory',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+    },
+});
+// List tools - proxy to gateway
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const result = await callGateway('tools/list', 'tools/list');
+    return result;
+});
+// Call tool - proxy to gateway
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const result = await callGateway('tools/call', 'tools/call', {
+        name: request.params.name,
+        arguments: request.params.arguments,
+    });
+    return result;
+});
+// List resources - proxy to gateway
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    const result = await callGateway('resources/list', 'resources/list');
+    return result;
+});
+// Read resource - proxy to gateway
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const result = await callGateway('resources/read', 'resources/read', {
+        uri: request.params.uri,
+    });
+    return result;
+});
+// List prompts - proxy to gateway
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    const result = await callGateway('prompts/list', 'prompts/list');
+    return result;
+});
+// Get prompt - proxy to gateway
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const result = await callGateway('prompts/get', 'prompts/get', {
+        name: request.params.name,
+        arguments: request.params.arguments,
+    });
+    return result;
+});
+// Error handling
+server.onerror = (error) => {
+    console.error('[ekkOS] Server error:', error);
+};
+process.on('SIGINT', async () => {
+    if (DEBUG) {
+        console.error('[ekkOS] Shutting down...');
+    }
+    await server.close();
+    process.exit(0);
+});
+// Start server
+async function main() {
+    if (DEBUG) {
+        console.error('[ekkOS] Starting MCP proxy to ekkOS Memory...');
+        console.error(`[ekkOS] Gateway: ${EKKOS_MCP_URL}`);
+        console.error(`[ekkOS] User ID: ${EKKOS_USER_ID || '(not set)'}`);
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    if (DEBUG) {
+        console.error('[ekkOS] ✓ Ready! Your AI can now access ekkOS memory.');
+    }
+}
+main().catch((error) => {
+    console.error('[ekkOS] Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ekkos/mcp-server",
+  "version": "1.0.0",
+  "description": "ekkOS Memory MCP Server - stdio bridge to cloud memory substrate",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ekkos-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ekkos",
+    "mcp",
+    "memory",
+    "ai",
+    "claude",
+    "anthropic",
+    "model-context-protocol"
+  ],
+  "author": "ekkOS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ekkos-ai/ekkos.git",
+    "directory": "packages/ekkos-mcp-server"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.5",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}