suma-mcp-proxy 1.0.0

package/README.md

@@ -0,0 +1,112 @@
+# SUMA MCP Local Proxy v1.0
+
+> Stable stdio bridge to stateless SUMA REST API
+
+## Why This Exists
+
+MCP (Model Context Protocol) was designed for **local/stdio** connections, not resilient cloud APIs. When you connect your IDE directly to a Cloud Run MCP endpoint:
+
+- Cloud Run scales to zero → session dies
+- Deploy new version → "Session not found"
+- Network hiccup → reconnection fails
+
+**This proxy runs locally**, maintaining an infinitely stable stdio connection to your IDE. It translates MCP tool calls to stateless REST API calls that Cloud Run handles gracefully.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Your Laptop                                            │
+│  ┌─────────────┐     stdio      ┌──────────────────┐   │
+│  │ Cursor /    │◄──────────────►│ suma-mcp-proxy   │   │
+│  │ Claude Code │   (stable)     │ (this script)    │   │
+│  └─────────────┘                └────────┬─────────┘   │
+└──────────────────────────────────────────┼─────────────┘
+                                           │ HTTPS REST
+                                           ▼
+┌─────────────────────────────────────────────────────────┐
+│  Cloud Run (stateless, scales freely, deploys anytime)  │
+│  https://sumapro-web-xxx.run.app/api/*                  │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+cd quad-products/squad-suma-mcp/proxy
+npm install
+```
+
+## Usage
+
+### Option 1: Environment Variable
+
+```bash
+export SUMA_API_KEY=sk_live_xxx
+node index.js
+```
+
+### Option 2: Command Line Argument
+
+```bash
+node index.js --key=sk_live_xxx
+```
+
+### Option 3: npx (after npm publish)
+
+```bash
+npx @quad/suma-mcp --key=sk_live_xxx
+```
+
+## IDE Configuration
+
+### Claude Code (.mcp.json)
+
+```json
+{
+  "mcpServers": {
+    "suma-memory": {
+      "command": "node",
+      "args": ["/path/to/quad-products/squad-suma-mcp/proxy/index.js"],
+      "env": {
+        "SUMA_API_KEY": "sk_live_xxx"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Settings → MCP → Add Server:
+- **Command**: `node /path/to/proxy/index.js`
+- **Environment**: `SUMA_API_KEY=sk_live_xxx`
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `suma_ping` | Health check — verify connection |
+| `suma_ingest` | Add knowledge to graph |
+| `suma_search` | Search with Gravity Well Algorithm |
+| `suma_talk` | Bidirectional memory (search + learn) |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SUMA_API_KEY` | Your SUMA API key (required) | — |
+| `SUMA_API_URL` | API endpoint | `https://sumapro-web-xxx.run.app` |
+
+## Architecture
+
+This is **v1.0 (Dumb Pipe)** — a simple MCP-to-REST translator.
+
+**v1.1 (Smart Proxy)** will add:
+- Local SQLite cache for zero-latency queries
+- Offline mode with sync-on-reconnect
+- Same architecture as SQUAD-Companion Flutter app
+
+See `quad-docs/QUAD-ARCHITECTURE-MCP-PROXY.md` for full design.
+
+## License
+
+MIT - Suman Addanke / A2 Vibe Creators LLC

package/index.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * SUMA MCP Local Proxy v1.0
+ *
+ * Architect Ruling (Apr 2, 2026):
+ *   MCP is designed for local/stdio use, not resilient cloud APIs.
+ *   This proxy runs locally, maintains stable stdio connection to IDE,
+ *   and translates MCP tool calls to stateless REST API calls.
+ *
+ * Usage:
+ *   SUMA_API_KEY=sk_live_xxx node index.js
+ *
+ * Or via npx (after npm publish):
+ *   npx @quad/suma-mcp --key=sk_live_xxx
+ *
+ * (c) 2026 Suman Addanke / A2 Vibe Creators LLC
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+const SUMA_API_URL = process.env.SUMA_API_URL || "https://sumapro-web-643846995630.us-central1.run.app";
+const API_KEY = process.env.SUMA_API_KEY || parseArgs().key;
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--key" && args[i + 1]) {
+      result.key = args[i + 1];
+      i++;
+    } else if (args[i].startsWith("--key=")) {
+      result.key = args[i].split("=")[1];
+    }
+  }
+  return result;
+}
+
+if (!API_KEY) {
+  console.error("ERROR: SUMA_API_KEY required");
+  console.error("Usage: SUMA_API_KEY=sk_live_xxx node index.js");
+  console.error("   or: node index.js --key=sk_live_xxx");
+  process.exit(1);
+}
+
+// ── REST API Client ─────────────────────────────────────────────────────────
+
+async function apiCall(endpoint, method = "GET", body = null) {
+  const url = `${SUMA_API_URL}/api${endpoint}`;
+  const options = {
+    method,
+    headers: {
+      "Authorization": `Bearer ${API_KEY}`,
+      "Content-Type": "application/json",
+    },
+  };
+
+  if (body && method !== "GET") {
+    options.body = JSON.stringify(body);
+  }
+
+  try {
+    const response = await fetch(url, options);
+    const data = await response.json();
+
+    if (!response.ok) {
+      return { error: data.error || `HTTP ${response.status}`, detail: data.detail };
+    }
+
+    return data;
+  } catch (err) {
+    return { error: "Network error", detail: err.message };
+  }
+}
+
+// ── Tool Definitions ────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: "suma_ping",
+    description: "Health check — verify connection and org. Call once at session start.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+    },
+  },
+  {
+    name: "suma_ingest",
+    description: `Add knowledge to the SUMA graph.
+
+[SYSTEM INSTRUCTION]: Do NOT pass raw massive text. You are the cognitive processor.
+Extract core facts into compressed semantic summaries before ingesting.
+
+Args:
+  text: The compressed knowledge to store (required)
+  sphere: Category - family, work, friends, health, architecture (optional, auto-classified)
+  extract_relationships: Auto-extract entities (default: true)`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "The knowledge to store" },
+        sphere: { type: "string", description: "Category (auto-classified if omitted)" },
+        extract_relationships: { type: "boolean", description: "Extract entities (default: true)" },
+      },
+      required: ["text"],
+    },
+  },
+  {
+    name: "suma_search",
+    description: `Search the knowledge graph using Gravity Well Algorithm.
+
+Phases:
+  1. Entity Strike — find entity by name
+  2. Neighborhood Expansion — get relationships
+  3. Evidence Bridge — get related nodes
+  4. GIN Fallback — full-text search
+
+Args:
+  query: Natural language query (required)
+  limit: Max results (default: 10)
+  sphere: Filter by category (optional)`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Natural language query" },
+        limit: { type: "integer", description: "Max results (default: 10)" },
+        sphere: { type: "string", description: "Filter by sphere" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "suma_talk",
+    description: `Bidirectional memory — search AND learn in one call.
+
+Searches for relevant context, optionally stores the message as new knowledge.
+
+Args:
+  message: User message (required)
+  learn: Store message as knowledge (default: true)
+  sphere: Category for storage (optional)`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: { type: "string", description: "User message" },
+        learn: { type: "boolean", description: "Store as knowledge (default: true)" },
+        sphere: { type: "string", description: "Category for storage" },
+      },
+      required: ["message"],
+    },
+  },
+];
+
+// ── Tool Handlers ───────────────────────────────────────────────────────────
+
+async function handleTool(name, args) {
+  switch (name) {
+    case "suma_ping":
+      return await apiCall("/ping", "GET");
+
+    case "suma_ingest":
+      return await apiCall("/ingest", "POST", {
+        text: args.text,
+        sphere: args.sphere || "default",
+        extract_relationships: args.extract_relationships !== false,
+      });
+
+    case "suma_search":
+      return await apiCall("/search", "POST", {
+        query: args.query,
+        limit: args.limit || 10,
+        sphere: args.sphere,
+      });
+
+    case "suma_talk":
+      return await apiCall("/talk", "POST", {
+        message: args.message,
+        learn: args.learn !== false,
+        sphere: args.sphere,
+      });
+
+    default:
+      return { error: `Unknown tool: ${name}` };
+  }
+}
+
+// ── MCP Server ──────────────────────────────────────────────────────────────
+
+const server = new Server(
+  {
+    name: "suma-mcp-proxy",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    const result = await handleTool(name, args || {});
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } catch (err) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: err.message }),
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// ── Start Server ────────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Log to stderr (stdout is for MCP protocol)
+  console.error(`SUMA MCP Proxy v1.0 started`);
+  console.error(`API: ${SUMA_API_URL}`);
+  console.error(`Org: Validating...`);
+
+  // Validate connection on startup
+  const ping = await apiCall("/ping", "GET");
+  if (ping.error) {
+    console.error(`ERROR: ${ping.error} - ${ping.detail || ""}`);
+  } else {
+    console.error(`Org ID: ${ping.org_id}, Tier: ${ping.tier}`);
+    console.error(`Ready.`);
+  }
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "suma-mcp-proxy",
+  "version": "1.0.0",
+  "description": "SUMA MCP Local Proxy — stable stdio bridge to stateless REST API",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "suma-mcp": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "suma",
+    "mcp",
+    "memory",
+    "ai",
+    "knowledge-graph",
+    "claude",
+    "cursor",
+    "llm"
+  ],
+  "author": "Suman Addanke <suman@quadframe.work>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quadframe/suma-mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}