cf-memory-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 John Lam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# CF Memory MCP
+
+[![npm version](https://badge.fury.io/js/cf-memory-mcp.svg)](https://badge.fury.io/js/cf-memory-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A portable **MCP (Model Context Protocol)** server for AI memory storage using **Cloudflare infrastructure**. This package allows AI coding agents to store, retrieve, and search memories using a production-ready, serverless backend.
+
+## 🚀 Quick Start
+
+```bash
+# Run directly with npx (no installation required)
+npx cf-memory-mcp
+
+# Or install globally
+npm install -g cf-memory-mcp
+cf-memory-mcp
+```
+
+## ✨ Features
+
+- **🌐 Completely Portable** - No local setup required, connects to deployed Cloudflare Worker
+- **⚡ Production Ready** - Uses Cloudflare D1 database and KV storage for reliability
+- **🔧 Zero Configuration** - Works out of the box with any MCP client
+- **🌍 Cross Platform** - Supports Windows, macOS, and Linux
+- **📦 NPX Compatible** - Run instantly without installation
+- **🔒 Secure** - Built on Cloudflare's secure infrastructure
+- **🚄 Fast** - Global edge deployment with KV caching
+
+## 🛠️ Usage
+
+### With MCP Clients
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "cf-memory": {
+      "command": "npx",
+      "args": ["cf-memory-mcp"]
+    }
+  }
+}
+```
+
+### With Augment
+
+Add to your `augment-config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cf-memory": {
+      "command": "npx",
+      "args": ["cf-memory-mcp"]
+    }
+  }
+}
+```
+
+### With Claude Desktop
+
+Add to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "cf-memory": {
+      "command": "npx",
+      "args": ["cf-memory-mcp"]
+    }
+  }
+}
+```
+
+## 🔧 Available Tools
+
+The CF Memory MCP server provides three main tools:
+
+### `store_memory`
+Store a new memory with optional metadata and tags.
+
+**Parameters:**
+- `content` (string, required) - The memory content
+- `tags` (array, optional) - Tags for categorization
+- `importance_score` (number, optional) - Importance score 0-10
+- `metadata` (object, optional) - Additional metadata
+
+### `search_memories`
+Search memories by content and tags.
+
+**Parameters:**
+- `query` (string, optional) - Full-text search query
+- `tags` (array, optional) - Filter by specific tags
+- `limit` (number, optional) - Maximum results (default: 10)
+- `offset` (number, optional) - Results offset (default: 0)
+- `min_importance` (number, optional) - Minimum importance score
+
+### `retrieve_memory`
+Retrieve a specific memory by ID.
+
+**Parameters:**
+- `id` (string, required) - The unique memory ID
+
+## 🌐 Architecture
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
+│   MCP Client    │    │  cf-memory-mcp   │    │  Cloudflare Worker  │
+│   (Augment,     │◄──►│   (npm package)  │◄──►│   (Production API)  │
+│   Claude, etc.) │    │                  │    │                     │
+└─────────────────┘    └──────────────────┘    └─────────────────────┘
+                                                          │
+                                                          ▼
+                                               ┌─────────────────────┐
+                                               │  Cloudflare D1 DB   │
+                                               │  + KV Storage       │
+                                               └─────────────────────┘
+```
+
+## 🔧 Command Line Options
+
+```bash
+# Start the MCP server
+npx cf-memory-mcp
+
+# Show version
+npx cf-memory-mcp --version
+
+# Show help
+npx cf-memory-mcp --help
+
+# Enable debug logging
+DEBUG=1 npx cf-memory-mcp
+```
+
+## 🌍 Environment Variables
+
+- `DEBUG=1` - Enable debug logging
+- `MCP_DEBUG=1` - Enable MCP-specific debug logging
+
+## 📋 Requirements
+
+- **Node.js** 16.0.0 or higher
+- **Internet connection** (connects to Cloudflare Worker)
+- **MCP client** (Augment, Claude Desktop, etc.)
+
+## 🚀 Why CF Memory MCP?
+
+### Traditional Approach ❌
+- Clone repository
+- Set up local database
+- Configure environment variables
+- Manage local server process
+- Handle updates manually
+
+### CF Memory MCP ✅
+- Run `npx cf-memory-mcp`
+- That's it! 🎉
+
+## 🔒 Privacy & Security
+
+- **No local data storage** - All data stored securely in Cloudflare D1
+- **HTTPS encryption** - All communication encrypted in transit
+- **Edge deployment** - Data replicated globally for reliability
+- **No API keys required** - Public read/write access for simplicity
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see the [GitHub repository](https://github.com/johnlam90/cf-memory-mcp) for more information.
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- **GitHub Repository**: https://github.com/johnlam90/cf-memory-mcp
+- **npm Package**: https://www.npmjs.com/package/cf-memory-mcp
+- **Issues**: https://github.com/johnlam90/cf-memory-mcp/issues
+- **MCP Specification**: https://modelcontextprotocol.io/
+
+---
+
+Made with ❤️ by [John Lam](https://github.com/johnlam90)

package/bin/cf-memory-mcp.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+
+/**
+ * CF Memory MCP - Portable MCP Server
+ * 
+ * A portable MCP (Model Context Protocol) server for AI memory storage
+ * using Cloudflare infrastructure. This executable connects to a deployed
+ * Cloudflare Worker to provide memory storage capabilities for AI agents.
+ * 
+ * Usage: npx cf-memory-mcp
+ * 
+ * @author John Lam <johnlam90@gmail.com>
+ * @license MIT
+ */
+
+const https = require('https');
+const { URL } = require('url');
+const os = require('os');
+const process = require('process');
+
+// Configuration
+const SERVER_URL = 'https://cf-memory-mcp.johnlam90.workers.dev/mcp/message';
+const PACKAGE_VERSION = require('../package.json').version;
+const TIMEOUT_MS = 30000;
+const CONNECT_TIMEOUT_MS = 10000;
+
+/**
+ * Cross-platform MCP stdio bridge
+ * Handles communication between MCP clients and the Cloudflare Worker
+ */
+class CFMemoryMCP {
+    constructor() {
+        this.serverUrl = SERVER_URL;
+        this.userAgent = `cf-memory-mcp/${PACKAGE_VERSION} (${os.platform()} ${os.arch()}; Node.js ${process.version})`;
+        
+        // Handle process termination gracefully
+        process.on('SIGINT', () => this.shutdown('SIGINT'));
+        process.on('SIGTERM', () => this.shutdown('SIGTERM'));
+        process.on('uncaughtException', (error) => {
+            this.logError('Uncaught exception:', error);
+            this.shutdown('ERROR');
+        });
+        
+        // Set up stdio encoding
+        process.stdin.setEncoding('utf8');
+        process.stdout.setEncoding('utf8');
+        
+        this.logDebug('CF Memory MCP server starting...');
+        this.logDebug(`Server URL: ${this.serverUrl}`);
+        this.logDebug(`User Agent: ${this.userAgent}`);
+    }
+    
+    /**
+     * Log debug messages to stderr (won't interfere with MCP communication)
+     */
+    logDebug(message) {
+        if (process.env.DEBUG || process.env.MCP_DEBUG) {
+            process.stderr.write(`[DEBUG] ${new Date().toISOString()} ${message}\n`);
+        }
+    }
+    
+    /**
+     * Log error messages to stderr
+     */
+    logError(message, error = null) {
+        const timestamp = new Date().toISOString();
+        process.stderr.write(`[ERROR] ${timestamp} ${message}\n`);
+        if (error && error.stack) {
+            process.stderr.write(`[ERROR] ${timestamp} ${error.stack}\n`);
+        }
+    }
+    
+    /**
+     * Start listening for MCP messages on stdin
+     */
+    async start() {
+        try {
+            // Test connectivity first
+            await this.testConnectivity();
+            
+            this.logDebug('Starting MCP message processing...');
+            await this.processStdio();
+        } catch (error) {
+            this.logError('Failed to start MCP server:', error);
+            process.exit(1);
+        }
+    }
+    
+    /**
+     * Test connectivity to the Cloudflare Worker
+     */
+    async testConnectivity() {
+        this.logDebug('Testing connectivity to Cloudflare Worker...');
+        
+        const testMessage = {
+            jsonrpc: '2.0',
+            id: 'connectivity-test',
+            method: 'initialize',
+            params: {
+                protocolVersion: '2024-11-05',
+                capabilities: { tools: {} },
+                clientInfo: {
+                    name: 'cf-memory-mcp',
+                    version: PACKAGE_VERSION
+                }
+            }
+        };
+        
+        try {
+            const response = await this.makeRequest(testMessage);
+            if (response.error) {
+                throw new Error(`Server responded with error: ${response.error.message}`);
+            }
+            this.logDebug('Connectivity test successful');
+        } catch (error) {
+            throw new Error(`Cannot connect to CF Memory server: ${error.message}`);
+        }
+    }
+    
+    /**
+     * Process stdio input/output for MCP communication
+     */
+    async processStdio() {
+        let buffer = '';
+        
+        // Handle stdin data
+        for await (const chunk of process.stdin) {
+            buffer += chunk;
+            
+            // Process complete JSON-RPC messages (one per line)
+            let newlineIndex;
+            while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                
+                if (line) {
+                    await this.handleMessage(line);
+                }
+            }
+        }
+        
+        // Process any remaining buffer content
+        if (buffer.trim()) {
+            await this.handleMessage(buffer.trim());
+        }
+        
+        this.logDebug('Stdin closed, shutting down...');
+    }
+    
+    /**
+     * Handle a single MCP message
+     */
+    async handleMessage(messageStr) {
+        try {
+            const message = JSON.parse(messageStr);
+            this.logDebug(`Processing message: ${message.method} (id: ${message.id})`);
+            
+            const response = await this.makeRequest(message);
+            
+            // Send response to stdout
+            process.stdout.write(JSON.stringify(response) + '\n');
+            
+        } catch (error) {
+            this.logError('Error handling message:', error);
+            
+            // Send error response
+            const errorResponse = {
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32700,
+                    message: 'Parse error',
+                    data: error.message
+                }
+            };
+            process.stdout.write(JSON.stringify(errorResponse) + '\n');
+        }
+    }
+    
+    /**
+     * Make HTTP request to the Cloudflare Worker
+     */
+    async makeRequest(message) {
+        return new Promise((resolve, reject) => {
+            const url = new URL(this.serverUrl);
+            const postData = JSON.stringify(message);
+            
+            const options = {
+                hostname: url.hostname,
+                port: url.port || 443,
+                path: url.pathname,
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json',
+                    'User-Agent': this.userAgent,
+                    'Content-Length': Buffer.byteLength(postData)
+                },
+                timeout: TIMEOUT_MS
+            };
+            
+            const req = https.request(options, (res) => {
+                let body = '';
+                
+                res.on('data', (chunk) => {
+                    body += chunk;
+                });
+                
+                res.on('end', () => {
+                    try {
+                        const response = JSON.parse(body);
+                        resolve(response);
+                    } catch (error) {
+                        resolve({
+                            jsonrpc: '2.0',
+                            id: message.id || null,
+                            error: {
+                                code: -32603,
+                                message: 'Invalid JSON response from server',
+                                data: error.message
+                            }
+                        });
+                    }
+                });
+            });
+            
+            req.on('error', (error) => {
+                resolve({
+                    jsonrpc: '2.0',
+                    id: message.id || null,
+                    error: {
+                        code: -32603,
+                        message: 'Network error',
+                        data: `Failed to connect to ${this.serverUrl}: ${error.message}`
+                    }
+                });
+            });
+            
+            req.on('timeout', () => {
+                req.destroy();
+                resolve({
+                    jsonrpc: '2.0',
+                    id: message.id || null,
+                    error: {
+                        code: -32603,
+                        message: 'Request timeout',
+                        data: `Server did not respond within ${TIMEOUT_MS}ms`
+                    }
+                });
+            });
+            
+            req.write(postData);
+            req.end();
+        });
+    }
+    
+    /**
+     * Graceful shutdown
+     */
+    shutdown(reason = 'UNKNOWN') {
+        this.logDebug(`Shutting down (reason: ${reason})`);
+        process.exit(0);
+    }
+}
+
+// Handle command line arguments
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    console.log(`cf-memory-mcp v${PACKAGE_VERSION}`);
+    process.exit(0);
+}
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log(`
+CF Memory MCP v${PACKAGE_VERSION}
+
+A portable MCP (Model Context Protocol) server for AI memory storage using Cloudflare infrastructure.
+
+Usage:
+  npx cf-memory-mcp                 Start the MCP server
+  npx cf-memory-mcp --version       Show version
+  npx cf-memory-mcp --help          Show this help
+
+Environment Variables:
+  DEBUG=1                           Enable debug logging
+  MCP_DEBUG=1                       Enable MCP debug logging
+
+For more information, visit: https://github.com/johnlam90/cf-memory-mcp
+`);
+    process.exit(0);
+}
+
+// Start the MCP server
+const server = new CFMemoryMCP();
+server.start().catch(error => {
+    console.error('Failed to start CF Memory MCP server:', error.message);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,79 @@
+{
+	"name": "cf-memory-mcp",
+	"version": "1.0.0",
+	"description": "A portable MCP (Model Context Protocol) server for AI memory storage using Cloudflare infrastructure",
+	"main": "bin/cf-memory-mcp.js",
+	"bin": {
+		"cf-memory-mcp": "./bin/cf-memory-mcp.js"
+	},
+	"author": {
+		"name": "John Lam",
+		"email": "johnlam90@gmail.com",
+		"url": "https://github.com/johnlam90"
+	},
+	"license": "MIT",
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"memory",
+		"ai",
+		"cloudflare",
+		"workers",
+		"d1",
+		"portable",
+		"cli",
+		"npx"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/johnlam90/cf-memory-mcp.git"
+	},
+	"bugs": {
+		"url": "https://github.com/johnlam90/cf-memory-mcp/issues"
+	},
+	"homepage": "https://github.com/johnlam90/cf-memory-mcp#readme",
+	"engines": {
+		"node": ">=16.0.0"
+	},
+	"os": [
+		"darwin",
+		"linux",
+		"win32"
+	],
+	"files": [
+		"bin/",
+		"lib/",
+		"README.md",
+		"LICENSE"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"start": "node bin/cf-memory-mcp.js",
+		"test": "node test/test-package.js",
+		"test:mcp": "node test/mcp-integration.test.js",
+		"prepublishOnly": "npm test",
+		"deploy": "wrangler deploy",
+		"dev": "wrangler dev",
+		"cf-typegen": "wrangler types",
+		"test:performance": "node test/performance-benchmark.js",
+		"test:all": "npm test && npm run test:mcp",
+		"test:full": "npm run test:all && npm run test:performance",
+		"benchmark": "npm run test:performance",
+		"validate": "npm run cf-typegen && npm run test:all"
+	},
+	"dependencies": {},
+	"devDependencies": {
+		"@modelcontextprotocol/sdk": "^1.13.1",
+		"@cloudflare/workers-types": "^4.20250129.0",
+		"@types/node": "22.13.0",
+		"@types/service-worker-mock": "^2.0.4",
+		"@types/uuid": "^9.0.8",
+		"chanfana": "^2.6.3",
+		"hono": "^4.6.20",
+		"uuid": "^11.0.4",
+		"zod": "^3.24.1",
+		"wrangler": "^4.21.2"
+	}
+}