@amar_528/mcp-bridge 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HIVE-MIND Team
+
+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,187 @@
+# @hivemind/mcp-bridge
+
+**Sovereign EU MCP Bridge for Claude Desktop and Cursor**
+
+Connect your AI IDE to GDPR-compliant, sovereign European memory storage with a single command.
+
+```bash
+npx @hivemind/mcp-bridge
+```
+
+## Features
+
+- **Sovereign EU Storage**: All data resides in Hetzner Cloud (Falkenstein, Germany)
+- **GDPR Compliant**: No data residency concerns for European enterprises
+- **Semantic Search**: Powered by Qdrant vector database with automatic embedding
+- **Triple-Operator System**: Memories support Updates/Extends/Derives relationships
+- **Zero Configuration**: Works with `npx` - no installation required
+
+## Quick Start
+
+### Claude Desktop Configuration
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hivemind": {
+      "command": "npx",
+      "args": ["-y", "@hivemind/mcp-bridge"],
+      "env": {
+        "HIVEMIND_API_URL": "https://hivemind.davinciai.eu",
+        "HIVEMIND_API_KEY": "hm_master_key_99228811",
+        "HIVEMIND_USER_ID": "00000000-0000-4000-8000-000000000001"
+      }
+    }
+  }
+}
+```
+
+### Cursor IDE Configuration
+
+Add this to your `.cursor/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "hivemind": {
+      "command": "npx",
+      "args": ["-y", "@hivemind/mcp-bridge"],
+      "env": {
+        "HIVEMIND_API_URL": "https://hivemind.davinciai.eu",
+        "HIVEMIND_API_KEY": "hm_master_key_99228811"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+Once connected, you have access to these MCP tools:
+
+| Tool | Description |
+|------|-------------|
+| `save_memory` | Save text, code, or data to sovereign storage |
+| `recall` | Search memories with semantic ranking |
+| `list_memories` | List all memories with filters |
+| `get_memory` | Retrieve a specific memory by ID |
+| `delete_memory` | Delete a memory |
+| `get_context` | Get contextual information |
+| `search_memories` | Hybrid search across memories |
+| `traverse_graph` | Navigate memory relationships |
+
+## Usage Examples
+
+### Save a Memory
+
+```
+Save this code snippet:
+
+const greet = (name) => `Hello, ${name}!`;
+
+Tags: javascript, utility, greeting
+Project: my-app
+```
+
+### Search Memories
+
+```
+Find memories about authentication patterns
+```
+
+### Recall Context
+
+```
+What do I know about the user preferences API?
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HIVEMIND_API_URL` | Yes | HIVE-MIND API endpoint URL |
+| `HIVEMIND_API_KEY` | Yes | Authentication API key |
+| `HIVEMIND_USER_ID` | No | User identifier (auto-generated if not set) |
+
+## Local Development Mode
+
+For testing against a local HIVE-MIND server:
+
+```bash
+npx @hivemind/mcp-bridge local --url http://localhost:3000
+```
+
+## Command Line Options
+
+```
+USAGE:
+  npx @hivemind/mcp-bridge [mode] [options]
+
+MODES:
+  hosted    Connect to hosted HIVE-MIND API (default)
+  local     Connect to local development server
+
+OPTIONS:
+  --url <url>         API URL (overrides env var)
+  --api-key <key>     API key (overrides env var)
+  --user-id <id>      User ID (overrides env var)
+  --verbose, -v       Enable verbose logging
+  --version           Show version number
+  --help, -h          Show help message
+```
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│  Claude Desktop │────▶│  MCP Bridge      │────▶│  HIVE-MIND API  │
+│  (MCP Client)   │     │  (npx @hivemind) │     │  (Hetzner EU)   │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+                                                    │
+                     ┌──────────────────────────────┼──────────────┐
+                     │                              │              │
+                     ▼                              ▼              ▼
+            ┌─────────────────┐           ┌─────────────────┐     │
+            │  PostgreSQL     │           │  Qdrant Cloud   │     │
+            │  (Metadata)     │           │  (Vectors)      │     │
+            └─────────────────┘           └─────────────────┘     │
+                                                                  │
+                                                    ┌─────────────────┐
+                                                    │  Hetzner        │
+                                                    │  Embeddings     │
+                                                    │  (all-MiniLM)   │
+                                                    └─────────────────┘
+```
+
+## Data Residency
+
+All data is stored in the European Union:
+
+- **PostgreSQL**: Hetzner Cloud (Falkenstein, Germany)
+- **Qdrant Cloud**: AWS Frankfurt (EU region)
+- **Embeddings**: Hetzner Cloud (Falkenstein, Germany)
+
+This ensures GDPR compliance for European enterprises with strict data residency requirements.
+
+## Comparison with Supermemory
+
+| Feature | HIVE-MIND | Supermemory |
+|---------|-----------|-------------|
+| Data Residency | EU (Hetzner) | US (Cloudflare) |
+| GDPR Compliance | Yes | Limited |
+| Infrastructure | Sovereign EU | US-centric |
+| Target Market | European enterprises | Global |
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file.
+
+## Repository
+
+https://github.com/hivemind/mcp-bridge
+
+## Support
+
+For issues or questions, please open an issue on GitHub.

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * HIVE-MIND MCP Bridge CLI
+ * Bridges local MCP clients to hosted HIVE-MIND MCP service
+ *
+ * Usage:
+ *   npx @hivemind/mcp-bridge hosted     - Connect to hosted EU backend
+ *   npx @hivemind/mcp-bridge local      - Connect to local development server
+ *   npx @hivemind/mcp-bridge            - Defaults to hosted mode
+ *
+ * Environment Variables (hosted mode):
+ *   HIVEMIND_API_URL        - HIVE-MIND API URL (required for hosted)
+ *   HIVEMIND_API_KEY        - API key for authentication (required for hosted)
+ *   HIVEMIND_USER_ID        - User identifier (optional, defaults to UUID)
+ *
+ * Environment Variables (local mode):
+ *   HIVEMIND_LOCAL_URL      - Local server URL (default: http://localhost:3000)
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+/**
+ * HIVE-MIND MCP Bridge CLI
+ * Bridges local MCP clients to hosted HIVE-MIND MCP service
+ *
+ * Usage:
+ *   npx @hivemind/mcp-bridge hosted     - Connect to hosted EU backend
+ *   npx @hivemind/mcp-bridge local      - Connect to local development server
+ *   npx @hivemind/mcp-bridge            - Defaults to hosted mode
+ *
+ * Environment Variables (hosted mode):
+ *   HIVEMIND_API_URL        - HIVE-MIND API URL (required for hosted)
+ *   HIVEMIND_API_KEY        - API key for authentication (required for hosted)
+ *   HIVEMIND_USER_ID        - User identifier (optional, defaults to UUID)
+ *
+ * Environment Variables (local mode):
+ *   HIVEMIND_LOCAL_URL      - Local server URL (default: http://localhost:3000)
+ */
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+// Get package version
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let packageVersion = '2.0.0';
+try {
+    const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+    packageVersion = pkg.version;
+}
+catch {
+    // Ignore if package.json not found
+}
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const config = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case 'hosted':
+            case '--hosted':
+                config.mode = 'hosted';
+                break;
+            case 'local':
+            case '--local':
+                config.mode = 'local';
+                break;
+            case '--url':
+                config.apiUrl = args[++i];
+                break;
+            case '--api-key':
+                config.apiKey = args[++i];
+                break;
+            case '--user-id':
+                config.userId = args[++i];
+                break;
+            case '-v':
+            case '--verbose':
+                config.verbose = true;
+                break;
+            case '--version':
+                console.log(`@hivemind/mcp-bridge v${packageVersion}`);
+                process.exit(0);
+            case '--help':
+            case '-h':
+                printHelp();
+                process.exit(0);
+        }
+    }
+    return config;
+}
+function printHelp() {
+    console.log(`
+HIVE-MIND MCP Bridge v${packageVersion}
+Connect Claude Desktop/Cursor to sovereign EU memory storage
+
+USAGE:
+  npx @hivemind/mcp-bridge [mode] [options]
+
+MODES:
+  hosted    Connect to hosted HIVE-MIND API (default)
+  local     Connect to local development server
+
+OPTIONS:
+  --url <url>         API URL (overrides env var)
+  --api-key <key>     API key (overrides env var)
+  --user-id <id>      User ID (overrides env var)
+  --verbose, -v       Enable verbose logging
+  --version           Show version number
+  --help, -h          Show this help message
+
+ENVIRONMENT VARIABLES:
+  HIVEMIND_API_URL      API URL for hosted mode
+  HIVEMIND_API_KEY      API key for authentication
+  HIVEMIND_USER_ID      User identifier (UUID)
+  HIVEMIND_LOCAL_URL    Local server URL (default: http://localhost:3000)
+
+EXAMPLES:
+  # Use with Claude Desktop (configured in claude_desktop_config.json)
+  {
+    "mcpServers": {
+      "hivemind": {
+        "command": "npx",
+        "args": ["-y", "@hivemind/mcp-bridge", "hosted"],
+        "env": {
+          "HIVEMIND_API_URL": "https://hivemind.davinciai.eu",
+          "HIVEMIND_API_KEY": "hm_master_key_...",
+          "HIVEMIND_USER_ID": "00000000-0000-4000-8000-000000000001"
+        }
+      }
+    }
+  }
+
+  # Local development
+  npx @hivemind/mcp-bridge local --url http://localhost:3000
+
+MORE INFO:
+  https://github.com/hivemind/mcp-bridge
+`);
+}
+function loadConfig() {
+    const cliConfig = parseArgs();
+    const mode = cliConfig.mode || 'hosted';
+    const verbose = cliConfig.verbose || false;
+    if (mode === 'hosted') {
+        const apiUrl = cliConfig.apiUrl || process.env.HIVEMIND_API_URL;
+        const apiKey = cliConfig.apiKey || process.env.HIVEMIND_API_KEY;
+        const userId = cliConfig.userId || process.env.HIVEMIND_USER_ID || generateUserId();
+        if (!apiUrl || !apiKey) {
+            console.error('ERROR: Hosted mode requires HIVEMIND_API_URL and HIVEMIND_API_KEY');
+            console.error('');
+            console.error('Set environment variables:');
+            console.error('  export HIVEMIND_API_URL="https://hivemind.davinciai.eu"');
+            console.error('  export HIVEMIND_API_KEY="hm_master_key_..."');
+            console.error('');
+            console.error('Or configure in claude_desktop_config.json:');
+            console.error('  "env": {');
+            console.error('    "HIVEMIND_API_URL": "...",');
+            console.error('    "HIVEMIND_API_KEY": "..."');
+            console.error('  }');
+            process.exit(1);
+        }
+        return { mode, apiUrl, apiKey, userId, verbose };
+    }
+    else {
+        // Local mode
+        const apiUrl = cliConfig.apiUrl || process.env.HIVEMIND_LOCAL_URL || 'http://localhost:3000';
+        const apiKey = cliConfig.apiKey || process.env.HIVEMIND_API_KEY || 'hm_master_key_99228811';
+        const userId = cliConfig.userId || '00000000-0000-4000-8000-000000000001';
+        return { mode, apiUrl, apiKey, userId, verbose };
+    }
+}
+function generateUserId() {
+    // Generate a stable user ID based on hostname for local development
+    const hostname = require('os').hostname();
+    const hash = require('crypto').createHash('md5').update(hostname).digest('hex');
+    return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-${hash.slice(12, 16)}-${hash.slice(16, 20)}-${hash.slice(20, 32)}`;
+}
+// ============================================================================
+// MCP Bridge Implementation
+// ============================================================================
+async function runHostedBridge(config) {
+    log(config, `Starting HIVE-MIND MCP Bridge v${packageVersion}`);
+    log(config, `Mode: HOSTED`);
+    log(config, `API URL: ${config.apiUrl}`);
+    log(config, `User ID: ${config.userId}`);
+    // Fetch MCP configuration from hosted service
+    log(config, 'Fetching MCP configuration...');
+    try {
+        const response = await fetch(`${config.apiUrl}/api/mcp/servers/${config.userId}`, {
+            headers: {
+                'X-API-Key': config.apiKey,
+                'X-User-Id': config.userId
+            }
+        });
+        if (!response.ok) {
+            console.error(`Failed to connect to HIVE-MIND: ${response.status} ${response.statusText}`);
+            console.error('');
+            console.error('Troubleshooting:');
+            console.error('  1. Check HIVEMIND_API_URL is correct');
+            console.error('  2. Check HIVEMIND_API_KEY is valid');
+            console.error('  3. Verify the server is running');
+            process.exit(1);
+        }
+        const serverConfig = await response.json();
+        log(config, `Connected! Server: ${serverConfig.mcp.serverInfo.name} v${serverConfig.mcp.serverInfo.version}`);
+        log(config, `Available tools: ${serverConfig.tools.length}`);
+        if (config.verbose) {
+            serverConfig.tools.forEach(tool => {
+                log(config, `  - ${tool.name}: ${tool.description}`);
+            });
+        }
+        // Start stdio bridge - handle incoming MCP messages
+        process.stdin.on('data', async (data) => {
+            try {
+                const message = JSON.parse(data.toString());
+                await handleMessage(message, config, serverConfig);
+            }
+            catch (error) {
+                log(config, `Error parsing message: ${error.message}`);
+                sendError(null, -32700, 'Parse error: Invalid JSON');
+            }
+        });
+        // Keep process alive
+        setInterval(() => { }, 1000);
+    }
+    catch (error) {
+        console.error(`Connection error: ${error.message}`);
+        process.exit(1);
+    }
+}
+async function handleMessage(message, config, serverConfig) {
+    const { method, id, params } = message;
+    switch (method) {
+        case 'initialize':
+            sendResponse(id, { result: serverConfig.mcp });
+            break;
+        case 'tools/list':
+            sendResponse(id, { result: { tools: serverConfig.tools } });
+            break;
+        case 'tools/call': {
+            const toolParams = params;
+            const toolName = toolParams?.name;
+            const toolArgs = toolParams?.arguments;
+            log(config, `Tool call: ${toolName}`);
+            if (config.verbose) {
+                log(config, `  Arguments: ${JSON.stringify(toolArgs, null, 2)}`);
+            }
+            try {
+                // Proxy tool call to hosted service
+                const response = await fetch(`${config.apiUrl}/api/mcp/rpc`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${config.apiKey}`,
+                        'X-User-Id': config.userId
+                    },
+                    body: JSON.stringify({
+                        jsonrpc: '2.0',
+                        id,
+                        method: 'tools/call',
+                        params: {
+                            name: toolName,
+                            arguments: toolArgs
+                        }
+                    })
+                });
+                const resultData = await response.json();
+                if (config.verbose) {
+                    log(config, `  Response: ${JSON.stringify(resultData)}`);
+                }
+                console.log(JSON.stringify(resultData));
+            }
+            catch (error) {
+                sendError(id, -32603, `Tool call failed: ${error.message}`);
+            }
+            break;
+        }
+        case 'ping':
+            sendResponse(id, { result: {} });
+            break;
+        default:
+            sendError(id, -32601, `Method not found: ${method}`);
+    }
+}
+function sendResponse(id, response) {
+    console.log(JSON.stringify({
+        jsonrpc: '2.0',
+        id,
+        ...response
+    }));
+}
+function sendError(id, code, message) {
+    console.log(JSON.stringify({
+        jsonrpc: '2.0',
+        id,
+        error: { code, message }
+    }));
+}
+function log(config, message) {
+    if (config.verbose || !config.mode) {
+        console.error(`[HIVE-MIND Bridge] ${message}`);
+    }
+}
+async function runLocalBridge(config) {
+    log(config, `Starting HIVE-MIND MCP Bridge v${packageVersion}`);
+    log(config, `Mode: LOCAL`);
+    log(config, `Local URL: ${config.apiUrl}`);
+    // For local mode, we proxy to a local HIVEMIND server
+    console.error(`[HIVE-MIND Bridge] Local mode connects to ${config.apiUrl}`);
+    console.error(`[HIVE-MIND Bridge] This mode is for development only`);
+    // Same implementation as hosted, but with local URL
+    await runHostedBridge(config);
+}
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+async function main() {
+    try {
+        const config = loadConfig();
+        if (config.mode === 'hosted') {
+            await runHostedBridge(config);
+        }
+        else {
+            await runLocalBridge(config);
+        }
+    }
+    catch (error) {
+        console.error(`Fatal error: ${error.message}`);
+        process.exit(1);
+    }
+}
+main().catch(console.error);

package/dist/server.d.ts

@@ -0,0 +1,178 @@
+/**
+ * HIVE-MIND MCP Server with Zod Validation
+ * Implements the "Supermemory" tool pattern for strict input validation
+ * Ensures all memory operations follow the Normalized Memory Schema
+ */
+import { z } from 'zod';
+/**
+ * Memory content schema - accepts text, code, or structured data
+ */
+export declare const MemoryContentSchema: z.ZodString;
+/**
+ * Tags schema - optional array of strings for categorization
+ */
+export declare const MemoryTagsSchema: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+/**
+ * Project identifier schema - defaults to 'antigravity' for backward compatibility
+ */
+export declare const ProjectSchema: z.ZodDefault<z.ZodString>;
+/**
+ * User identifier schema - UUID format preferred
+ */
+export declare const UserIdSchema: z.ZodString;
+/**
+ * Memory priority schema - for importance ranking
+ */
+export declare const PrioritySchema: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+/**
+ * Relationship type for triple-operator system
+ */
+export declare const RelationshipTypeSchema: z.ZodOptional<z.ZodEnum<["updates", "extends", "derives"]>>;
+/**
+ * Complete memory input schema - combines all fields
+ */
+export declare const SaveMemoryInputSchema: z.ZodObject<{
+    content: z.ZodString;
+    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    project: z.ZodDefault<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    priority: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    relationship: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodEnum<["updates", "extends", "derives"]>>;
+        targetId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type?: "updates" | "extends" | "derives" | undefined;
+        targetId?: string | undefined;
+    }, {
+        type?: "updates" | "extends" | "derives" | undefined;
+        targetId?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    tags: string[];
+    project: string;
+    userId?: string | undefined;
+    priority?: number | undefined;
+    relationship?: {
+        type?: "updates" | "extends" | "derives" | undefined;
+        targetId?: string | undefined;
+    } | undefined;
+}, {
+    content: string;
+    userId?: string | undefined;
+    tags?: string[] | undefined;
+    project?: string | undefined;
+    priority?: number | undefined;
+    relationship?: {
+        type?: "updates" | "extends" | "derives" | undefined;
+        targetId?: string | undefined;
+    } | undefined;
+}>;
+export type SaveMemoryInput = z.infer<typeof SaveMemoryInputSchema>;
+export type MemoryTags = z.infer<typeof MemoryTagsSchema>;
+export type RelationshipType = z.infer<typeof RelationshipTypeSchema>;
+/**
+ * Validate and parse memory input with detailed error messages
+ */
+export declare function validateMemoryInput(input: unknown): {
+    success: true;
+    data: SaveMemoryInput;
+} | {
+    success: false;
+    error: string;
+    details?: Record<string, string[]>;
+};
+/**
+ * Normalize memory content (trim, clean, standardize)
+ */
+export declare function normalizeMemoryContent(content: string): string;
+/**
+ * Generate normalized tags (lowercase, trimmed, deduplicated)
+ */
+export declare function normalizeTags(tags?: string[]): string[];
+/**
+ * Result type for memory operations
+ */
+export interface MemoryOperationResult {
+    success: boolean;
+    memoryId?: string;
+    message: string;
+    metadata?: {
+        vectorStored?: boolean;
+        relationshipDetected?: boolean;
+        relationshipType?: RelationshipType;
+    };
+}
+/**
+ * Handler function type for save_memory tool
+ */
+export type SaveMemoryHandler = (input: SaveMemoryInput) => Promise<MemoryOperationResult>;
+/**
+ * Create a configured save_memory tool handler
+ *
+ * @param hivemindApiUrl - The HIVE-MIND API URL
+ * @param hivemindApiKey - The API key for authentication
+ * @returns Handler function for MCP tool
+ */
+export declare function createSaveMemoryHandler(hivemindApiUrl: string, hivemindApiKey: string): SaveMemoryHandler;
+/**
+ * Tool definition for registration with MCP server
+ *
+ * Usage:
+ * ```typescript
+ * const server = new McpServer({ name: "HIVE-MIND", version: "2.0.0" });
+ *
+ * server.tool(
+ *   MEMORY_TOOL_DEFINITION.name,
+ *   MEMORY_TOOL_DEFINITION.inputSchema,
+ *   MEMORY_TOOL_DEFINITION.handler
+ * );
+ * ```
+ */
+export declare const MEMORY_TOOL_DEFINITION: {
+    name: string;
+    description: string;
+    inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+                readonly description: "The text, code, or data to remember (max 50,000 chars)";
+            };
+            readonly tags: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Category tags for organizing memories (max 20)";
+            };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Project context (default: \"antigravity\")";
+            };
+            readonly priority: {
+                readonly type: "number";
+                readonly minimum: 0;
+                readonly maximum: 10;
+                readonly description: "Importance priority 0-10 (default: 5)";
+            };
+            readonly relationship: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["updates", "extends", "derives"];
+                        readonly description: "Relationship to existing memory";
+                    };
+                    readonly targetId: {
+                        readonly type: "string";
+                        readonly format: "uuid";
+                        readonly description: "ID of related memory";
+                    };
+                };
+                readonly description: "Triple-operator relationship (Updates/Extends/Derives)";
+            };
+        };
+        readonly required: readonly ["content"];
+    };
+};

package/dist/server.js

@@ -0,0 +1,231 @@
+/**
+ * HIVE-MIND MCP Server with Zod Validation
+ * Implements the "Supermemory" tool pattern for strict input validation
+ * Ensures all memory operations follow the Normalized Memory Schema
+ */
+import { z } from 'zod';
+// ============================================================================
+// Schema Definitions (Normalized Memory Schema)
+// ============================================================================
+/**
+ * Memory content schema - accepts text, code, or structured data
+ */
+export const MemoryContentSchema = z.string()
+    .min(1, "Memory content cannot be empty")
+    .max(50000, "Memory content exceeds maximum length of 50,000 characters")
+    .describe("The text, code, or data to remember");
+/**
+ * Tags schema - optional array of strings for categorization
+ */
+export const MemoryTagsSchema = z.array(z.string())
+    .max(20, "Maximum 20 tags allowed")
+    .optional()
+    .default([])
+    .describe("Category tags for organizing memories");
+/**
+ * Project identifier schema - defaults to 'antigravity' for backward compatibility
+ */
+export const ProjectSchema = z.string()
+    .min(1, "Project name cannot be empty")
+    .default("antigravity")
+    .describe("Project context for the memory");
+/**
+ * User identifier schema - UUID format preferred
+ */
+export const UserIdSchema = z.string()
+    .uuid("Invalid UUID format")
+    .describe("User who owns this memory");
+/**
+ * Memory priority schema - for importance ranking
+ */
+export const PrioritySchema = z.number()
+    .min(0)
+    .max(10)
+    .default(5)
+    .optional()
+    .describe("Importance priority (0-10, default 5)");
+/**
+ * Relationship type for triple-operator system
+ */
+export const RelationshipTypeSchema = z.enum(['updates', 'extends', 'derives'])
+    .optional()
+    .describe("Relationship to existing memories (triple-operator system)");
+/**
+ * Complete memory input schema - combines all fields
+ */
+export const SaveMemoryInputSchema = z.object({
+    content: MemoryContentSchema,
+    tags: MemoryTagsSchema,
+    project: ProjectSchema,
+    userId: UserIdSchema.optional(),
+    priority: PrioritySchema,
+    relationship: z.object({
+        type: RelationshipTypeSchema,
+        targetId: z.string().uuid().optional()
+    }).optional()
+});
+// ============================================================================
+// Input Validation Helpers
+// ============================================================================
+/**
+ * Validate and parse memory input with detailed error messages
+ */
+export function validateMemoryInput(input) {
+    const result = SaveMemoryInputSchema.safeParse(input);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    const details = {};
+    result.error.errors.forEach(err => {
+        const path = err.path.join('.') || 'root';
+        if (!details[path])
+            details[path] = [];
+        details[path].push(err.message);
+    });
+    return {
+        success: false,
+        error: result.error.message,
+        details
+    };
+}
+/**
+ * Normalize memory content (trim, clean, standardize)
+ */
+export function normalizeMemoryContent(content) {
+    return content
+        .trim()
+        .replace(/\r\n/g, '\n') // Normalize line endings
+        .replace(/\s+$/gm, '') // Remove trailing whitespace
+        .replace(/^\s*\n/gm, '\n'); // Remove leading whitespace on lines
+}
+/**
+ * Generate normalized tags (lowercase, trimmed, deduplicated)
+ */
+export function normalizeTags(tags) {
+    if (!tags || tags.length === 0)
+        return [];
+    return Array.from(new Set(tags
+        .map(tag => tag.toLowerCase().trim())
+        .filter(tag => tag.length > 0)));
+}
+/**
+ * Create a configured save_memory tool handler
+ *
+ * @param hivemindApiUrl - The HIVE-MIND API URL
+ * @param hivemindApiKey - The API key for authentication
+ * @returns Handler function for MCP tool
+ */
+export function createSaveMemoryHandler(hivemindApiUrl, hivemindApiKey) {
+    return async (input) => {
+        try {
+            // Normalize input
+            const normalizedContent = normalizeMemoryContent(input.content);
+            const normalizedTags = normalizeTags(input.tags);
+            // Prepare payload for HIVE-MIND API
+            const payload = {
+                content: normalizedContent,
+                tags: normalizedTags,
+                project: input.project,
+                priority: input.priority,
+                relationship: input.relationship
+            };
+            // Send to sovereign EU backend
+            const response = await fetch(`${hivemindApiUrl}/api/memories`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${hivemindApiKey}`,
+                    'X-Data-Residency': 'EU' // GDPR compliance header
+                },
+                body: JSON.stringify(payload)
+            });
+            if (!response.ok) {
+                const errorBody = await response.text();
+                throw new Error(`API error: ${response.status} - ${errorBody}`);
+            }
+            const result = await response.json();
+            return {
+                success: true,
+                memoryId: result.id,
+                message: "Memory secured in HIVE-MIND sovereign storage",
+                metadata: {
+                    vectorStored: result.vectorStored ?? true,
+                    relationshipDetected: !!result.relationship,
+                    relationshipType: result.relationship?.type
+                }
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to save memory: ${error.message}`,
+                metadata: {
+                    vectorStored: false,
+                    relationshipDetected: false
+                }
+            };
+        }
+    };
+}
+// ============================================================================
+// MCP Tool Definition (for direct use with @modelcontextprotocol/sdk)
+// ============================================================================
+/**
+ * Tool definition for registration with MCP server
+ *
+ * Usage:
+ * ```typescript
+ * const server = new McpServer({ name: "HIVE-MIND", version: "2.0.0" });
+ *
+ * server.tool(
+ *   MEMORY_TOOL_DEFINITION.name,
+ *   MEMORY_TOOL_DEFINITION.inputSchema,
+ *   MEMORY_TOOL_DEFINITION.handler
+ * );
+ * ```
+ */
+export const MEMORY_TOOL_DEFINITION = {
+    name: 'save_memory',
+    description: 'Save a memory to HIVE-MIND sovereign EU storage. Supports text, code, and structured data with automatic semantic indexing.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            content: {
+                type: 'string',
+                description: 'The text, code, or data to remember (max 50,000 chars)'
+            },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Category tags for organizing memories (max 20)'
+            },
+            project: {
+                type: 'string',
+                description: 'Project context (default: "antigravity")'
+            },
+            priority: {
+                type: 'number',
+                minimum: 0,
+                maximum: 10,
+                description: 'Importance priority 0-10 (default: 5)'
+            },
+            relationship: {
+                type: 'object',
+                properties: {
+                    type: {
+                        type: 'string',
+                        enum: ['updates', 'extends', 'derives'],
+                        description: 'Relationship to existing memory'
+                    },
+                    targetId: {
+                        type: 'string',
+                        format: 'uuid',
+                        description: 'ID of related memory'
+                    }
+                },
+                description: 'Triple-operator relationship (Updates/Extends/Derives)'
+            }
+        },
+        required: ['content']
+    }
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@amar_528/mcp-bridge",
+  "version": "2.0.0",
+  "description": "Sovereign EU MCP Bridge - Connect Claude Desktop/Cursor to HIVE-MIND hosted MCP service with GDPR-compliant data residency",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "hivemind-mcp-bridge": "./dist/cli.js",
+    "hivemind-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "hivemind",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "ai",
+    "memory",
+    "gdpr",
+    "sovereign",
+    "europe"
+  ],
+  "author": "HIVE-MIND Team",
+  "license": "MIT",
+  "homepage": "https://github.com/hivemind/mcp-bridge#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hivemind/mcp-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hivemind/mcp-bridge/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "node-fetch": "^3.3.2"
+  }
+}