@clawdreyhepburn/carapace 0.1.0

package/src/gui/server.ts

@@ -0,0 +1,169 @@
+/**
+ * Control GUI — lightweight local web server for human oversight of MCP tool access.
+ *
+ * Serves a single-page app that shows all MCP servers and tools,
+ * lets humans toggle access, and displays Cedar policy state.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse, type Server } from "node:http";
+import type { McpAggregator } from "../mcp-aggregator.js";
+import type { Logger, CedarEngineInterface } from "../types.js";
+import { guiHtml } from "./html.js";
+
+interface GuiOpts {
+  port: number;
+  aggregator: McpAggregator;
+  cedar: CedarEngineInterface;
+  logger: Logger;
+}
+
+export class ControlGui {
+  private port: number;
+  private aggregator: McpAggregator;
+  private cedar: CedarEngineInterface;
+  private logger: Logger;
+  private server: Server | null = null;
+
+  constructor(opts: GuiOpts) {
+    this.port = opts.port;
+    this.aggregator = opts.aggregator;
+    this.cedar = opts.cedar;
+    this.logger = opts.logger;
+  }
+
+  async start(): Promise<void> {
+    this.server = createServer((req, res) => this.handleRequest(req, res));
+    return new Promise((resolve, reject) => {
+      this.server!.listen(this.port, "127.0.0.1", () => {
+        this.logger.info(`GUI listening on http://127.0.0.1:${this.port}`);
+        resolve();
+      });
+      this.server!.on("error", reject);
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.server) {
+        this.server.close(() => resolve());
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  private async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = new URL(req.url ?? "/", `http://127.0.0.1:${this.port}`);
+
+    try {
+      // --- API routes ---
+      if (url.pathname === "/api/status" && req.method === "GET") {
+        const servers = this.aggregator.getServerStatus();
+        const tools = this.aggregator.listTools();
+        this.json(res, {
+          servers,
+          tools,
+          policies: this.cedar.getPolicies(),
+          toolCount: tools.length,
+          enabledCount: tools.filter((t) => t.enabled).length,
+        });
+        return;
+      }
+
+      if (url.pathname === "/api/tools" && req.method === "GET") {
+        const server = url.searchParams.get("server") ?? undefined;
+        this.json(res, this.aggregator.listTools(server));
+        return;
+      }
+
+      if (url.pathname === "/api/toggle" && req.method === "POST") {
+        const body = await this.readBody(req);
+        const { tool, enabled } = JSON.parse(body);
+        if (enabled) {
+          this.cedar.enableTool(tool);
+        } else {
+          this.cedar.disableTool(tool);
+        }
+        this.json(res, { ok: true, tool, enabled });
+        return;
+      }
+
+      if (url.pathname === "/api/verify" && req.method === "POST") {
+        const result = await this.cedar.verify();
+        this.json(res, result);
+        return;
+      }
+
+      if (url.pathname === "/api/policies" && req.method === "GET") {
+        this.json(res, this.cedar.getPolicies());
+        return;
+      }
+
+      if (url.pathname === "/api/policy" && req.method === "POST") {
+        const body = await this.readBody(req);
+        const { id, raw } = JSON.parse(body);
+        if (!id || !raw) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "id and raw are required" }));
+          return;
+        }
+        this.cedar.savePolicy(id, raw);
+        this.json(res, { ok: true, id });
+        return;
+      }
+
+      if (url.pathname === "/api/policy" && req.method === "DELETE") {
+        const body = await this.readBody(req);
+        const { id } = JSON.parse(body);
+        const deleted = this.cedar.deletePolicy(id);
+        this.json(res, { ok: deleted, id });
+        return;
+      }
+
+      if (url.pathname === "/api/schema" && req.method === "GET") {
+        this.json(res, this.cedar.getSchema());
+        return;
+      }
+
+      if (url.pathname === "/api/schema" && req.method === "POST") {
+        const body = await this.readBody(req);
+        const { raw } = JSON.parse(body);
+        this.cedar.saveSchema(raw);
+        this.json(res, { ok: true });
+        return;
+      }
+
+      // --- GUI ---
+      if (url.pathname === "/" || url.pathname === "/index.html") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(guiHtml());
+        return;
+      }
+
+      // 404
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Not Found");
+    } catch (err: any) {
+      this.logger.error(`GUI error: ${err.message}`);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  }
+
+  private json(res: ServerResponse, data: any): void {
+    res.writeHead(200, {
+      "Content-Type": "application/json",
+      "Access-Control-Allow-Origin": "*",
+    });
+    res.end(JSON.stringify(data));
+  }
+
+  private readBody(req: IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk) => chunks.push(chunk));
+      req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+      req.on("error", reject);
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,208 @@
+/**
+ * Carapace — OpenClaw Plugin
+ *
+ * Aggregates upstream MCP servers, enforces Cedar policies on tool access,
+ * and serves a local GUI for human oversight.
+ */
+
+import { CedarlingEngine } from "./cedar-engine-cedarling.js";
+import { McpAggregator } from "./mcp-aggregator.js";
+import { ControlGui } from "./gui/server.js";
+import type { PluginConfig } from "./types.js";
+
+export const id = "carapace";
+export const name = "Carapace";
+
+/**
+ * OpenClaw plugin API shape (matches real runtime).
+ * We define it here to avoid depending on OpenClaw types at build time.
+ */
+interface OpenClawPluginApi {
+  pluginConfig: any;
+  logger: {
+    info(msg: string, ...args: any[]): void;
+    warn(msg: string, ...args: any[]): void;
+    error(msg: string, ...args: any[]): void;
+    debug?(msg: string, ...args: any[]): void;
+  };
+  registerService(service: { id: string; start(): Promise<void> | void; stop(): Promise<void> | void }): void;
+  registerTool(
+    tool: {
+      name: string;
+      label?: string;
+      description: string;
+      parameters: Record<string, any>;
+      execute(toolCallId: string, params: any): Promise<any>;
+    },
+    opts?: { optional?: boolean },
+  ): void;
+  registerCli?(fn: (ctx: { program: any }) => void, opts?: { commands: string[] }): void;
+  registerGatewayMethod?(name: string, handler: (ctx: { respond: (ok: boolean, data: any) => void }) => void): void;
+}
+
+export default function register(api: OpenClawPluginApi) {
+  const config: PluginConfig = api.pluginConfig ?? {};
+  const logger = api.logger;
+
+  const cedar = new CedarlingEngine({
+    policyDir: config.policyDir ?? "~/.openclaw/mcp-policies/",
+    defaultPolicy: config.defaultPolicy ?? "allow-all",
+    verify: config.verify ?? false,
+    logger,
+  });
+
+  const aggregator = new McpAggregator({
+    servers: config.servers ?? {},
+    cedar,
+    logger,
+  });
+
+  const gui = new ControlGui({
+    port: config.guiPort ?? 19820,
+    aggregator,
+    cedar,
+    logger,
+  });
+
+  // --- Background service: connect to MCP servers and serve GUI ---
+  api.registerService({
+    id: "carapace",
+    async start() {
+      logger.info("Carapace starting...");
+      await cedar.init();
+      await aggregator.connectAll();
+      await gui.start();
+      logger.info(`Control GUI at http://localhost:${config.guiPort ?? 19820}`);
+    },
+    async stop() {
+      await gui.stop();
+      await aggregator.disconnectAll();
+      logger.info("Carapace stopped");
+    },
+  });
+
+  // --- Agent tool: list available MCP tools ---
+  api.registerTool({
+    name: "mcp_tools",
+    label: "MCP Tools (Carapace)",
+    description:
+      "List all MCP tools available through the Carapace Cedar proxy, with their enabled/disabled status",
+    parameters: {
+      type: "object",
+      properties: {
+        server: {
+          type: "string",
+          description: "Filter by server name (optional)",
+        },
+      },
+    },
+    async execute(_toolCallId: string, params: { server?: string }) {
+      const tools = aggregator.listTools(params.server);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(tools, null, 2),
+          },
+        ],
+      };
+    },
+  });
+
+  // --- Agent tool: invoke an MCP tool through the proxy ---
+  api.registerTool({
+    name: "mcp_call",
+    label: "MCP Call (Carapace)",
+    description:
+      "Call an MCP tool through the Carapace Cedar proxy. The call is authorized by Cedar policies before reaching the upstream server.",
+    parameters: {
+      type: "object",
+      required: ["tool"],
+      properties: {
+        tool: {
+          type: "string",
+          description: 'Fully qualified tool name (e.g., "github/create_issue")',
+        },
+        arguments: {
+          type: "object",
+          description: "Arguments to pass to the tool",
+        },
+      },
+    },
+    async execute(_toolCallId: string, params: { tool: string; arguments?: Record<string, unknown> }) {
+      const { tool, arguments: args } = params;
+
+      // Authorize via Cedar
+      const decision = await cedar.authorize({
+        principal: 'Agent::"openclaw"',
+        action: 'Action::"call_tool"',
+        resource: `Tool::"${tool}"`,
+        context: args ? { arguments: args } : {},
+      });
+
+      if (decision.decision === "deny") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `DENIED by Cedar policy: ${tool}\nReason: ${decision.reasons.join(", ") || "default deny"}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      // Forward to upstream MCP server
+      const result = await aggregator.callTool(tool, args ?? {});
+      return result;
+    },
+  });
+
+  // --- CLI command ---
+  api.registerCli?.(
+    ({ program }) => {
+      const cmd = program.command("carapace").description("Carapace — MCP tool authorization");
+
+      cmd.command("status").action(async () => {
+        const servers = aggregator.getServerStatus();
+        console.log("\n🦞 Carapace Status\n");
+        for (const [name, status] of Object.entries(servers)) {
+          const icon = status.connected ? "✅" : "❌";
+          console.log(`  ${icon} ${name} — ${status.toolCount} tools`);
+        }
+        const tools = aggregator.listTools();
+        const enabled = tools.filter((t) => t.enabled).length;
+        console.log(`\n  ${enabled}/${tools.length} tools enabled`);
+        console.log(`  GUI: http://localhost:${config.guiPort ?? 19820}\n`);
+      });
+
+      cmd.command("tools").action(async () => {
+        const tools = aggregator.listTools();
+        for (const tool of tools) {
+          const icon = tool.enabled ? "🟢" : "🔴";
+          console.log(`  ${icon} ${tool.qualifiedName} — ${tool.description}`);
+        }
+      });
+
+      cmd.command("verify").action(async () => {
+        const result = await cedar.verify();
+        if (result.ok) {
+          console.log("✅ All policies verified");
+        } else {
+          console.log("⚠️  Verification issues:");
+          for (const issue of result.issues) {
+            console.log(`  - ${issue}`);
+          }
+        }
+      });
+    },
+    { commands: ["carapace"] },
+  );
+
+  // --- Gateway RPC ---
+  api.registerGatewayMethod?.("carapace.status", ({ respond }) => {
+    const servers = aggregator.getServerStatus();
+    const tools = aggregator.listTools();
+    respond(true, { servers, toolCount: tools.length, enabledCount: tools.filter((t) => t.enabled).length });
+  });
+}

