@cybermem/mcp 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @cybermem/mcp
+
+Official TypeScript MCP Server for CyberMem.
+
+## Configuration
+
+### Option A: Local (Standard)
+If you are running CyberMem locally on your machine, use `npx` to spawn the MCP server. It will bridge the connection to your local Docker instance.
+
+**Claude Desktop Config (`~/Library/Application Support/Claude/claude_desktop_config.json`):**
+```json
+{
+  "mcpServers": {
+    "cybermem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@cybermem/mcp"
+      ],
+      "env": {
+        "CYBERMEM_URL": "http://localhost:8080/memory",
+        "CYBERMEM_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Option B: Remote (RPi / Cloud)
+If you have deployed CyberMem to a Raspberry Pi or Cloud VPS, **do not use npx**. Instead, connect directly to the remote SSE endpoint.
+
+**Claude Desktop Config:**
+```json
+{
+  "mcpServers": {
+    "cybermem-remote": {
+      "url": "http://<your-rpi-ip>:8080/mcp",
+      "transport": "sse",
+      "headers": {
+        "x-api-key": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+- `CYBERMEM_URL`: URL to the OpenMemory API (default: `http://localhost:8080/memory`)
+- `CYBERMEM_API_KEY`: Your API Key (found in `~/.cybermem/.env`)

package/dist/index.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const axios_1 = __importDefault(require("axios"));
+const dotenv_1 = __importDefault(require("dotenv"));
+dotenv_1.default.config();
+const API_URL = process.env.CYBERMEM_URL || "http://localhost:8080/memory";
+const API_KEY = process.env.CYBERMEM_API_KEY || "dev-secret-key";
+const server = new index_js_1.Server({
+    name: "cybermem-mcp",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+const tools = [
+    {
+        name: "add_memory",
+        description: "Store a new memory in CyberMem",
+        inputSchema: {
+            type: "object",
+            properties: {
+                content: { type: "string" },
+                user_id: { type: "string" },
+                tags: { type: "array", items: { type: "string" } },
+            },
+            required: ["content"],
+        },
+    },
+    {
+        name: "query_memory",
+        description: "Search for relevant memories",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string" },
+                k: { type: "number", default: 5 },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "list_memories",
+        description: "List recent memories",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", default: 10 },
+            },
+        },
+    }
+];
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools,
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "add_memory": {
+                const response = await axios_1.default.post(`${API_URL}/add`, args, {
+                    headers: { "Authorization": `Bearer ${API_KEY}` }
+                });
+                return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+            }
+            case "query_memory": {
+                const response = await axios_1.default.post(`${API_URL}/query`, args, {
+                    headers: { "Authorization": `Bearer ${API_KEY}` }
+                });
+                return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+            }
+            case "list_memories": {
+                const limit = args?.limit || 10;
+                const response = await axios_1.default.get(`${API_URL}/list?limit=${limit}`, {
+                    headers: { "Authorization": `Bearer ${API_KEY}` }
+                });
+                return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+async function run() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("CyberMem MCP Server running on stdio");
+}
+run().catch((error) => {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@cybermem/mcp",
+  "version": "0.1.0",
+  "description": "CyberMem MCP Server (TypeScript)",
+  "main": "dist/index.js",
+  "bin": {
+    "cybermem-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.6.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.0.0"
+  }
+}

package/requirements.txt

@@ -0,0 +1,2 @@
+mcp>=0.9.0
+httpx>=0.27.0

package/server.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""
+CyberMem MCP Server
+
+MCP server that exposes shared memory functionality to several LLM.
+"""
+
+import asyncio
+import os
+from typing import Any
+
+import httpx
+from mcp import types
+from mcp.server import NotificationOptions, Server
+from mcp.server.models import InitializationOptions
+from mcp.server.stdio import stdio_server
+
+# CyberMem configuration (OpenMemory backend)
+OPENMEMORY_URL = os.getenv("OPENMEMORY_URL", "http://localhost:80")
+CYBERMEM_API_KEY = os.getenv("CYBERMEM_API_KEY", "dev-secret-key")
+
+# Create MCP server instance
+server = Server("cybermem")
+
+
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+    """List available memory management tools."""
+    return [
+        types.Tool(
+            name="add_memory",
+            description="Store information in long-term memory. Use this to remember important facts, decisions, or context for future conversations.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "content": {
+                        "type": "string",
+                        "description": "The information to remember (text content)",
+                    },
+                    "metadata": {
+                        "type": "object",
+                        "description": "Optional metadata (tags, category, importance, etc.)",
+                        "additionalProperties": True,
+                    },
+                },
+                "required": ["content"],
+            },
+        ),
+        types.Tool(
+            name="search_memory",
+            description="Search through stored memories to find relevant information. Use this to recall past conversations, decisions, or facts.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "What to search for (semantic search query)",
+                    },
+                    "limit": {
+                        "type": "number",
+                        "description": "Maximum number of results (default: 5)",
+                        "default": 5,
+                    },
+                },
+                "required": ["query"],
+            },
+        ),
+        types.Tool(
+            name="list_memories",
+            description="List recent memories stored in the system. Useful for browsing what has been remembered.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "limit": {
+                        "type": "number",
+                        "description": "Maximum number of memories to retrieve (default: 10)",
+                        "default": 10,
+                    }
+                },
+            },
+        ),
+        types.Tool(
+            name="delete_memory",
+            description="Delete a specific memory by its ID. Use this to remove outdated or incorrect information.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "memory_id": {
+                        "type": "string",
+                        "description": "The UUID of the memory to delete",
+                    }
+                },
+                "required": ["memory_id"],
+            },
+        ),
+        types.Tool(
+            name="update_memory",
+            description="Update an existing memory's content, tags, or metadata.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "memory_id": {
+                        "type": "string",
+                        "description": "The UUID of the memory to update",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "New content for the memory (optional)",
+                    },
+                    "tags": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "New tags for the memory (optional)",
+                    },
+                    "metadata": {
+                        "type": "object",
+                        "description": "New metadata for the memory (optional)",
+                        "additionalProperties": True,
+                    },
+                },
+                "required": ["memory_id"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def handle_call_tool(
+    name: str, arguments: dict[str, Any]
+) -> list[types.TextContent]:
+    """Handle tool execution requests."""
+
+    # Get client info from MCP context
+    client_name, client_version = "unknown", "unknown"
+    try:
+        ctx = server.request_context
+        if hasattr(ctx, "session"):
+            session = ctx.session
+            if hasattr(session, "_client_params"):
+                client_params = session._client_params
+                if client_params and hasattr(client_params, "clientInfo"):
+                    client_info = client_params.clientInfo
+                    client_name = client_info.name or "unknown"
+                    client_version = client_info.version or "unknown"
+    except Exception:
+        pass
+
+    headers = {
+        "Authorization": f"Bearer {CYBERMEM_API_KEY}",
+        "Content-Type": "application/json",
+        "X-Client-Name": client_name,
+        "X-Client-Version": client_version,
+    }
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            if name == "add_memory":
+                # Store memory in OpenMemory
+                content = arguments.get("content")
+                metadata = arguments.get("metadata", {})
+
+                response = await client.post(
+                    f"{OPENMEMORY_URL}/memory/add",
+                    json={"content": content, "metadata": metadata},
+                    headers=headers,
+                )
+                response.raise_for_status()
+                result = response.json()
+
+                return [
+                    types.TextContent(
+                        type="text",
+                        text=f"✅ Memory stored successfully!\n\nID: {result.get('id')}\nChunks: {result.get('chunks')}\nSectors: {', '.join(result.get('sectors', []))}",
+                    )
+                ]
+
+            elif name == "search_memory":
+                # Search memories in OpenMemory
+                query = arguments.get("query")
+                limit = arguments.get("limit", 5)
+
+                response = await client.post(
+                    f"{OPENMEMORY_URL}/memory/query",
+                    json={"query": query, "k": limit},
+                    headers=headers,
+                )
+                response.raise_for_status()
+                data = response.json()
+                matches = data.get("matches", [])
+
+                if not matches:
+                    return [
+                        types.TextContent(
+                            type="text",
+                            text="🔍 No memories found matching your query.",
+                        )
+                    ]
+
+                # Format search results
+                formatted_results = []
+                for i, memory in enumerate(matches, 1):
+                    content = memory.get("content", "")
+                    score = memory.get("score", 0)
+                    sector = memory.get("primary_sector", "")
+
+                    formatted_results.append(
+                        f"**Result {i}** (score: {score:.2f}, sector: {sector})\n{content}\n"
+                    )
+
+                return [
+                    types.TextContent(
+                        type="text",
+                        text=f"🔍 Found {len(matches)} memories:\n\n"
+                        + "\n".join(formatted_results),
+                    )
+                ]
+
+            elif name == "list_memories":
+                # List recent memories
+                limit = arguments.get("limit", 10)
+
+                # Note: OpenMemory doesn't have a /list endpoint yet,
+                # so we'll do a broad query with generic term
+                response = await client.post(
+                    f"{OPENMEMORY_URL}/memory/query",
+                    json={"query": "memory context", "k": limit},
+                    headers=headers,
+                )
+                response.raise_for_status()
+                data = response.json()
+                matches = data.get("matches", [])
+
+                if not matches:
+                    return [
+                        types.TextContent(
+                            type="text", text="📋 No memories stored yet."
+                        )
+                    ]
+
+                # Format list
+                formatted_list = []
+                for i, memory in enumerate(matches, 1):
+                    content = memory.get("content", "")
+                    sector = memory.get("primary_sector", "")
+                    # Truncate long content
+                    if len(content) > 100:
+                        content = content[:97] + "..."
+                    formatted_list.append(f"{i}. [{sector}] {content}")
+
+                return [
+                    types.TextContent(
+                        type="text",
+                        text=f"📋 Recent memories ({len(matches)}):\n\n"
+                        + "\n".join(formatted_list),
+                    )
+                ]
+
+            elif name == "delete_memory":
+                # Delete memory by ID
+                memory_id = arguments.get("memory_id")
+
+                try:
+                    response = await client.delete(
+                        f"{OPENMEMORY_URL}/memory/{memory_id}", headers=headers
+                    )
+                    response.raise_for_status()
+                    result = response.json()
+                    status = result.get("ok", "deleted")
+                except httpx.HTTPStatusError as e:
+                    # Workaround: OpenMemory returns 500 on successful delete (bug in OpenMemory)
+                    # We'll treat it as success since the memory is actually deleted
+                    if e.response.status_code == 500:
+                        status = "deleted (500 ignored - OpenMemory bug)"
+                    else:
+                        raise
+
+                return [
+                    types.TextContent(
+                        type="text",
+                        text=f"🗑️ Memory deleted successfully!\n\nID: {memory_id}\nStatus: {status}",
+                    )
+                ]
+
+            elif name == "update_memory":
+                # Update memory by ID
+                memory_id = arguments.get("memory_id")
+                content = arguments.get("content")
+                tags = arguments.get("tags")
+                metadata = arguments.get("metadata")
+
+                payload = {}
+                if content:
+                    payload["content"] = content
+                if tags:
+                    payload["tags"] = tags
+                if metadata:
+                    payload["metadata"] = metadata
+
+                response = await client.patch(
+                    f"{OPENMEMORY_URL}/memory/{memory_id}",
+                    json=payload,
+                    headers=headers,
+                )
+                response.raise_for_status()
+                result = response.json()
+
+                return [
+                    types.TextContent(
+                        type="text",
+                        text=f"✏️ Memory updated successfully!\n\nID: {result.get('id', memory_id)}",
+                    )
+                ]
+
+            else:
+                raise ValueError(f"Unknown tool: {name}")
+
+        except httpx.HTTPStatusError as e:
+            return [
+                types.TextContent(
+                    type="text",
+                    text=f"❌ API Error: {e.response.status_code}\n{e.response.text}",
+                )
+            ]
+        except Exception as e:
+            return [types.TextContent(type="text", text=f"❌ Error: {str(e)}")]
+
+
+async def main():
+    """Run the MCP server."""
+
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="cybermem",
+                server_version="0.1.0",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/src/index.ts

@@ -0,0 +1,114 @@
+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 axios from "axios";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+const API_URL = process.env.CYBERMEM_URL || "http://localhost:8080/memory";
+const API_KEY = process.env.CYBERMEM_API_KEY || "dev-secret-key";
+
+const server = new Server(
+  {
+    name: "cybermem-mcp",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+const tools: Tool[] = [
+  {
+    name: "add_memory",
+    description: "Store a new memory in CyberMem",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: { type: "string" },
+        user_id: { type: "string" },
+        tags: { type: "array", items: { type: "string" } },
+      },
+      required: ["content"],
+    },
+  },
+  {
+    name: "query_memory",
+    description: "Search for relevant memories",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        k: { type: "number", default: 5 },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "list_memories",
+    description: "List recent memories",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "number", default: 10 },
+      },
+    },
+  }
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "add_memory": {
+        const response = await axios.post(`${API_URL}/add`, args, {
+          headers: { "Authorization": `Bearer ${API_KEY}` }
+        });
+        return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+      }
+      case "query_memory": {
+        const response = await axios.post(`${API_URL}/query`, args, {
+          headers: { "Authorization": `Bearer ${API_KEY}` }
+        });
+        return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+      }
+      case "list_memories": {
+        const limit = args?.limit || 10;
+        const response = await axios.get(`${API_URL}/list?limit=${limit}`, {
+          headers: { "Authorization": `Bearer ${API_KEY}` }
+        });
+        return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+      }
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error: any) {
+    return {
+      content: [{ type: "text", text: `Error: ${error.message}` }],
+      isError: true,
+    };
+  }
+});
+
+async function run() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("CyberMem MCP Server running on stdio");
+}
+
+run().catch((error) => {
+  console.error("Fatal error running server:", error);
+  process.exit(1);
+});

package/test_mcp.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+Test script for OpenMemory MCP Server
+
+Demonstrates MCP server functionality by simulating tool calls.
+"""
+
+import asyncio
+import httpx
+import json
+
+
+OPENMEMORY_URL = "http://localhost/memory"
+OPENMEMORY_API_KEY = "dev-secret-key"
+
+
+async def test_add_memory():
+    """Test adding a memory."""
+    print("\n🧪 Test 1: Adding memory...")
+
+    headers = {
+        "Authorization": f"Bearer {OPENMEMORY_API_KEY}",
+        "Content-Type": "application/json"
+    }
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        response = await client.post(
+            f"{OPENMEMORY_URL}/add",
+            json={
+                "content": "MCP server test: Claude Code can now remember conversations and context",
+                "metadata": {
+                    "source": "mcp_test",
+                    "category": "integration_test",
+                    "timestamp": "2025-11-30"
+                }
+            },
+            headers=headers
+        )
+
+        if response.status_code == 200:
+            result = response.json()
+            print(f"✅ Memory added successfully!")
+            print(f"   ID: {result.get('id')}")
+            print(f"   Chunks: {result.get('chunks')}")
+            print(f"   Sectors: {', '.join(result.get('sectors', []))}")
+            return result.get('id')
+        else:
+            print(f"❌ Failed: {response.status_code} - {response.text}")
+            return None
+
+
+async def test_search_memory():
+    """Test searching memories."""
+    print("\n🧪 Test 2: Searching memory...")
+
+    headers = {
+        "Authorization": f"Bearer {OPENMEMORY_API_KEY}",
+        "Content-Type": "application/json"
+    }
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        response = await client.post(
+            f"{OPENMEMORY_URL}/query",
+            json={
+                "query": "Claude Code remember conversations",
+                "k": 3
+            },
+            headers=headers
+        )
+
+        if response.status_code == 200:
+            data = response.json()
+            matches = data.get("matches", [])
+            print(f"✅ Found {len(matches)} memories:")
+            for i, memory in enumerate(matches, 1):
+                content = memory.get("content", "")
+                score = memory.get("score", 0)
+                sector = memory.get("primary_sector", "")
+                print(f"\n   Result {i} (score: {score:.2f}, sector: {sector}):")
+                print(f"   {content[:100]}...")
+        else:
+            print(f"❌ Failed: {response.status_code} - {response.text}")
+
+
+async def test_mcp_integration():
+    """Run full MCP integration test."""
+    print("=" * 60)
+    print("OpenMemory MCP Server - Integration Test")
+    print("=" * 60)
+
+    # Test 1: Add memory
+    memory_id = await test_add_memory()
+
+    # Wait a bit for indexing
+    await asyncio.sleep(2)
+
+    # Test 2: Search memory
+    await test_search_memory()
+
+    print("\n" + "=" * 60)
+    print("✅ Integration test completed!")
+    print("=" * 60)
+    print("\nNext steps:")
+    print("1. Restart Claude Code to load the MCP server")
+    print("2. Try asking Claude Code to remember something")
+    print("3. Check Grafana dashboard for audit trail")
+    print("   → http://localhost:3000/d/cybermem-memory")
+
+
+if __name__ == "__main__":
+    asyncio.run(test_mcp_integration())

package/tsconfig.json

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