workfullcircle-mcp 1.0.8 → 1.1.0

package/README.md

@@ -0,0 +1,171 @@
+# WorkFullCircle MCP - Universal AI Memory
+
+🧠 **Persistent intelligence that works anywhere across all your AI tools**
+
+# Quick Start
+
+```bash
+# Install and configure automatically
+npx workfullcircle-mcp install --token uam_your_token_here
+
+# Or use the remote server directly
+npx workfullcircle-remote https://your-server.com/sse --header "Authorization: Bearer uam_your_token"
+```
+
+## Environment Variables
+
+Configure your MCP server with these environment variables:
+
+### Required Variables
+```bash
+# WorkFullCircle API Configuration
+WFC_API_URL=https://workfullcircle.com/api          # Your API endpoint
+WFC_API_KEY=uam_your_api_key_here                    # Your API key
+
+# For remote server connections
+WFC_SSE_URL=https://workfullcircle.com/sse           # SSE endpoint
+```
+
+### Optional Variables
+```bash
+# Testing
+TEST_API_URL=http://localhost:9001/api               # Local testing API
+TEST_API_KEY=uam_test_key                            # Local testing key
+
+# Server Configuration (for self-hosting)
+HOST=0.0.0.0                                         # Server host
+PORT=9001                                            # Server port
+NODE_ENV=development                                 # Environment
+```
+
+## Installation Methods
+
+### Method 1: Auto-Install (Recommended)
+```bash
+npx @workfullcircle/mcp install --token uam_your_token
+```
+- Automatically detects and configures: Claude Desktop, Cursor, Windsurf, VS Code
+- No manual config file editing required
+
+### Method 2: Manual Configuration
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "workfullcircle": {
+      "command": "npx",
+      "args": ["-y", "workfullcircle-remote", "https://workfullcircle.com/sse", "--header", "Authorization: Bearer uam_your_token"]
+    }
+  }
+}
+```
+
+**Cursor/Windsurf** (`~/.cursor/mcp.json` or `~/.windsurf/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "workfullcircle": {
+      "command": "npx",
+      "args": ["-y", "workfullcircle-remote", "https://workfullcircle.com/sse", "--header", "Authorization: Bearer uam_your_token"]
+    }
+  }
+}
+```
+
+### Method 3: Local API Connection
+For direct API connections without SSE:
+```json
+{
+  "mcpServers": {
+    "workfullcircle": {
+      "command": "npx",
+      "args": ["-y", "workfullcircle-mcp-local"],
+      "env": {
+        "WFC_API_URL": "https://workfullcircle.com/api",
+        "WFC_API_KEY": "uam_your_token"
+      }
+    }
+  }
+}
+```
+
+## Platform Support
+
+✅ **Claude Desktop** - Full SSE support  
+✅ **Cursor** - Full SSE support  
+✅ **Windsurf** - Full SSE support  
+✅ **VS Code** - Via global MCP extension  
+✅ **LangChain** - Via stdio interface  
+✅ **Custom integrations** - Standard MCP protocol
+
+## Available Tools
+
+- `save_memory` - Store important information
+- `get_memory` - Search and retrieve memories  
+- `capture_cognition` - Auto-capture conversations
+- `delete_memory` - Remove stored memories
+- `update_memory` - Modify existing memories
+- `list_all_memories` - Browse all stored memories
+
+## Self-Hosting
+
+Set up your own WorkFullCircle server:
+
+1. **Clone and setup**:
+```bash
+git clone https://github.com/workfullcircle/universal-ai-memory-mcp
+cd universal-ai-memory-mcp
+cp .env.example .env
+# Edit .env with your configuration
+npm install
+npm start
+```
+
+2. **Configure environment**:
+```bash
+# .env file
+SUPABASE_URL=your_supabase_url
+SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
+OPENAI_API_KEY=your_openai_key
+HOST=0.0.0.0
+PORT=9001
+```
+
+3. **Connect clients**:
+```bash
+npx workfullcircle-mcp install --token uam_your_token --server-url http://localhost:9001
+```
+
+## Architecture
+
+- **workfullcircle-mcp** - Main installer CLI
+- **workfullcircle-remote** - SSE proxy for remote servers
+- **workfullcircle-mcp-local** - Direct API client
+
+## Troubleshooting
+
+**Connection Issues**:
+- Verify `WFC_API_KEY` is correct and starts with `uam_`
+- Check `WFC_API_URL` is accessible
+- Ensure firewall allows connections to workfullcircle.com
+
+**Configuration Issues**:
+- Run `npx workfullcircle-mcp install` to auto-fix configs
+- Check JSON syntax in manual config files
+- Restart IDE after configuration changes
+
+**Platform-Specific**:
+- **Windows**: Configs in `%APPDATA%\Claude\` and `%USERPROFILE%\.cursor\`
+- **macOS**: Configs in `~/Library/Application Support/` and `~/.cursor/`
+- **Linux**: Configs in `~/.config/` and `~/.cursor/`
+
+## Support
+
+- 📖 [Documentation](https://workfullcircle.com/docs)
+- 🐛 [Issues](https://github.com/workfullcircle/mcp/issues)
+- 💬 [Community](https://discord.gg/workfullcircle)
+
+---
+
+**WorkFullCircle** - Your AI memory, everywhere you need it.

package/bin/workfullcircle-mcp.js

@@ -1,59 +1,59 @@
-#!/usr/bin/env node
-
-const { validateToken } = require('../src/auth');
-const { getTargets, writeConfig } = require('../src/config-writer');
-
-const args = process.argv.slice(2);
-
-function printUsage() {
-  console.error('Usage: workfullcircle-mcp install --token uam_...');
-  process.exit(1);
-}
-
-function parseArgs(argv) {
-  if (argv.length < 2) {
-    printUsage();
-  }
-
-  const command = argv[0];
-  const tokenIndex = argv.indexOf('--token');
-  const token = tokenIndex !== -1 ? argv[tokenIndex + 1] : null;
-  const projectIndex = argv.indexOf('--project');
-  const projectId = projectIndex !== -1 ? argv[projectIndex + 1] : null;
-
-  if (command !== 'install' || !token) {
-    printUsage();
-  }
-
-  const validation = validateToken(token);
-  if (!validation.valid) {
-    console.error(`Error: ${validation.error}`);
-    process.exit(1);
-  }
-
-  return { token, projectId };
-}
-
-function install(token, projectId) {
-  const targets = getTargets();
-  let updated = 0;
-  targets.forEach((target) => {
-    if (!target.path) return;
-    const result = writeConfig(target, token, projectId);
-    if (result.success) {
-      console.error(`Updated ${target.name} config.`);
-      updated += 1;
-    } else {
-      console.warn(`Skipping ${target.name}: ${result.error}`);
-    }
-  });
-
-  if (updated === 0) {
-    console.error('No configs found. Please create a config file manually.');
-  } else {
-    console.error('Setup complete. Restart your IDE to load WorkFullCircle.');
-  }
-}
-
-const { token, projectId } = parseArgs(args);
-install(token, projectId);
+#!/usr/bin/env node
+
+const { validateToken } = require('../src/auth');
+const { getTargets, writeConfig } = require('../src/config-writer');
+
+const args = process.argv.slice(2);
+
+function printUsage() {
+  console.log('Usage: workfullcircle-mcp install --token uam_...');
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  if (argv.length < 2) {
+    printUsage();
+  }
+
+  const command = argv[0];
+  const tokenIndex = argv.indexOf('--token');
+  const token = tokenIndex !== -1 ? argv[tokenIndex + 1] : null;
+  const projectIndex = argv.indexOf('--project');
+  const projectId = projectIndex !== -1 ? argv[projectIndex + 1] : null;
+
+  if (command !== 'install' || !token) {
+    printUsage();
+  }
+
+  const validation = validateToken(token);
+  if (!validation.valid) {
+    console.error(`Error: ${validation.error}`);
+    process.exit(1);
+  }
+
+  return { token, projectId };
+}
+
+function install(token, projectId) {
+  const targets = getTargets();
+  let updated = 0;
+  targets.forEach((target) => {
+    if (!target.path) return;
+    const result = writeConfig(target, token, projectId);
+    if (result.success) {
+      console.log(`Updated ${target.name} config.`);
+      updated += 1;
+    } else {
+      console.warn(`Skipping ${target.name}: ${result.error}`);
+    }
+  });
+
+  if (updated === 0) {
+    console.log('No configs found. Please create a config file manually.');
+  } else {
+    console.log('Setup complete. Restart your IDE to load WorkFullCircle.');
+  }
+}
+
+const { token, projectId } = parseArgs(args);
+install(token, projectId);

package/package.json

@@ -1,26 +1,32 @@
-{
-  "name": "workfullcircle-mcp",
-  "version": "1.0.8",
-  "description": "WorkFullCircle MCP installer CLI",
-  "bin": {
-    "workfullcircle-mcp": "bin/workfullcircle-mcp.js"
-  },
-  "main": "bin/workfullcircle-mcp.js",
-  "scripts": {
-    "start": "node bin/workfullcircle-mcp.js"
-  },
-  "keywords": [
-    "mcp",
-    "workfullcircle",
-    "installer",
-    "cli"
-  ],
-  "author": "Afreensiyad",
-  "license": "MIT",
-  "dependencies": {
-    "fs-extra": "^11.2.0"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  }
-}
+{
+  "name": "workfullcircle-mcp",
+  "version": "1.1.0",
+  "description": "WorkFullCircle MCP - Universal AI memory that works anywhere",
+  "bin": {
+    "workfullcircle-mcp": "bin/workfullcircle-mcp.js"
+  },
+  "main": "bin/workfullcircle-mcp.js",
+  "scripts": {
+    "start": "node bin/workfullcircle-mcp.js"
+  },
+  "keywords": [
+    "mcp",
+    "workfullcircle",
+    "ai",
+    "memory",
+    "universal",
+    "cross-platform",
+    "windsurf",
+    "cursor",
+    "claude",
+    "vscode"
+  ],
+  "author": "Afreensiyad",
+  "license": "MIT",
+  "dependencies": {
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/src/config-writer.js

@@ -35,8 +35,8 @@ function getTargets() {
 function buildConfig(token, projectId) {
   const args = [
     '-y',
-    '@workfullcircle/remote',
-    'https://workfullcircle.com/sse',
+    'workfullcircle-remote',
+    process.env.WFC_SSE_URL || 'https://workfullcircle.com/sse',
     '--header',
     `Authorization: Bearer ${token}`
   ];

package/test-install.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+/**
+ * Test script to verify @workfullcircle/mcp installation
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+console.log('🧪 Testing @workfullcircle/mcp package...\n');
+
+// Test 1: Help command
+console.log('1. Testing help command...');
+const helpProcess = spawn('node', [path.join(__dirname, 'bin', 'workfullcircle-mcp.js')], {
+  stdio: 'pipe'
+});
+
+helpProcess.stdout.on('data', (data) => {
+  console.log('✅ Help output:', data.toString().trim());
+});
+
+helpProcess.stderr.on('data', (data) => {
+  console.log('❌ Help error:', data.toString().trim());
+});
+
+// Test 2: Token validation
+console.log('\n2. Testing token validation...');
+const testProcess = spawn('node', [
+  path.join(__dirname, 'bin', 'workfullcircle-mcp.js'),
+  'install',
+  '--token',
+  'uam_test_token_12345'
+], {
+  stdio: 'pipe'
+});
+
+testProcess.stdout.on('data', (data) => {
+  console.log('✅ Install output:', data.toString().trim());
+});
+
+testProcess.stderr.on('data', (data) => {
+  console.log('❌ Install error:', data.toString().trim());
+});
+
+setTimeout(() => {
+  console.log('\n🎉 Test completed! The package is ready for publishing.');
+  console.log('\n📦 To publish to npm:');
+  console.log('   cd packages/wfc-cli');
+  console.log('   npm publish');
+  console.log('\n🚀 Users can then run:');
+  console.log('   npx @workfullcircle/mcp install --token uam_their_token');
+}, 2000);