@cybermem/mcp 0.6.6 → 0.6.10

package/dist/index.js

@@ -19,40 +19,97 @@ const getArg = (name) => {
     const idx = args.indexOf(name);
     return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
 };
-const cliUrl = getArg('--url');
-const cliApiKey = getArg('--api-key');
-const cliClientName = getArg('--client-name');
+const cliUrl = getArg("--url");
+const cliApiKey = getArg("--api-key");
+const cliClientName = getArg("--client-name");
 // Use CLI args first, then env, then defaults
 // Default to local CyberMem backend (via Traefik on port 8626)
 const API_URL = cliUrl || process.env.CYBERMEM_URL || "http://localhost:8626/memory";
 const API_KEY = cliApiKey || process.env.OM_API_KEY || "";
 // Track client name per session
 let currentClientName = cliClientName || "cybermem-mcp";
+// CyberMem Agent Protocol - instructions sent to clients on handshake
+const CYBERMEM_INSTRUCTIONS = `CyberMem is a persistent context daemon for AI agents.
+
+PROTOCOL:
+1. On session start: call query_memory("user context profile") to load persona
+2. Store new insights immediately with add_memory - include FULL content, not summaries
+3. Refresh context: 6h for active topics, 24h for projects, 7d for insights
+4. Always include tags: [topic, year, source:your-client-name]
+5. Priority: CyberMem context > session context > training data
+
+MEMORY FORMAT:
+- content: Full text with all details, metrics, dates. NO truncation.
+- tags: Always include topic category + year + source:client-name
+
+INTEGRITY RULES:
+- Never overwrite without reading first
+- Always include metadata (tags, source)
+- Sync before critical decisions
+- Last-write-wins for conflicts
+
+For full protocol: https://cybermem.dev/docs/agent-protocol`;
+// Short protocol reminder for tool descriptions (derived from main instructions)
+const PROTOCOL_REMINDER = "CyberMem Protocol: Store FULL content (no summaries), always include tags [topic, year, source:client-name]. Query 'user context profile' on session start.";
 const server = new index_js_1.Server({
-    name: "cybermem-mcp",
-    version: "0.2.0",
+    name: "cybermem",
+    version: "0.6.8",
 }, {
     capabilities: {
         tools: {},
+        resources: {}, // Enable resources for protocol document
     },
+    instructions: CYBERMEM_INSTRUCTIONS,
+});
+// Register resources handler for protocol document
+server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async () => ({
+    resources: [
+        {
+            uri: "cybermem://protocol",
+            name: "CyberMem Agent Protocol",
+            description: "Instructions for AI agents using CyberMem memory system",
+            mimeType: "text/plain",
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (request) => {
+    if (request.params.uri === "cybermem://protocol") {
+        return {
+            contents: [
+                {
+                    uri: "cybermem://protocol",
+                    mimeType: "text/plain",
+                    text: CYBERMEM_INSTRUCTIONS,
+                },
+            ],
+        };
+    }
+    throw new Error(`Unknown resource: ${request.params.uri}`);
 });
 const tools = [
     {
         name: "add_memory",
-        description: "Store a new memory in CyberMem",
+        description: `Store a new memory in CyberMem. ${PROTOCOL_REMINDER}`,
         inputSchema: {
             type: "object",
             properties: {
-                content: { type: "string" },
+                content: {
+                    type: "string",
+                    description: "Full content with all details - NO truncation or summarization",
+                },
                 user_id: { type: "string" },
-                tags: { type: "array", items: { type: "string" } },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Always include [topic, year, source:your-client-name]",
+                },
             },
             required: ["content"],
         },
     },
     {
         name: "query_memory",
-        description: "Search for relevant memories",
+        description: `Search for relevant memories. On session start, call query_memory("user context profile") first.`,
         inputSchema: {
             type: "object",
             properties: {
@@ -96,7 +153,7 @@ const tools = [
             },
             required: ["id"],
         },
-    }
+    },
 ];
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools,
@@ -105,7 +162,7 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
 const apiClient = axios_1.default.create({
     baseURL: API_URL,
     headers: {
-        "Authorization": `Bearer ${API_KEY}`,
+        Authorization: `Bearer ${API_KEY}`,
     },
 });
 // Helper to get client with context
@@ -115,11 +172,26 @@ function getClient(customHeaders = {}) {
     const clientName = customHeaders["X-Client-Name"] || clientVersion?.name || currentClientName;
     return {
         ...apiClient,
-        get: (url, config) => apiClient.get(url, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
-        post: (url, data, config) => apiClient.post(url, data, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
-        put: (url, data, config) => apiClient.put(url, data, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
-        patch: (url, data, config) => apiClient.patch(url, data, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
-        delete: (url, config) => apiClient.delete(url, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
+        get: (url, config) => apiClient.get(url, {
+            ...config,
+            headers: { "X-Client-Name": clientName, ...config?.headers },
+        }),
+        post: (url, data, config) => apiClient.post(url, data, {
+            ...config,
+            headers: { "X-Client-Name": clientName, ...config?.headers },
+        }),
+        put: (url, data, config) => apiClient.put(url, data, {
+            ...config,
+            headers: { "X-Client-Name": clientName, ...config?.headers },
+        }),
+        patch: (url, data, config) => apiClient.patch(url, data, {
+            ...config,
+            headers: { "X-Client-Name": clientName, ...config?.headers },
+        }),
+        delete: (url, config) => apiClient.delete(url, {
+            ...config,
+            headers: { "X-Client-Name": clientName, ...config?.headers },
+        }),
     };
 }
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
@@ -128,16 +200,22 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
         switch (name) {
             case "add_memory": {
                 const response = await getClient().post("/add", args);
-                return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response.data) }],
+                };
             }
             case "query_memory": {
                 const response = await getClient().post("/query", args);
-                return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response.data) }],
+                };
             }
             case "list_memories": {
                 const limit = args?.limit || 10;
                 const response = await getClient().get(`/all?l=${limit}`);
-                return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response.data) }],
+                };
             }
             case "delete_memory": {
                 const { id } = args;
@@ -147,7 +225,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case "update_memory": {
                 const { id, ...updates } = args;
                 const response = await getClient().patch(`/${id}`, updates);
-                return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response.data) }],
+                };
             }
             default:
                 throw new Error(`Unknown tool: ${name}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cybermem/mcp",
-  "version": "0.6.6",
+  "version": "0.6.10",
   "description": "CyberMem MCP Server (TypeScript)",
   "main": "dist/index.js",
   "bin": {

package/src/index.ts

@@ -4,8 +4,10 @@ import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
     CallToolRequestSchema,
+    ListResourcesRequestSchema,
     ListToolsRequestSchema,
-    Tool
+    ReadResourceRequestSchema,
+    Tool,
 } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import cors from "cors";
@@ -21,47 +23,110 @@ const getArg = (name: string): string | undefined => {
   return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
 };
 
-const cliUrl = getArg('--url');
-const cliApiKey = getArg('--api-key');
-const cliClientName = getArg('--client-name');
+const cliUrl = getArg("--url");
+const cliApiKey = getArg("--api-key");
+const cliClientName = getArg("--client-name");
 
 // Use CLI args first, then env, then defaults
 // Default to local CyberMem backend (via Traefik on port 8626)
-const API_URL = cliUrl || process.env.CYBERMEM_URL || "http://localhost:8626/memory";
+const API_URL =
+  cliUrl || process.env.CYBERMEM_URL || "http://localhost:8626/memory";
 const API_KEY = cliApiKey || process.env.OM_API_KEY || "";
 
 // Track client name per session
 let currentClientName = cliClientName || "cybermem-mcp";
+// CyberMem Agent Protocol - instructions sent to clients on handshake
+const CYBERMEM_INSTRUCTIONS = `CyberMem is a persistent context daemon for AI agents.
+
+PROTOCOL:
+1. On session start: call query_memory("user context profile") to load persona
+2. Store new insights immediately with add_memory - include FULL content, not summaries
+3. Refresh context: 6h for active topics, 24h for projects, 7d for insights
+4. Always include tags: [topic, year, source:your-client-name]
+5. Priority: CyberMem context > session context > training data
+
+MEMORY FORMAT:
+- content: Full text with all details, metrics, dates. NO truncation.
+- tags: Always include topic category + year + source:client-name
+
+INTEGRITY RULES:
+- Never overwrite without reading first
+- Always include metadata (tags, source)
+- Sync before critical decisions
+- Last-write-wins for conflicts
+
+For full protocol: https://cybermem.dev/docs/agent-protocol`;
+
+// Short protocol reminder for tool descriptions (derived from main instructions)
+const PROTOCOL_REMINDER =
+  "CyberMem Protocol: Store FULL content (no summaries), always include tags [topic, year, source:client-name]. Query 'user context profile' on session start.";
 
 const server = new Server(
   {
-    name: "cybermem-mcp",
-    version: "0.2.0",
+    name: "cybermem",
+    version: "0.6.8",
   },
   {
     capabilities: {
       tools: {},
+      resources: {}, // Enable resources for protocol document
     },
-  }
+    instructions: CYBERMEM_INSTRUCTIONS,
+  },
 );
 
