feat: mesh services platform — deploy MCP servers, vaults, scopes

Add the foundation for deploying and managing MCP servers on the VPS
broker, with per-peer credential vaults and visibility scopes.

Architecture:
- One Docker container per mesh with a Node supervisor
- Each MCP server runs as a child process with its own stdio pipe
- claudemesh launch installs native MCP entries in ~/.claude.json
- Mid-session deploys fall back to svc__* dynamic tools + list_changed

New components:
- DB: mesh.service + mesh.vault_entry tables, mesh.skill extensions
- Broker: 19 wire protocol types, 11 message handlers, service catalog
  in hello_ack with scope filtering, service-manager.ts (775 lines)
- CLI: 13 tool definitions, 12 WS client methods, tool call handlers,
  startServiceProxy() for native MCP proxy mode
- Launch: catalog fetch, native MCP entry install, stale sweep, cleanup,
  MCP_TIMEOUT=30s, MAX_MCP_OUTPUT_TOKENS=50k

Security: path sanitization on service names, column whitelist on
upsertService, returning()-based delete checks, vault E2E encryption.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

apps/cli/src/mcp/server.ts

@@ -22,7 +22,8 @@ import type {
   SetSummaryArgs,
   ListPeersArgs,
 } from "./types";
-import type { BrokerClient, InboundPush } from "../ws/client";
+import { BrokerClient } from "../ws/client";
+import type { InboundPush } from "../ws/client";
 
 /** Compute a human-readable relative time string from an ISO timestamp. */
 function relativeTime(isoStr: string): string {
@@ -144,6 +145,12 @@ function formatPush(p: InboundPush, meshSlug: string): string {
 }
 
 export async function startMcpServer(): Promise<void> {
+  // Check for --service mode (native mesh MCP proxy)
+  const serviceIdx = process.argv.indexOf("--service");
+  if (serviceIdx !== -1 && process.argv[serviceIdx + 1]) {
+    return startServiceProxy(process.argv[serviceIdx + 1]!);
+  }
+
   const config = loadConfig();
 
   const myName = config.displayName ?? "unnamed";
@@ -1533,3 +1540,182 @@ Your message mode is "${messageMode}".
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 }
+
+/**
+ * Mesh service proxy — a thin MCP server that proxies ONE deployed service.
+ *
+ * Spawned by Claude Code as a native MCP entry. Connects to the broker,
+ * fetches tool schemas for the named service, and routes tool calls.
+ *
+ * If the broker WS drops, the proxy waits for reconnection (up to 10s)
+ * before failing tool calls. If the proxy process itself crashes, Claude
+ * Code will not auto-restart it.
+ */
+async function startServiceProxy(serviceName: string): Promise<void> {
+  const config = loadConfig();
+  if (config.meshes.length === 0) {
+    process.stderr.write(`[mesh:${serviceName}] no meshes joined\n`);
+    process.exit(1);
+  }
+
+  const mesh = config.meshes[0]!;
+  const client = new BrokerClient(mesh, {
+    displayName: config.displayName ?? `proxy:${serviceName}`,
+  });
+
+  try {
+    await client.connect();
+  } catch (e) {
+    process.stderr.write(
+      `[mesh:${serviceName}] broker connect failed: ${e instanceof Error ? e.message : String(e)}\n`,
+    );
+    process.exit(1);
+  }
+
+  // Wait for hello_ack and service catalog
+  await new Promise((r) => setTimeout(r, 1500));
+
+  // Fetch tool schemas for this service
+  let tools: Array<{
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+  }> = [];
+  try {
+    const fetched = await client.getServiceTools(serviceName);
+    tools = fetched as typeof tools;
+  } catch {
+    // Try from catalog cache
+    const cached = client.serviceCatalog.find((s) => s.name === serviceName);
+    if (cached) {
+      tools = cached.tools as typeof tools;
+    }
+  }
+
+  if (tools.length === 0) {
+    process.stderr.write(
+      `[mesh:${serviceName}] no tools found — service may not be running\n`,
+    );
+  }
+
+  // Build MCP server
+  const server = new Server(
+    { name: `mesh:${serviceName}`, version: "0.1.0" },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: tools.map((t) => ({
+      name: t.name,
+      description: `[mesh:${serviceName}] ${t.description}`,
+      inputSchema: t.inputSchema as any,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const toolName = req.params.name;
+    const args = req.params.arguments ?? {};
+
+    // Wait for broker reconnection if needed
+    if (client.status !== "open") {
+      let waited = 0;
+      while (client.status !== "open" && waited < 10_000) {
+        await new Promise((r) => setTimeout(r, 500));
+        waited += 500;
+      }
+      if (client.status !== "open") {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Service temporarily unavailable — broker reconnecting. Retry in a few seconds.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+
+    try {
+      const result = await client.mcpCall(
+        serviceName,
+        toolName,
+        args as Record<string, unknown>,
+      );
+      if (result.error) {
+        return {
+          content: [{ type: "text" as const, text: `Error: ${result.error}` }],
+          isError: true,
+        };
+      }
+      const resultText =
+        typeof result.result === "string"
+          ? result.result
+          : JSON.stringify(result.result, null, 2);
+      return {
+        content: [{ type: "text" as const, text: resultText }],
+      };
+    } catch (e) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Call failed: ${e instanceof Error ? e.message : String(e)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  // Listen for service events (undeploy, update)
+  client.onPush((push) => {
+    if (
+      push.event === "mcp_undeployed" &&
+      (push.eventData as any)?.name === serviceName
+    ) {
+      process.stderr.write(
+        `[mesh:${serviceName}] service undeployed — exiting\n`,
+      );
+      client.close();
+      process.exit(0);
+    }
+    if (
+      push.event === "mcp_updated" &&
+      (push.eventData as any)?.name === serviceName
+    ) {
+      // Refresh tools
+      const newTools = (push.eventData as any)?.tools;
+      if (Array.isArray(newTools)) {
+        tools = newTools;
+        // Notify Claude Code that tools changed
+        server
+          .notification({
+            method: "notifications/tools/list_changed",
+          })
+          .catch(() => {
+            /* ignore notification errors */
+          });
+      }
+    }
+  });
+
+  // Start stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Keep event loop alive
+  const keepalive = setInterval(() => {
+    // Intentionally empty — prevents event loop from settling.
+  }, 1_000);
+  void keepalive;
+
+  // Graceful shutdown
+  const shutdown = (): void => {
+    clearInterval(keepalive);
+    client.close();
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}

apps/cli/src/mcp/tools.ts

@@ -893,4 +893,82 @@ export const TOOLS: Tool[] = [
       required: ["name"],
     },
   },
+
+  // --- Service deployment tools ---
+
+  {
+    name: "mesh_mcp_deploy",
+    description: "Deploy an MCP server to the mesh from a zip file or git repo. Runs on the broker VPS, persists across peer sessions. Default scope: private (only you).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        server_name: { type: "string", description: "Unique name for the server in this mesh" },
+        file_id: { type: "string", description: "File ID of uploaded zip (from share_file)" },
+        git_url: { type: "string", description: "Git repo URL" },
+        git_branch: { type: "string", description: "Branch to clone (default: main)" },
+        env: { type: "object", description: "Environment variables. Use $vault:<key> for vault secrets." },
+        runtime: { type: "string", enum: ["node", "python", "bun"], description: "Runtime (auto-detected if omitted)" },
+        memory_mb: { type: "number", description: "Memory limit in MB (default: 256)" },
+        network_allow: { type: "array", items: { type: "string" }, description: "Allowed outbound hosts (default: none)" },
+        scope: { description: "Visibility: 'peer' (default), 'mesh', or {group/groups/role/peers}" },
+      },
+      required: ["server_name"],
+    },
+  },
+  {
+    name: "mesh_mcp_undeploy",
+    description: "Stop and remove a managed MCP server from the mesh.",
+    inputSchema: { type: "object", properties: { server_name: { type: "string" } }, required: ["server_name"] },
+  },
+  {
+    name: "mesh_mcp_update",
+    description: "Pull latest code and restart a git-sourced MCP server.",
+    inputSchema: { type: "object", properties: { server_name: { type: "string" } }, required: ["server_name"] },
+  },
+  {
+    name: "mesh_mcp_logs",
+    description: "View recent logs from a managed MCP server.",
+    inputSchema: { type: "object", properties: { server_name: { type: "string" }, lines: { type: "number", description: "Lines (default: 50, max: 1000)" } }, required: ["server_name"] },
+  },
+  {
+    name: "mesh_mcp_scope",
+    description: "Get or set the visibility scope of a deployed MCP server.",
+    inputSchema: { type: "object", properties: { server_name: { type: "string" }, scope: { description: "New scope to set. Omit to read current." } }, required: ["server_name"] },
+  },
+  {
+    name: "mesh_mcp_schema",
+    description: "Inspect tool schemas for a deployed MCP server.",
+    inputSchema: { type: "object", properties: { server_name: { type: "string" }, tool_name: { type: "string", description: "Specific tool (omit for all)" } }, required: ["server_name"] },
+  },
+  {
+    name: "mesh_mcp_catalog",
+    description: "List all deployed services in the mesh with status, scope, and tool count.",
+    inputSchema: { type: "object", properties: {} },
+  },
+
+  // --- Skill deployment tools ---
+
+  {
+    name: "mesh_skill_deploy",
+    description: "Deploy a multi-file skill bundle from a zip or git repo.",
+    inputSchema: { type: "object", properties: { file_id: { type: "string" }, git_url: { type: "string" }, git_branch: { type: "string" } } },
+  },
+
+  // --- Vault tools ---
+
+  {
+    name: "vault_set",
+    description: "Store an encrypted credential in your vault. Reference in mesh_mcp_deploy with $vault:<key>.",
+    inputSchema: { type: "object", properties: { key: { type: "string" }, value: { type: "string", description: "Secret value or local file path (for type=file)" }, type: { type: "string", enum: ["env", "file"] }, mount_path: { type: "string" }, description: { type: "string" } }, required: ["key", "value"] },
+  },
+  {
+    name: "vault_list",
+    description: "List your vault entries (keys and metadata only, no secret values).",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "vault_delete",
+    description: "Remove a credential from your vault.",
+    inputSchema: { type: "object", properties: { key: { type: "string" } }, required: ["key"] },
+  },
 ];

apps/cli/src/mcp/types.ts

@@ -22,3 +22,60 @@ export interface SetSummaryArgs {
 export interface SetStatusArgs {
   status: PeerStatus;
 }
+
+// --- Service deployment types ---
+
+export type ServiceScope =
+  | "peer"
+  | "mesh"
+  | { peers: string[] }
+  | { group: string }
+  | { groups: string[] }
+  | { role: string };
+
+export interface ServiceInfo {
+  name: string;
+  type: "mcp" | "skill";
+  description: string;
+  status: string;
+  tool_count: number;
+  deployed_by: string;
+  scope: ServiceScope;
+  source_type: string;
+  runtime?: string;
+  created_at: string;
+}
+
+export interface ServiceToolSchema {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface VaultEntry {
+  key: string;
+  entry_type: "env" | "file";
+  mount_path?: string;
+  description?: string;
+  updated_at: string;
+}
+
+export interface MeshMcpDeployArgs {
+  server_name: string;
+  file_id?: string;
+  git_url?: string;
+  git_branch?: string;
+  env?: Record<string, string>;
+  runtime?: "node" | "python" | "bun";
+  memory_mb?: number;
+  network_allow?: string[];
+  scope?: ServiceScope;
+}
+
+export interface VaultSetArgs {
+  key: string;
+  value: string;
+  type?: "env" | "file";
+  mount_path?: string;
+  description?: string;
+}