memdata-mcp 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# memdata-mcp
+
+MCP server for [MemData](https://memdata.ai) - persistent memory for AI agents.
+
+Give Claude, Cursor, or any MCP-compatible AI long-term memory across conversations.
+
+## Quick Start
+
+### 1. Get your API key
+
+Create an API key at [memdata.ai/dashboard/api-keys](https://memdata.ai/dashboard/api-keys)
+
+### 2. Add to your MCP config
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "memdata": {
+      "command": "npx",
+      "args": ["memdata-mcp"],
+      "env": {
+        "MEMDATA_API_KEY": "md_your_key"
+      }
+    }
+  }
+}
+```
+
+**Claude Code** (`~/.claude.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "memdata": {
+      "command": "npx",
+      "args": ["memdata-mcp"],
+      "env": {
+        "MEMDATA_API_KEY": "md_your_key"
+      }
+    }
+  }
+}
+```
+
+**Cursor** (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "memdata": {
+      "command": "npx",
+      "args": ["memdata-mcp"],
+      "env": {
+        "MEMDATA_API_KEY": "md_your_key"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart your client
+
+You should now see `memdata_ingest` and `memdata_query` tools available.
+
+## Tools
+
+### `memdata_ingest`
+
+Store text in long-term memory.
+
+```
+"Remember that we decided to use PostgreSQL for the new project."
+```
+
+**Parameters:**
+- `content` (string) - Text to store
+- `name` (string) - Source identifier (e.g., "meeting-notes-jan-29")
+
+### `memdata_query`
+
+Search memory with natural language.
+
+```
+"What database did we choose?"
+```
+
+**Parameters:**
+- `query` (string) - Natural language search
+- `limit` (number, optional) - Max results (default: 5)
+
+## How it works
+
+1. **Ingest**: Text is chunked, embedded (OpenAI text-embedding-3-small), and stored
+2. **Query**: Your question is embedded and matched against stored memories using vector similarity
+3. **Results**: Returns semantically similar content with similarity scores
+
+Scores of 30-50% are typical for good matches. Semantic search finds meaning, not keywords.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MEMDATA_API_KEY` | Yes | Your API key from memdata.ai |
+| `MEMDATA_API_URL` | No | API URL (default: https://memdata.ai) |
+
+## Links
+
+- [MemData](https://memdata.ai) - Main site
+- [Dashboard](https://memdata.ai/dashboard) - Manage your memory
+- [Docs](https://memdata.ai/docs) - Full documentation
+- [GitHub](https://github.com/thelabvenice/mem-data) - Source code
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * MemData MCP Server
+ *
+ * A thin client that exposes memory ingestion and query tools via MCP.
+ * Connects to the hosted MemData API (memdata.ai).
+ *
+ * Usage:
+ *   npx memdata-mcp
+ *
+ * Environment Variables:
+ *   MEMDATA_API_KEY - Your MemData API key (required, starts with md_)
+ *   MEMDATA_API_URL - API URL (optional, defaults to https://memdata.ai)
+ */
+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":";AACA;;;;;;;;;;;;GAYG"}

package/dist/index.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * MemData MCP Server
+ *
+ * A thin client that exposes memory ingestion and query tools via MCP.
+ * Connects to the hosted MemData API (memdata.ai).
+ *
+ * Usage:
+ *   npx memdata-mcp
+ *
+ * Environment Variables:
+ *   MEMDATA_API_KEY - Your MemData API key (required, starts with md_)
+ *   MEMDATA_API_URL - API URL (optional, defaults to https://memdata.ai)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+// Configuration
+const MEMDATA_API_KEY = process.env.MEMDATA_API_KEY;
+const MEMDATA_API_URL = process.env.MEMDATA_API_URL || 'https://memdata.ai';
+if (!MEMDATA_API_KEY) {
+    console.error('Error: MEMDATA_API_KEY environment variable is required');
+    console.error('');
+    console.error('Get your API key at: https://memdata.ai/dashboard/api-keys');
+    console.error('');
+    console.error('Then add to your MCP config:');
+    console.error(JSON.stringify({
+        mcpServers: {
+            memdata: {
+                command: 'npx',
+                args: ['memdata-mcp'],
+                env: {
+                    MEMDATA_API_KEY: 'md_your_key_here'
+                }
+            }
+        }
+    }, null, 2));
+    process.exit(1);
+}
+/**
+ * Call the MemData API
+ */
+async function callAPI(endpoint, body) {
+    const response = await fetch(`${MEMDATA_API_URL}${endpoint}`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${MEMDATA_API_KEY}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`API error (${response.status}): ${error}`);
+    }
+    return response.json();
+}
+/**
+ * Ingest text content into memory
+ */
+async function ingestContent(content, name) {
+    const result = (await callAPI('/api/memdata/ingest', {
+        content,
+        sourceName: name,
+    }));
+    if (!result.success) {
+        return { success: false, message: result.error || 'Unknown error' };
+    }
+    return {
+        success: true,
+        artifactId: result.artifact_id,
+        chunkCount: result.chunk_count,
+    };
+}
+/**
+ * Query memory for relevant context
+ */
+async function queryMemory(query, limit = 5) {
+    const result = (await callAPI('/api/memdata/query', {
+        query,
+        limit,
+    }));
+    if (!result.success) {
+        return { success: false, message: result.error || 'Unknown error' };
+    }
+    return {
+        success: true,
+        results: (result.results || []).map((r) => ({
+            text: r.chunk_text,
+            source: r.source_name,
+            score: Math.round(r.similarity_score * 1000) / 1000,
+        })),
+    };
+}
+// Create MCP server
+const server = new mcp_js_1.McpServer({
+    name: 'memdata',
+    version: '1.0.0',
+});
+// Register ingest tool
+server.tool('memdata_ingest', 'Ingest text content into long-term memory for later retrieval. Use this to store important information, notes, decisions, or context that should be remembered across conversations.', {
+    content: zod_1.z.string().describe('Text content to store in memory'),
+    name: zod_1.z.string().describe('Source name/identifier for this memory (e.g., "meeting-notes-2024-01-15", "project-decision", "user-preference")'),
+}, async ({ content, name }) => {
+    try {
+        const result = await ingestContent(content, name);
+        if (!result.success) {
+            return {
+                content: [{ type: 'text', text: `Failed to ingest: ${result.message}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Successfully stored in memory:\n- Artifact ID: ${result.artifactId}\n- Chunks created: ${result.chunkCount}\n- Source: ${name}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `Failed to ingest content: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// Register query tool
+server.tool('memdata_query', 'Search memory for relevant context based on a natural language query. Returns the most semantically similar stored content with similarity scores.', {
+    query: zod_1.z.string().describe('Natural language search query (e.g., "What did we decide about the database?", "meeting notes from last week")'),
+    limit: zod_1.z.number().optional().default(5).describe('Maximum number of results to return (default: 5, max: 20)'),
+}, async ({ query, limit }) => {
+    try {
+        const result = await queryMemory(query, Math.min(limit, 20));
+        if (!result.success) {
+            return {
+                content: [{ type: 'text', text: `Failed to query: ${result.message}` }],
+                isError: true,
+            };
+        }
+        if (!result.results || result.results.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No relevant memories found for this query.' }],
+            };
+        }
+        const formatted = result.results
+            .map((r, i) => `[${i + 1}] (${(r.score * 100).toFixed(1)}% match) ${r.source}\n${r.text}`)
+            .join('\n\n---\n\n');
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${result.results.length} relevant memories:\n\n${formatted}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `Failed to query memory: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('MemData MCP server running');
+    console.error(`API: ${MEMDATA_API_URL}`);
+}
+main().catch((error) => {
+    console.error('Failed to start MCP server:', 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,46 @@
+{
+  "name": "memdata-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for MemData - persistent memory for AI agents",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "memory",
+    "semantic-search",
+    "embeddings"
+  ],
+  "author": "The Lab Venice",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thelabvenice/mem-data.git",
+    "directory": "packages/memdata-mcp"
+  },
+  "homepage": "https://memdata.ai",
+  "bin": {
+    "memdata-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}