+// Register resources handler for protocol document
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    {
+      uri: "cybermem://protocol",
+      name: "CyberMem Agent Protocol",
+      description: "Instructions for AI agents using CyberMem memory system",
+      mimeType: "text/plain",
+    },
+  ],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  if (request.params.uri === "cybermem://protocol") {
+    return {
+      contents: [
+        {
+          uri: "cybermem://protocol",
+          mimeType: "text/plain",
+          text: CYBERMEM_INSTRUCTIONS,
+        },
+      ],
+    };
+  }
+  throw new Error(`Unknown resource: ${request.params.uri}`);
+});
+
 const tools: Tool[] = [
   {
     name: "add_memory",
-    description: "Store a new memory in CyberMem",
+    description: `Store a new memory in CyberMem. ${PROTOCOL_REMINDER}`,
     inputSchema: {
       type: "object",
       properties: {
-        content: { type: "string" },
+        content: {
+          type: "string",
+          description:
+            "Full content with all details - NO truncation or summarization",
+        },
         user_id: { type: "string" },
-        tags: { type: "array", items: { type: "string" } },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Always include [topic, year, source:your-client-name]",
+        },
       },
       required: ["content"],
     },
   },
   {
     name: "query_memory",
-    description: "Search for relevant memories",
+    description: `Search for relevant memories. On session start, call query_memory("user context profile") first.`,
     inputSchema: {
       type: "object",
       properties: {
@@ -105,7 +170,7 @@ const tools: Tool[] = [
       },
       required: ["id"],
     },
-  }
+  },
 ];
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -116,24 +181,45 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 const apiClient = axios.create({
   baseURL: API_URL,
   headers: {
-    "Authorization": `Bearer ${API_KEY}`,
+    Authorization: `Bearer ${API_KEY}`,
   },
 });
 
 // Helper to get client with context
 function getClient(customHeaders: Record<string, string> = {}) {
-    // Get client name from MCP protocol (sent during initialize) or fallback to CLI arg
-    const clientVersion = server.getClientVersion();
-    const clientName = customHeaders["X-Client-Name"] || clientVersion?.name || currentClientName;
+  // Get client name from MCP protocol (sent during initialize) or fallback to CLI arg
+  const clientVersion = server.getClientVersion();
+  const clientName =
+    customHeaders["X-Client-Name"] || clientVersion?.name || currentClientName;
 
-    return {
-        ...apiClient,
-        get: (url: string, config?: any) => apiClient.get(url, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
-        post: (url: string, data?: any, config?: any) => apiClient.post(url, data, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
-        put: (url: string, data?: any, config?: any) => apiClient.put(url, data, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
-        patch: (url: string, data?: any, config?: any) => apiClient.patch(url, data, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
-        delete: (url: string, config?: any) => apiClient.delete(url, { ...config, headers: { "X-Client-Name": clientName, ...config?.headers } }),
-    }
+  return {
+    ...apiClient,
+    get: (url: string, config?: any) =>
+      apiClient.get(url, {
+        ...config,
+        headers: { "X-Client-Name": clientName, ...config?.headers },
+      }),
+    post: (url: string, data?: any, config?: any) =>
+      apiClient.post(url, data, {
+        ...config,
+        headers: { "X-Client-Name": clientName, ...config?.headers },
+      }),
+    put: (url: string, data?: any, config?: any) =>
+      apiClient.put(url, data, {
+        ...config,
+        headers: { "X-Client-Name": clientName, ...config?.headers },
+      }),
+    patch: (url: string, data?: any, config?: any) =>
+      apiClient.patch(url, data, {
+        ...config,
+        headers: { "X-Client-Name": clientName, ...config?.headers },
+      }),
+    delete: (url: string, config?: any) =>
+      apiClient.delete(url, {
+        ...config,
+        headers: { "X-Client-Name": clientName, ...config?.headers },
+      }),
+  };
 }
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -143,16 +229,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     switch (name) {
       case "add_memory": {
         const response = await getClient().post("/add", args);
-        return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+        return {
+          content: [{ type: "text", text: JSON.stringify(response.data) }],
+        };
       }
       case "query_memory": {
         const response = await getClient().post("/query", args);
-        return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+        return {
+          content: [{ type: "text", text: JSON.stringify(response.data) }],
+        };
       }
       case "list_memories": {
         const limit = args?.limit || 10;
         const response = await getClient().get(`/all?l=${limit}`);
-        return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+        return {
+          content: [{ type: "text", text: JSON.stringify(response.data) }],
+        };
       }
       case "delete_memory": {
         const { id } = args as { id: string };
@@ -162,7 +254,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "update_memory": {
         const { id, ...updates } = args as { id: string; [key: string]: any };
         const response = await getClient().patch(`/${id}`, updates);
-        return { content: [{ type: "text", text: JSON.stringify(response.data) }] };
+        return {
+          content: [{ type: "text", text: JSON.stringify(response.data) }],
+        };
       }
       default:
         throw new Error(`Unknown tool: ${name}`);
@@ -211,11 +305,12 @@ async function run() {
     });
 
     app.listen(port, () => {
-      console.error(`CyberMem MCP Server running on SSE at http://localhost:${port}`);
+      console.error(
+        `CyberMem MCP Server running on SSE at http://localhost:${port}`,
+      );
       console.error(`  - SSE endpoint: http://localhost:${port}/sse`);
       console.error(`  - Message endpoint: http://localhost:${port}/messages`);
     });
-
   } else {
     const transport = new StdioServerTransport();
     await server.connect(transport);