ruflo 3.5.1 → 3.5.3

package/dist/rvf.manifest.json

@@ -0,0 +1,295 @@
+{
+  "rvf_version": "2.0",
+  "format": "rvf-package",
+  "name": "chat-ui-mcp",
+  "version": "2.0.0",
+  "description": "White-label AI Chat UI with MCP tool groups \u2014 per-group toggleable MCP servers, multi-provider AI proxy, deployable to Google Cloud Run or Docker Compose",
+  "license": "MIT",
+  "segments": {
+    "MANIFEST": {
+      "type": "root",
+      "uuid": "a7384d49-19c6-4943-949c-b12897ea3887",
+      "created": "2026-03-05T02:55:15Z",
+      "parent": null
+    },
+    "PROFILE": {
+      "type": "domain-config",
+      "description": "Deployment configuration \u2014 all secrets via environment variables",
+      "config_schema": "config/config.example.json",
+      "env_schema": ".env.example"
+    },
+    "WASM": {
+      "type": "runtime",
+      "description": "MCP Bridge v2.0 \u2014 per-group MCP endpoints, multi-provider AI proxy, error normalization",
+      "entrypoint": "mcp-bridge/index.js",
+      "runtime": "node:20",
+      "port": 3001
+    },
+    "META_IDX": {
+      "type": "metadata",
+      "components": [
+        {
+          "name": "mcp-bridge",
+          "type": "service",
+          "description": "Per-group MCP JSON-RPC server + OpenAI-compatible chat proxy with upstream error normalization",
+          "dockerfile": "mcp-bridge/Dockerfile",
+          "port": 3001,
+          "env_vars": [
+            "OPENAI_API_KEY",
+            "GOOGLE_API_KEY",
+            "OPENROUTER_API_KEY",
+            "ANTHROPIC_API_KEY",
+            "SEARCH_API_URL",
+            "RESEARCH_API_URL",
+            "MCP_GROUP_INTELLIGENCE",
+            "MCP_GROUP_AGENTS",
+            "MCP_GROUP_MEMORY",
+            "MCP_GROUP_DEVTOOLS",
+            "MCP_GROUP_SECURITY",
+            "MCP_GROUP_BROWSER",
+            "MCP_GROUP_NEURAL",
+            "MCP_GROUP_AGENTIC_FLOW",
+            "MCP_GROUP_CLAUDE_CODE",
+            "MCP_GROUP_GEMINI",
+            "MCP_GROUP_CODEX"
+          ]
+        },
+        {
+          "name": "chat-ui",
+          "type": "service",
+          "description": "HuggingFace Chat UI with branded assets, OIDC auth, and per-group MCP server toggles",
+          "dockerfile": "chat-ui/Dockerfile",
+          "base_image": "ghcr.io/huggingface/chat-ui-db:latest",
+          "port": 3000,
+          "env_vars": [
+            "MONGODB_URL",
+            "PUBLIC_APP_NAME",
+            "PUBLIC_ORIGIN",
+            "OPENID_PROVIDER_URL",
+            "OPENID_CLIENT_ID",
+            "OPENID_CLIENT_SECRET",
+            "MCP_SERVERS"
+          ]
+        },
+        {
+          "name": "mongodb",
+          "type": "datastore",
+          "description": "MongoDB for conversation persistence",
+          "image": "mongo:7",
+          "port": 27017
+        }
+      ]
+    },
+    "TOOL_GROUPS": {
+      "type": "mcp-groups",
+      "description": "Each group exposes a separate MCP endpoint at /mcp/{group} \u2014 toggleable in Chat UI",
+      "groups": {
+        "core": {
+          "enabled_by_default": true,
+          "display_name": "Core Tools",
+          "endpoint": "/mcp/core",
+          "description": "Built-in guidance, help, and utility tools",
+          "source": "builtin"
+        },
+        "intelligence": {
+          "enabled_by_default": true,
+          "display_name": "Intelligence & Learning",
+          "endpoint": "/mcp/intelligence",
+          "description": "Hooks, learning, trajectory, neural pattern tools",
+          "source": "ruvector",
+          "prefixes": [
+            "hooks_"
+          ]
+        },
+        "agents": {
+          "enabled_by_default": true,
+          "display_name": "Agents & Orchestration",
+          "endpoint": "/mcp/agents",
+          "description": "Agent spawn, swarm, hive-mind, task orchestration",
+          "source": "ruflo",
+          "prefixes": [
+            "agent_",
+            "swarm_",
+            "hive_",
+            "task_"
+          ]
+        },
+        "memory": {
+          "enabled_by_default": true,
+          "display_name": "Memory & Knowledge",
+          "endpoint": "/mcp/memory",
+          "description": "Memory store/search/retrieve, embeddings, session",
+          "source": "ruflo",
+          "prefixes": [
+            "memory_",
+            "embedding_",
+            "session_"
+          ]
+        },
+        "devtools": {
+          "enabled_by_default": true,
+          "display_name": "Dev Tools & Analysis",
+          "endpoint": "/mcp/devtools",
+          "description": "Performance, security, deployment, config, doctor tools",
+          "source": "ruflo",
+          "prefixes": [
+            "perf_",
+            "security_",
+            "deploy_",
+            "config_",
+            "doctor_",
+            "plugin_",
+            "workflow_",
+            "provider_"
+          ]
+        },
+        "security": {
+          "enabled_by_default": false,
+          "display_name": "Security & Safety",
+          "endpoint": "/mcp/security",
+          "description": "Security scanning, CVE detection, threat analysis",
+          "source": "ruflo",
+          "prefixes": [
+            "security_"
+          ]
+        },
+        "browser": {
+          "enabled_by_default": false,
+          "display_name": "Browser Automation",
+          "endpoint": "/mcp/browser",
+          "description": "Headless browser \u2014 navigate, click, fill, screenshot",
+          "source": "ruflo",
+          "prefixes": [
+            "browser_"
+          ]
+        },
+        "neural": {
+          "enabled_by_default": false,
+          "display_name": "Neural & DAA",
+          "endpoint": "/mcp/neural",
+          "description": "Neural training, DAA autonomous agents",
+          "source": "ruflo",
+          "prefixes": [
+            "neural_",
+            "daa_"
+          ]
+        },
+        "agentic-flow": {
+          "enabled_by_default": false,
+          "display_name": "Agentic Flow",
+          "endpoint": "/mcp/agentic-flow",
+          "description": "agentic-flow alpha integration",
+          "source": "agentic-flow"
+        },
+        "claude-code": {
+          "enabled_by_default": false,
+          "display_name": "Claude Code",
+          "endpoint": "/mcp/claude-code",
+          "description": "Claude Code CLI tools",
+          "source": "claude-code"
+        },
+        "gemini": {
+          "enabled_by_default": false,
+          "display_name": "Gemini",
+          "endpoint": "/mcp/gemini",
+          "description": "Google Gemini native tools",
+          "source": "gemini"
+        },
+        "codex": {
+          "enabled_by_default": false,
+          "display_name": "Codex",
+          "endpoint": "/mcp/codex",
+          "description": "OpenAI Codex tools",
+          "source": "codex"
+        }
+      }
+    },
+    "OVERLAY": {
+      "type": "customization",
+      "description": "Brand-specific overlays",
+      "assets": [
+        "chat-ui/static/chatui/omni-welcome.gif",
+        "chat-ui/static/chatui/icon-144x144.png"
+      ],
+      "generators": [
+        {
+          "name": "welcome-gif",
+          "script": "scripts/generate-welcome.js",
+          "config_key": "brand.welcomeColors",
+          "output": "chat-ui/static/chatui/omni-welcome.gif"
+        }
+      ]
+    },
+    "CRYPTO": {
+      "type": "security",
+      "description": "Security configuration with private network MCP tunnel",
+      "secrets_management": "gcp-secret-manager",
+      "auth_protocol": "openid-connect",
+      "no_embedded_secrets": true,
+      "private_tunnel": {
+        "protocol": "http",
+        "scope": "docker-network-only",
+        "patch": "chat-ui/patch-mcp-url-safety.sh",
+        "adr": "docs/adr/ADR-032-RVF-PRIVATE-MCP-TUNNEL.md"
+      },
+      "env_only_keys": [
+        "OPENAI_API_KEY",
+        "GOOGLE_API_KEY",
+        "OPENROUTER_API_KEY",
+        "ANTHROPIC_API_KEY",
+        "OPENID_CLIENT_SECRET"
+      ]
+    }
+  },
+  "deployment": {
+    "platforms": [
+      "google-cloud-run",
+      "docker-compose",
+      "kubernetes"
+    ],
+    "infrastructure": {
+      "mcp_bridge": {
+        "memory": "512Mi",
+        "cpu": 1,
+        "min_instances": 0,
+        "max_instances": 5,
+        "timeout": 300
+      },
+      "chat_ui": {
+        "memory": "2Gi",
+        "cpu": 2,
+        "min_instances": 1,
+        "max_instances": 10,
+        "timeout": 300
+      }
+    }
+  },
+  "capabilities": {
+    "mcp_protocol": "2024-11-05",
+    "mcp_tool_groups": true,
+    "per_group_mcp_endpoints": true,
+    "chat_completions_proxy": true,
+    "upstream_error_normalization": true,
+    "goap_search_pipeline": true,
+    "multi_provider_routing": [
+      "openai",
+      "gemini",
+      "openrouter"
+    ],
+    "oidc_auth": true,
+    "branded_assets": true,
+    "tool_extensibility": true,
+    "ruvector_integration": true,
+    "ruflo_integration": true,
+    "agentic_flow_integration": true,
+    "external_mcp_backends": [
+      "ruvector",
+      "ruflo",
+      "agentic-flow",
+      "claude-code",
+      "gemini",
+      "codex"
+    ],
+    "test_harness": true
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruflo",
-  "version": "3.5.1",
+  "version": "3.5.3",
   "description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "bin/ruflo.js",
   "type": "module",
@@ -18,11 +18,25 @@
   },
   "files": [
     "bin/**",
+    "src/**",
+    "dist/**",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "preinstall": "node -e \"var f=require('fs'),p=require('path'),o=require('os'),h=o.homedir(),d=p.join(h,'.npm','_npx');try{if(f.existsSync(d))f.readdirSync(d).forEach(function(x){var nm=p.join(d,x,'node_modules');try{if(f.existsSync(nm))f.readdirSync(nm).forEach(function(e){if(e.charAt(0)==='.'&&e.indexOf('-')>0&&/[A-Za-z]{8}/.test(e)){try{var t=p.join(nm,e);if(f.statSync(t).isDirectory())f.rmSync(t,{recursive:true,force:true})}catch(x){}}})}catch(x){}})}catch(x){}try{var ci=p.join(h,'.npm','_cacache','index-v5');if(f.existsSync(ci)){(function walk(dir){f.readdirSync(dir).forEach(function(e){var fp=p.join(dir,e);try{if(f.statSync(fp).isDirectory())walk(fp);else{var c=f.readFileSync(fp,'utf-8');if(c.indexOf('claude-flow')!==-1||c.indexOf('ruflo')!==-1)f.unlinkSync(fp)}}catch(x){}});})(ci)}}catch(x){}\" || true"
+    "dev": "node src/mcp-bridge/index.js",
+    "dev:bridge": "node --watch src/mcp-bridge/index.js",
+    "dev:test": "node src/mcp-bridge/test-harness.js",
+    "start": "node src/mcp-bridge/index.js",
+    "docker:up": "docker compose up -d",
+    "docker:down": "docker compose down",
+    "docker:build": "docker compose build",
+    "docker:logs": "docker compose logs -f",
+    "install:bridge": "cd src/mcp-bridge && npm install",
+    "generate:config": "node src/scripts/generate-config.js",
+    "generate:welcome": "node src/scripts/generate-welcome.js",
+    "deploy": "bash src/scripts/deploy.sh",
+    "package:rvf": "bash src/scripts/package-rvf.sh"
   },
   "dependencies": {
     "@claude-flow/cli": ">=3.0.0-alpha.1"

package/src/chat-ui/Dockerfile

@@ -0,0 +1,25 @@
+FROM ghcr.io/huggingface/chat-ui-db:latest
+
+# Switch to root for patching and file operations
+USER root
+
+# Bake .env.local with MODELS config (too large for Cloud Run env vars)
+COPY dotenv-local.txt /app/.env.local
+
+# RVF Security Patch — allow private Docker network MCP connections.
+# HF Chat UI enforces HTTPS for MCP URLs (SSRF protection).
+# In containerized deployments, MCP bridge runs on private Docker network.
+# This patch allows HTTP for admin-configured MCP_SERVERS only.
+COPY patch-mcp-url-safety.sh /tmp/patch-mcp-url-safety.sh
+RUN sh /tmp/patch-mcp-url-safety.sh && rm /tmp/patch-mcp-url-safety.sh
+
+# Copy branded welcome GIF into the SvelteKit static asset directory.
+COPY static/chatui/omni-welcome.gif /app/build/client/chatui/omni-welcome.gif
+COPY static/chatui/omni-welcome.gif /app/static/chatui/omni-welcome.gif
+
+# Copy PWA icon (fixes 404 for /chat/chatui/icon-144x144.png)
+COPY static/chatui/icon-144x144.png /app/build/client/chatui/icon-144x144.png
+COPY static/chatui/icon-144x144.png /app/static/chatui/icon-144x144.png
+
+# Switch back to non-root user
+USER 1000

package/src/chat-ui/patch-mcp-url-safety.sh

@@ -0,0 +1,28 @@
+#!/bin/sh
+# RVF Security Patch — Allow private network MCP connections
+#
+# HF Chat UI enforces HTTPS-only for MCP server URLs to prevent SSRF.
+# In containerized deployments, MCP servers run on the private Docker
+# network (not exposed to the internet). This patch allows HTTP for
+# admin-configured MCP_SERVERS URLs while maintaining SSRF protection
+# for user-provided URLs.
+#
+# Security model:
+#   - MCP_SERVERS is set by the deployment admin (env var / .env.local)
+#   - Private Docker network is not accessible from the internet
+#   - The patch only relaxes protocol check, not IP safety checks
+
+URLSAFETY_FILE=$(find /app/build/server -name "urlSafety-*.js" | head -1)
+
+if [ -z "$URLSAFETY_FILE" ]; then
+  echo "[rvf-patch] urlSafety file not found, skipping"
+  exit 0
+fi
+
+# Allow http: protocol in addition to https:
+sed -i 's/if (url\.protocol !== "https:")/if (url.protocol !== "https:" \&\& url.protocol !== "http:")/' "$URLSAFETY_FILE"
+
+# Allow localhost for container-internal MCP servers
+sed -i 's/if (hostname === "localhost")/if (false \&\& hostname === "localhost")/' "$URLSAFETY_FILE"
+
+echo "[rvf-patch] Patched $URLSAFETY_FILE for private network MCP"

package/src/config/config.example.json

@@ -0,0 +1,76 @@
+{
+  "brand": {
+    "name": "My AI Assistant",
+    "description": "AI-powered assistant for your business",
+    "domain": "chat.example.com",
+    "welcomeColors": {
+      "background": "#0d0d1a",
+      "primary": "#06b6d4",
+      "secondary": "#3b82f6",
+      "accent": "#6366f1"
+    }
+  },
+  "gcp": {
+    "projectId": "my-gcp-project",
+    "region": "us-central1",
+    "vpcConnector": "",
+    "serviceName": {
+      "chatUi": "chat-ui",
+      "mcpBridge": "mcp-bridge"
+    }
+  },
+  "auth": {
+    "enabled": true,
+    "provider": "google",
+    "clientId": "",
+    "clientSecretName": "google-client-secret",
+    "scopes": "openid profile email",
+    "nameClaim": "name"
+  },
+  "models": [
+    {
+      "name": "gemini-2.5-pro",
+      "displayName": "Gemini 2.5 Pro (Default)",
+      "description": "Google's most capable deep thinking model",
+      "provider": "gemini",
+      "supportsTools": true
+    },
+    {
+      "name": "gemini-2.5-flash",
+      "displayName": "Gemini 2.5 Flash",
+      "description": "Fast Google model with thinking",
+      "provider": "gemini",
+      "supportsTools": true
+    },
+    {
+      "name": "gpt-4.1",
+      "displayName": "GPT-4.1",
+      "description": "OpenAI's latest flagship model (2026)",
+      "provider": "openai",
+      "multimodal": true,
+      "supportsTools": true
+    },
+    {
+      "name": "gpt-4.1-mini",
+      "displayName": "GPT-4.1 Mini",
+      "description": "Fast and affordable OpenAI model",
+      "provider": "openai",
+      "supportsTools": true
+    },
+    {
+      "name": "o3-mini",
+      "displayName": "o3-mini (Reasoning)",
+      "description": "OpenAI reasoning model for complex tasks",
+      "provider": "openai",
+      "supportsTools": true
+    }
+  ],
+  "secrets": {
+    "openaiApiKey": "openai-api-key",
+    "googleApiKey": "google-api-key",
+    "openrouterApiKey": "openrouter-api-key"
+  },
+  "tools": [],
+  "cloudFunctions": {},
+  "systemPrompt": "You are an intelligent AI assistant with powerful tools organized into 5 groups. You MUST use tools proactively — never ask permission, never guess answers from general knowledge.\n\nIMPORTANT: Call `guidance` with topic='overview' if you are ever unsure which tool to use. It will tell you exactly what is available and how to use it.\n\n# Tool Groups\n\nYour tools are organized into groups. Each tool name is prefixed with its backend (e.g., `ruflo__agent_spawn`, `ruvector__hooks_route`). Always use the full prefixed name.\n\n## Group 1: Core Tools\nBuilt-in tools always available.\n\n- **search** — Search the knowledge base for documents, procedures, how-tos. ALWAYS search before answering knowledge questions.\n- **web_research** — Web search, deep research, comparisons, fact-checking.\n  - Actions: `search` (quick), `research` (deep report), `compare` (side-by-side), `fact_check` (verify), `goap` (comprehensive multi-step — BEST for important questions)\n- **guidance** — Get help on any tool group, specific tool usage, or capabilities overview.\n  - Topics: `overview`, `groups`, `agents`, `memory`, `intelligence`, `devtools`\n  - For specific tool: `guidance(topic='tool', tool_name='ruflo__agent_spawn')`\n\n## Group 2: Intelligence & Learning (ruvector)\nPattern learning, routing, code analysis, and trajectory tracking.\n\n### Key tools:\n- **ruvector__hooks_route** — Route a task to the optimal agent type. Call this FIRST for complex tasks to get agent recommendations.\n  - `{\"task\": \"describe what needs to be done\", \"context\": [\"relevant info\"]}`\n- **ruvector__hooks_remember** — Store a key-value pair in persistent memory for cross-session recall.\n  - `{\"key\": \"pattern-name\", \"value\": \"what to remember\", \"namespace\": \"patterns\"}`\n- **ruvector__hooks_recall** — Retrieve a previously stored memory by key.\n  - `{\"key\": \"pattern-name\", \"namespace\": \"patterns\"}`\n- **ruvector__hooks_trajectory_begin** — Start tracking a multi-step task for learning.\n- **ruvector__hooks_trajectory_step** — Record a step in the current trajectory.\n- **ruvector__hooks_trajectory_end** — End trajectory, triggering pattern extraction.\n- **ruvector__hooks_ast_analyze** — Analyze code structure (AST) of a file.\n- **ruvector__hooks_ast_complexity** — Get complexity metrics for code.\n- **ruvector__hooks_diff_analyze** — Analyze a code diff for risk and impact.\n- **ruvector__hooks_security_scan** — Scan code for security vulnerabilities.\n- **ruvector__hooks_rag_context** — Get RAG context for a query from stored knowledge.\n- **ruvector__hooks_learn** — Force the system to learn from provided examples.\n- **ruvector__hooks_compress** — Compress/summarize long text for efficient storage.\n- **ruvector__hooks_swarm_recommend** — Get swarm topology recommendation for a task.\n- **ruvector__hooks_suggest_context** — Get contextual suggestions based on current work.\n- **ruvector__hooks_capabilities** — List all intelligence system capabilities.\n- **ruvector__hooks_stats** — View learning statistics and metrics.\n- **ruvector__hooks_doctor** — Run diagnostics on the intelligence system.\n\n### When to use Intelligence tools:\n- Before starting complex work → `ruvector__hooks_route` to find the best approach\n- To remember solutions for later → `ruvector__hooks_remember`\n- For code analysis → `ruvector__hooks_ast_analyze`, `ruvector__hooks_security_scan`\n- To track multi-step work → trajectory_begin/step/end\n\n## Group 3: Agents & Orchestration (ruflo)\nSpawn agents, coordinate swarms, manage tasks and workflows.\n\n### Agent Management:\n- **ruflo__agent_spawn** — Create a new specialized agent.\n  - `{\"type\": \"coder|researcher|tester|reviewer|architect|security\", \"name\": \"optional-name\"}`\n  - Agent types: `coder` (writes code), `researcher` (finds information), `tester` (writes tests), `reviewer` (reviews code), `architect` (designs systems), `security` (audits security)\n- **ruflo__agent_status** — Check an agent's current state. `{\"agentId\": \"agent-xxx\"}`\n- **ruflo__agent_list** — List all active agents.\n- **ruflo__agent_terminate** — Stop an agent. `{\"agentId\": \"agent-xxx\"}`\n- **ruflo__agent_health** — Health check across all agents.\n\n### Swarm Coordination:\n- **ruflo__swarm_init** — Initialize a multi-agent swarm.\n  - `{\"topology\": \"hierarchical|mesh|ring|star\", \"maxAgents\": 8, \"strategy\": \"balanced|specialized|adaptive\"}`\n  - Use `hierarchical` for coordinated teams, `mesh` for peer-to-peer collaboration\n- **ruflo__swarm_status** — Get swarm health and agent states.\n- **ruflo__swarm_shutdown** — Tear down a swarm.\n\n### Task Management:\n- **ruflo__task_create** — Create a tracked task.\n  - `{\"description\": \"what needs to be done\", \"priority\": \"low|normal|high|critical\"}`\n- **ruflo__task_status** — Check task progress. `{\"taskId\": \"task-xxx\"}`\n- **ruflo__task_list** — List all tasks with their statuses.\n- **ruflo__task_complete** — Mark a task as done. `{\"taskId\": \"task-xxx\"}`\n- **ruflo__task_update** — Update task details or status.\n\n### Workflow Orchestration:\n- **ruflo__workflow_create** — Define a multi-step workflow.\n  - `{\"name\": \"workflow-name\", \"steps\": [{\"name\": \"step1\", \"tool\": \"tool-name\", \"args\": {}}]}`\n- **ruflo__workflow_execute** — Run a workflow. `{\"workflowId\": \"wf-xxx\"}`\n- **ruflo__workflow_status** — Check workflow progress.\n- **ruflo__workflow_template** — Use a pre-built workflow template.\n\n### Hive-Mind (Multi-Agent Consensus):\n- **ruflo__hive-mind_init** — Start distributed consensus system.\n- **ruflo__hive-mind_spawn** — Add an agent to the hive.\n- **ruflo__hive-mind_consensus** — Run consensus vote across agents.\n- **ruflo__hive-mind_broadcast** — Send message to all hive agents.\n\n### Coordination:\n- **ruflo__coordination_topology** — View/change coordination topology.\n- **ruflo__coordination_load_balance** — Distribute work across agents.\n- **ruflo__coordination_orchestrate** — Orchestrate complex multi-agent tasks.\n\n### When to use Agent tools:\n- Complex tasks needing multiple perspectives → spawn a swarm\n- Code implementation → `ruflo__agent_spawn({\"type\": \"coder\"})`\n- Research tasks → `ruflo__agent_spawn({\"type\": \"researcher\"})`\n- Track progress → create tasks, update status\n- Multi-step processes → create and execute workflows\n\n## Group 4: Memory & Knowledge (ruflo)\nPersistent memory, vector search, embeddings, and pattern storage.\n\n### Memory Operations:\n- **ruflo__memory_store** — Store data in persistent memory.\n  - `{\"key\": \"my-key\", \"value\": \"data to store\", \"namespace\": \"default\", \"tags\": [\"tag1\"]}`\n- **ruflo__memory_retrieve** — Get stored data by key.\n  - `{\"key\": \"my-key\", \"namespace\": \"default\"}`\n- **ruflo__memory_search** — Semantic vector search across all stored memories.\n  - `{\"query\": \"what to search for\", \"limit\": 5, \"namespace\": \"default\"}`\n- **ruflo__memory_list** — List all stored keys in a namespace.\n- **ruflo__memory_delete** — Remove a stored memory.\n- **ruflo__memory_stats** — View memory usage statistics.\n\n### Embeddings:\n- **ruflo__embeddings_generate** — Generate vector embeddings for text.\n- **ruflo__embeddings_compare** — Compare semantic similarity of two texts.\n- **ruflo__embeddings_search** — Search embeddings database.\n\n### AgentDB (Advanced Pattern Storage):\n- **ruflo__agentdb_pattern-store** — Store a learned pattern with metadata.\n  - `{\"pattern\": \"description\", \"category\": \"code|debug|architecture\", \"confidence\": 0.9}`\n- **ruflo__agentdb_pattern-search** — Search patterns by similarity.\n  - `{\"query\": \"search terms\", \"limit\": 5}`\n- **ruflo__agentdb_route** — Route a query to the most relevant stored pattern.\n- **ruflo__agentdb_feedback** — Provide feedback on a pattern (reinforcement learning).\n- **ruflo__agentdb_context-synthesize** — Synthesize context from multiple sources.\n- **ruflo__agentdb_semantic-route** — Semantic routing based on stored knowledge.\n- **ruflo__agentdb_consolidate** — Consolidate and deduplicate stored patterns.\n\n### When to use Memory tools:\n- Storing information for later → `ruflo__memory_store`\n- Finding relevant past knowledge → `ruflo__memory_search`\n- Building a knowledge base → store patterns in AgentDB\n- Comparing concepts → `ruflo__embeddings_compare`\n\n## Group 5: Dev Tools & Analysis (ruflo)\nPerformance, system health, GitHub integration, code analysis, and terminal access.\n\n### System & Performance:\n- **ruflo__system_status** — System health overview.\n- **ruflo__system_metrics** — Detailed performance metrics.\n- **ruflo__performance_report** — Generate performance report.\n- **ruflo__performance_bottleneck** — Identify performance bottlenecks.\n- **ruflo__performance_benchmark** — Run benchmarks.\n- **ruflo__performance_optimize** — Get optimization recommendations.\n\n### Code Analysis:\n- **ruflo__analyze_diff** — Analyze a code diff.\n- **ruflo__analyze_diff-risk** — Assess risk level of changes.\n- **ruflo__analyze_diff-classify** — Classify type of changes (feature, bugfix, refactor).\n- **ruflo__analyze_diff-reviewers** — Suggest code reviewers.\n- **ruflo__analyze_file-risk** — Assess risk of a specific file.\n\n### GitHub Integration:\n- **ruflo__github_repo_analyze** — Analyze a GitHub repository.\n- **ruflo__github_pr_manage** — Manage pull requests.\n- **ruflo__github_issue_track** — Track and manage issues.\n- **ruflo__github_workflow** — Manage GitHub Actions workflows.\n- **ruflo__github_metrics** — Repository metrics and insights.\n\n### Terminal:\n- **ruflo__terminal_create** — Create a terminal session.\n- **ruflo__terminal_execute** — Execute a command. `{\"command\": \"ls -la\", \"terminalId\": \"term-xxx\"}`\n- **ruflo__terminal_list** — List active terminals.\n- **ruflo__terminal_history** — View command history.\n\n### Development Hooks:\n- **ruflo__hooks_pre-task** / **ruflo__hooks_post-task** — Task lifecycle hooks.\n- **ruflo__hooks_pre-edit** / **ruflo__hooks_post-edit** — File edit hooks.\n- **ruflo__hooks_session-start** / **ruflo__hooks_session-end** — Session lifecycle.\n- **ruflo__hooks_worker-dispatch** — Dispatch background workers.\n  - Workers: `optimize`, `audit`, `testgaps`, `document`, `map`, `deepdive`, `benchmark`\n- **ruflo__hooks_intelligence** — Access intelligence subsystem.\n- **ruflo__hooks_model-route** — Route to optimal AI model for a task.\n\n### Progress Tracking:\n- **ruflo__progress_check** — Check implementation progress.\n- **ruflo__progress_summary** — Summarize overall progress.\n- **ruflo__progress_watch** — Monitor progress in real-time.\n\n# Decision Framework\n\nWhen the user asks you something, follow this decision tree:\n\n1. **Knowledge question** (\"how do I...\", \"what is...\", \"explain...\") → `search` first, then `web_research` if not found locally\n2. **Research request** (\"look up\", \"compare\", \"find out\") → `web_research` with appropriate action\n3. **Code task** (\"write\", \"fix\", \"refactor\", \"implement\") → `ruvector__hooks_route` to find best approach, then spawn agents\n4. **Analysis request** (\"analyze\", \"review\", \"audit\") → use analysis tools + spawn reviewer/security agents\n5. **Multi-step project** → create tasks, spawn swarm, coordinate with workflows\n6. **Memory/recall** (\"remember\", \"save\", \"what did we...\") → memory_store/retrieve/search\n7. **System question** (\"what tools\", \"help\", \"status\") → `guidance` or `ruflo__system_status`\n\n# Parallel Execution\n\nWhen multiple independent tools can answer a question, call them ALL in parallel:\n- Research + Search simultaneously\n- Spawn multiple agents at once\n- Run analysis tools in parallel\n\nNever call tools sequentially when they could run in parallel.\n\n# Response Rules\n\n1. **Call tools FIRST**, then present results conversationally — NEVER show raw JSON\n2. Use markdown formatting: **bold** headers, bullet points, tables for comparisons\n3. Synthesize tool results naturally — be a helpful colleague, not a data pipe\n4. Cite sources when available\n5. If a tool fails or returns no results, say so honestly and try an alternative\n6. For complex tasks, outline your plan before executing\n7. After completing work, suggest relevant follow-up actions\n\n# Never Include\n\nSimilarity scores, chunk IDs, function names, API endpoints, raw JSON, internal IDs, references to \"MCP\", \"tool calls\", \"vectors\", \"embeddings\", or internal infrastructure. Present results as a knowledgeable assistant would."
+}

package/src/mcp-bridge/Dockerfile

@@ -0,0 +1,45 @@
+FROM node:20-slim
+
+WORKDIR /app
+
+COPY package.json ./
+RUN npm install --production
+
+# Pre-install MCP backends for faster startup (avoids npx download on first call)
+# Each installed separately so one failure doesn't block others
+RUN npm install -g ruvector || true
+RUN npm install -g ruflo || true
+RUN npm install -g agentic-flow@alpha || true
+RUN npm install -g gemini-mcp-server || true
+RUN npm install -g @openai/codex || true
+
+COPY index.js ./
+COPY mcp-stdio-kernel.js ./
+
+# Create writable directories for MCP backends (ruflo, ruvector, agentic-flow)
+# These tools write state/tasks/memory to the working directory at runtime
+RUN mkdir -p /app/.claude-flow/tasks /app/.claude-flow/memory /app/.claude-flow/sessions \
+    /app/.claude-flow/agents /app/.claude-flow/config /app/.claude-flow/data \
+    /app/.claude-flow/logs /app/.claude-flow/swarm \
+    && chown -R node:node /app/.claude-flow
+
+USER node
+
+EXPOSE 3001
+
+ENV PORT=3001
+# Default-on tool groups
+ENV MCP_GROUP_INTELLIGENCE=true
+ENV MCP_GROUP_AGENTS=true
+ENV MCP_GROUP_MEMORY=true
+ENV MCP_GROUP_DEVTOOLS=true
+# Opt-in tool groups
+ENV MCP_GROUP_SECURITY=false
+ENV MCP_GROUP_BROWSER=false
+ENV MCP_GROUP_NEURAL=false
+ENV MCP_GROUP_AGENTIC_FLOW=false
+ENV MCP_GROUP_CLAUDE_CODE=false
+ENV MCP_GROUP_GEMINI=false
+ENV MCP_GROUP_CODEX=false
+
+CMD ["node", "index.js"]