package/src/mcp-aggregator.ts

@@ -0,0 +1,178 @@
+/**
+ * MCP Aggregator — connects to multiple upstream MCP servers,
+ * discovers their tools, and proxies calls through Cedar authorization.
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+// import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+// import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { Logger, ServerConfig, McpTool, ServerStatus, CedarEngineInterface } from "./types.js";
+
+interface AggregatorOpts {
+  servers: Record<string, ServerConfig>;
+  cedar: CedarEngineInterface;
+  logger: Logger;
+}
+
+interface ConnectedServer {
+  name: string;
+  config: ServerConfig;
+  client: Client;
+  transport: any;
+  tools: McpTool[];
+  connected: boolean;
+  error?: string;
+}
+
+export class McpAggregator {
+  private servers: Map<string, ConnectedServer> = new Map();
+  private serverConfigs: Record<string, ServerConfig>;
+  private cedar: CedarEngineInterface;
+  private logger: Logger;
+
+  constructor(opts: AggregatorOpts) {
+    this.serverConfigs = opts.servers;
+    this.cedar = opts.cedar;
+    this.logger = opts.logger;
+  }
+
+  /** Connect to all configured MCP servers and discover tools */
+  async connectAll(): Promise<void> {
+    const entries = Object.entries(this.serverConfigs);
+    this.logger.info(`Connecting to ${entries.length} MCP server(s)...`);
+
+    await Promise.allSettled(
+      entries.map(([name, config]) => this.connectServer(name, config)),
+    );
+
+    const total = this.listTools().length;
+    const connected = [...this.servers.values()].filter((s) => s.connected).length;
+    this.logger.info(`Connected: ${connected}/${entries.length} servers, ${total} tools discovered`);
+  }
+
+  /** Disconnect all servers */
+  async disconnectAll(): Promise<void> {
+    for (const [name, server] of this.servers) {
+      try {
+        await server.transport?.close?.();
+        this.logger.debug?.(`Disconnected: ${name}`);
+      } catch (err) {
+        this.logger.warn(`Error disconnecting ${name}: ${err}`);
+      }
+    }
+    this.servers.clear();
+  }
+
+  /** List all discovered tools across all servers */
+  listTools(serverFilter?: string): McpTool[] {
+    const tools: McpTool[] = [];
+    for (const server of this.servers.values()) {
+      if (serverFilter && server.name !== serverFilter) continue;
+      for (const tool of server.tools) {
+        tools.push({
+          ...tool,
+          enabled: this.cedar.isToolEnabled(tool.qualifiedName),
+        });
+      }
+    }
+    return tools;
+  }
+
+  /** Get status of all servers */
+  getServerStatus(): Record<string, ServerStatus> {
+    const status: Record<string, ServerStatus> = {};
+    for (const [name, server] of this.servers) {
+      status[name] = {
+        connected: server.connected,
+        toolCount: server.tools.length,
+        error: server.error,
+      };
+    }
+    return status;
+  }
+
+  /** Call a tool on the appropriate upstream server */
+  async callTool(qualifiedName: string, args: Record<string, unknown>): Promise<any> {
+    const [serverName, toolName] = qualifiedName.split("/", 2);
+    const server = this.servers.get(serverName);
+
+    if (!server) {
+      return {
+        content: [{ type: "text", text: `Server not found: ${serverName}` }],
+        isError: true,
+      };
+    }
+
+    if (!server.connected) {
+      return {
+        content: [{ type: "text", text: `Server not connected: ${serverName}` }],
+        isError: true,
+      };
+    }
+
+    try {
+      const result = await server.client.callTool({ name: toolName, arguments: args });
+      return result;
+    } catch (err: any) {
+      return {
+        content: [{ type: "text", text: `Tool call failed: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+
+  // --- Private ---
+
+  private async connectServer(name: string, config: ServerConfig): Promise<void> {
+    const entry: ConnectedServer = {
+      name,
+      config,
+      client: new Client({ name: `mcp-cedar-proxy/${name}`, version: "0.1.0" }),
+      transport: null,
+      tools: [],
+      connected: false,
+    };
+
+    try {
+      if (config.transport === "stdio") {
+        if (!config.command) throw new Error("stdio transport requires 'command'");
+
+        entry.transport = new StdioClientTransport({
+          command: config.command,
+          args: config.args ?? [],
+          env: { ...process.env, ...(config.env ?? {}) } as Record<string, string>,
+        });
+      } else if (config.transport === "http" || config.transport === "sse") {
+        if (!config.url) throw new Error(`${config.transport} transport requires 'url'`);
+
+        // TODO: Add HTTP/SSE transport support
+        // For now, only stdio is implemented
+        throw new Error(`${config.transport} transport not yet implemented — use stdio`);
+      } else {
+        throw new Error(`Unknown transport: ${config.transport}`);
+      }
+
+      await entry.client.connect(entry.transport);
+      entry.connected = true;
+
+      // Discover tools
+      const toolsResult = await entry.client.listTools();
+      entry.tools = (toolsResult.tools ?? []).map((t) => ({
+        name: t.name,
+        qualifiedName: `${name}/${t.name}`,
+        server: name,
+        description: t.description ?? "",
+        inputSchema: t.inputSchema,
+        enabled: false, // Will be resolved against Cedar policies
+      }));
+
+      this.logger.info(`Connected to ${name}: ${entry.tools.length} tools`);
+    } catch (err: any) {
+      entry.error = err.message;
+      this.logger.warn(`Failed to connect to ${name}: ${err.message}`);
+    }
+
+    this.servers.set(name, entry);
+  }
+}

package/src/types.ts

@@ -0,0 +1,107 @@
+/**
+ * Type definitions for the MCP Cedar Proxy plugin.
+ */
+
+
+export interface Logger {
+  info(msg: string, ...args: any[]): void;
+  warn(msg: string, ...args: any[]): void;
+  error(msg: string, ...args: any[]): void;
+  debug?(msg: string, ...args: any[]): void;
+}
+
+export interface ToolDef {
+  name: string;
+  description: string;
+  parameters: Record<string, any>;
+  handler(args: any): Promise<any>;
+}
+
+export interface PluginConfig {
+  guiPort?: number;
+  servers?: Record<string, ServerConfig>;
+  policyDir?: string;
+  defaultPolicy?: "deny-all" | "allow-all";
+  verify?: boolean;
+}
+
+export interface ServerConfig {
+  transport: "stdio" | "http" | "sse";
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+}
+
+export interface McpTool {
+  name: string;
+  qualifiedName: string; // "server/tool"
+  server: string;
+  description: string;
+  inputSchema?: Record<string, any>;
+  enabled: boolean;
+}
+
+export interface ServerStatus {
+  connected: boolean;
+  toolCount: number;
+  lastSeen?: number;
+  error?: string;
+}
+
+export interface CedarDecision {
+  decision: "allow" | "deny";
+  reasons: string[];
+}
+
+export interface AuthzRequest {
+  principal: string;
+  action: string;
+  resource: string;
+  context?: Record<string, unknown>;
+}
+
+/** Common interface for Cedar engines (homebrew and Cedarling) */
+export interface CedarEngineInterface {
+  init(): Promise<void>;
+  authorize(request: AuthzRequest): Promise<CedarDecision>;
+  enableTool(qualifiedName: string): void;
+  disableTool(qualifiedName: string): void;
+  isToolEnabled(qualifiedName: string): boolean;
+  savePolicy(id: string, raw: string): void;
+  deletePolicy(id: string): boolean;
+  getPolicies(): Array<{ id: string; effect: string; raw: string }>;
+  getSchema(): CedarSchemaInfo;
+  saveSchema(raw: string): void;
+  verify(): Promise<VerifyResult>;
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  issues: string[];
+  durationMs: number;
+}
+
+export interface CedarSchemaInfo {
+  entities: SchemaEntity[];
+  actions: SchemaAction[];
+  raw: string;
+}
+
+export interface SchemaEntity {
+  name: string;
+  parents: string[];
+  attributes: SchemaAttribute[];
+}
+
+export interface SchemaAttribute {
+  name: string;
+  type: string;
+  optional: boolean;
+}
+
+export interface SchemaAction {
+  name: string;
+  principalTypes: string[];
+  resourceTypes: string[];
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}