shabti 2.0.0 → 2.2.0

package/README.md

@@ -117,6 +117,53 @@ you> /help
 
 Requires `OPENAI_API_KEY` in `.env` for chat functionality. Memory commands (`/remember`, `/recall`) work with the local Qdrant engine.
 
+## MCP Server
+
+shabti includes an MCP (Model Context Protocol) server for integration with Claude Code, Cursor, and other MCP-compatible tools.
+
+```bash
+# Start the MCP server (stdio transport)
+npx shabti-mcp
+```
+
+### Claude Code configuration
+
+Generate the MCP settings JSON:
+
+```bash
+shabti mcp-config
+```
+
+Or manually add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "shabti-memory": {
+      "command": "npx",
+      "args": ["shabti-mcp"]
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool            | Description                            |
+| --------------- | -------------------------------------- |
+| `memory_store`  | Store a memory entry                   |
+| `memory_search` | Search memories by semantic similarity |
+| `memory_delete` | Delete a memory entry by ID            |
+| `memory_list`   | List recent memory entries             |
+| `memory_status` | Get engine status                      |
+
+### Available resources
+
+| URI               | Description                  |
+| ----------------- | ---------------------------- |
+| `shabti://status` | Engine status and statistics |
+| `shabti://config` | Current configuration        |
+
 ## Node.js API
 
 ```javascript

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "shabti",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Agent Memory OS — semantic memory for AI agents",
   "type": "module",
   "main": "native.cjs",
   "types": "native.d.ts",
   "bin": {
-    "shabti": "src/index.js"
+    "shabti": "src/index.js",
+    "shabti-mcp": "src/mcp/server.js"
   },
   "files": [
     "src/",
@@ -42,6 +43,7 @@
     "vector-database",
     "qdrant",
     "embeddings",
+    "mcp",
     "cli"
   ],
   "author": "Kaga Hinata",

package/src/index.js

@@ -78,6 +78,22 @@ function buildProgram() {
   registerSpin(program);
   registerStatus(program);
   registerStore(program);
+
+  program
+    .command("mcp-config")
+    .description("Print MCP server configuration JSON for Claude Code / Cursor")
+    .action(() => {
+      const config = {
+        mcpServers: {
+          "shabti-memory": {
+            command: "npx",
+            args: ["shabti-mcp"],
+          },
+        },
+      };
+      console.log(JSON.stringify(config, null, 2));
+    });
+
   return program;
 }
 

package/src/mcp/server.js

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+import { createInterface } from "readline";
+import { createEngine, loadConfig } from "../core/engine.js";
+
+const SERVER_INFO = {
+  name: "shabti-memory",
+  version: "2.0.0",
+};
+
+const TOOLS = [
+  {
+    name: "memory_store",
+    description: "Store a memory entry in shabti",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: { type: "string", description: "The text content to store" },
+        namespace: {
+          type: "string",
+          description: "Target namespace (default: 'default')",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tags to associate with the memory",
+        },
+      },
+      required: ["content"],
+    },
+  },
+  {
+    name: "memory_search",
+    description: "Search stored memories by semantic similarity",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query text" },
+        limit: {
+          type: "integer",
+          description: "Maximum number of results (default: 10)",
+        },
+        namespace: { type: "string", description: "Namespace to search within" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "memory_delete",
+    description: "Delete a memory entry by ID",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "UUID of the memory entry to delete" },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "memory_list",
+    description: "List recent memory entries",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "integer",
+          description: "Maximum number of entries to return (default: 10)",
+        },
+        namespace: { type: "string", description: "Filter by namespace" },
+      },
+    },
+  },
+  {
+    name: "memory_status",
+    description: "Get the current status of the memory engine",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+];
+
+const RESOURCES = [
+  {
+    uri: "shabti://status",
+    name: "Engine status",
+    description: "Current shabti engine status and statistics",
+    mimeType: "application/json",
+  },
+  {
+    uri: "shabti://config",
+    name: "Engine configuration",
+    description: "Current engine configuration",
+    mimeType: "application/json",
+  },
+];
+
+let engine = null;
+let engineInitAttempted = false;
+
+function initEngine() {
+  if (engine) return engine;
+  if (engineInitAttempted) return null;
+  engineInitAttempted = true;
+  try {
+    engine = createEngine();
+  } catch {
+    // engine stays null — tools will return errors
+  }
+  return engine;
+}
+
+function respond(id, result) {
+  const msg = JSON.stringify({ jsonrpc: "2.0", id, result });
+  process.stdout.write(msg + "\n");
+}
+
+function respondError(id, code, message) {
+  const msg = JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
+  process.stdout.write(msg + "\n");
+}
+
+function handleInitialize(id) {
+  respond(id, {
+    protocolVersion: "2024-11-05",
+    serverInfo: SERVER_INFO,
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  });
+}
+
+function handleToolsList(id) {
+  respond(id, { tools: TOOLS });
+}
+
+function handleResourcesList(id) {
+  respond(id, { resources: RESOURCES });
+}
+
+async function handleToolsCall(id, params) {
+  const { name, arguments: args } = params;
+
+  const eng = initEngine();
+
+  if (name === "memory_status") {
+    if (!eng) {
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { status: "unavailable", entry_count: 0, model_id: "unknown" },
+              null,
+              2,
+            ),
+          },
+        ],
+      });
+    }
+    const status = eng.status();
+    return respond(id, {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              status: "ok",
+              entry_count: status.entryCount,
+              tier: status.tier,
+              model_id: status.modelId,
+              qdrant_url: status.qdrantUrl,
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    });
+  }
+
+  if (name === "memory_store") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    const content = args?.content;
+    if (!content) {
+      return respondError(id, -32602, "Missing required parameter: content");
+    }
+    try {
+      const opts = {};
+      if (args.namespace) opts.namespace = args.namespace;
+      if (args.tags) opts.tags = args.tags;
+      const result = await eng.store(content, opts);
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { status: result.status, id: result.id || result.existingId },
+              null,
+              2,
+            ),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
+  if (name === "memory_search") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    const query = args?.query;
+    if (!query) {
+      return respondError(id, -32602, "Missing required parameter: query");
+    }
+    try {
+      const limit = args.limit || 10;
+      const queryObj = { text: query, limit };
+      if (args.namespace) queryObj.namespace = args.namespace;
+      const results = await eng.executeQuery(queryObj);
+      const formatted = results.map((r) => ({
+        content: r.content,
+        score: r.score,
+        id: r.id,
+        namespace: r.namespace,
+      }));
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ query, results: formatted }, null, 2),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
+  if (name === "memory_delete") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    const entryId = args?.id;
+    if (!entryId) {
+      return respondError(id, -32602, "Missing required parameter: id");
+    }
+    try {
+      await eng.delete(entryId);
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ deleted: true, id: entryId }, null, 2),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
+  if (name === "memory_list") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    try {
+      const limit = args?.limit || 10;
+      const queryObj = { text: "*", limit };
+      if (args?.namespace) queryObj.namespace = args.namespace;
+      const results = await eng.executeQuery(queryObj);
+      const entries = results.map((r) => ({
+        id: r.id,
+        content: r.content,
+        score: r.score,
+        namespace: r.namespace,
+        createdAt: r.createdAt,
+      }));
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ entries, count: entries.length }, null, 2),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
+  respondError(id, -32601, `Unknown tool: ${name}`);
+}
+
+function handleResourcesRead(id, params) {
+  const { uri } = params;
+  const eng = initEngine();
+
+  if (uri === "shabti://status") {
+    if (!eng) {
+      return respond(id, {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify({ status: "unavailable", entry_count: 0 }),
+          },
+        ],
+      });
+    }
+    const status = eng.status();
+    return respond(id, {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify({
+            status: "ok",
+            entry_count: status.entryCount,
+            tier: status.tier,
+            model_id: status.modelId,
+          }),
+        },
+      ],
+    });
+  }
+
+  if (uri === "shabti://config") {
+    const config = loadConfig();
+    return respond(id, {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(config),
+        },
+      ],
+    });
+  }
+
+  respondError(id, -32602, `Unknown resource: ${uri}`);
+}
+
+async function handleRequest(line) {
+  let req;
+  try {
+    req = JSON.parse(line);
+  } catch {
+    return respondError(null, -32700, "Parse error");
+  }
+
+  const { id, method, params } = req;
+
+  switch (method) {
+    case "initialize":
+      return handleInitialize(id);
+    case "notifications/initialized":
+      return; // no response needed for notifications
+    case "tools/list":
+      return handleToolsList(id);
+    case "tools/call":
+      return handleToolsCall(id, params || {});
+    case "resources/list":
+      return handleResourcesList(id);
+    case "resources/read":
+      return handleResourcesRead(id, params || {});
+    default:
+      return respondError(id, -32601, "Method not found");
+  }
+}
+
+// stdio transport: read newline-delimited JSON from stdin
+const rl = createInterface({ input: process.stdin, terminal: false });
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (trimmed) handleRequest(trimmed);
+});
+rl.on("close", () => process.exit(0));