@marchward/mcp-server 0.2.2

package/src/.fuse_hidden0000004000000001

@@ -0,0 +1,286 @@
+/**
+ * Marchward MCP Server — Tool definitions
+ *
+ * Each tool maps to a Marchward API capability. These tools let
+ * AI coding agents (Claude, Cursor, Copilot, etc.):
+ *   1. Check governance before taking actions (marchward_authorize)
+ *   2. Execute actions through Marchward's credential gateway (marchward_execute)
+ *   3. Register and manage agents (marchward_register_agent, marchward_list_agents)
+ *   4. Inspect decisions (marchward_get_decisions)
+ *   5. Check governance coverage (marchward_check_coverage)
+ *   6. Bind policies to agents (marchward_bind_policy)
+ *
+ * Tool names are marchward_* (stable as of v0.2.0). MCP clients discover
+ * tools dynamically at runtime; the names are not dual-listed because
+ * duplicate tools degrade agent tool-selection.
+ */
+
+import { z } from "zod";
+import { MarchwardAPIClient } from "./api-client.js";
+
+// ─── Tool Schemas ───────────────────────────────────────────────
+
+export const TOOL_DEFINITIONS = {
+  marchward_authorize: {
+    name: "marchward_authorize",
+    description:
+      "Check whether an action is allowed BEFORE the agent takes it. Call this first for any consequential or irreversible action (deploying, committing, publishing, deleting, moving money, calling an external API). Returns ALLOW, BLOCK, ESCALATE, or ALLOW_WITH_CONDITIONS, and writes a tamper-evident audit record. The agent and policy are resolved from your API key, so you usually only pass toolName.",
+    inputSchema: z.object({
+      toolName: z
+        .string()
+        .describe(
+          "Name of the tool/action being authorized (e.g. 'github_commit', 'railway_deploy', 'notion_update')",
+        ),
+      arguments: z
+        .record(z.unknown())
+        .optional()
+        .describe("Arguments/parameters for the tool call"),
+      policyBundleId: z
+        .string()
+        .optional()
+        .describe("ID of the policy bundle to evaluate against (auto-resolved from API key → agent → policy if omitted)"),
+      agentId: z
+        .string()
+        .optional()
+        .describe("Agent ID (auto-resolved from API key if omitted)"),
+      mode: z
+        .enum(["HIC", "HITL", "HOTL"])
+        .optional()
+        .describe(
+          "Governance mode: HIC (human-in-command), HITL (human-in-the-loop), HOTL (human-on-the-loop)",
+        ),
+      context: z
+        .record(z.unknown())
+        .optional()
+        .describe("Additional context for policy evaluation"),
+    }),
+  },
+
+  marchward_execute: {
+    name: "marchward_execute",
+    description:
+      "Run an action through Marchward's credential-mediated gateway. Marchward evaluates policy, injects the real downstream credential server-side (the agent never holds it), enforces the cost cap and approval gates, then makes the call and records it. Use this for any call to a service whose credentials Marchward manages (GitHub, Stripe, Notion, etc.).",
+    inputSchema: z.object({
+      toolName: z
+        .string()
+        .describe("Name of the tool/action being executed"),
+      arguments: z
+        .record(z.unknown())
+        .optional()
+        .describe("Arguments for the tool call"),
+      policyBundleId: z
+        .string()
+        .describe("Policy bundle ID to evaluate against"),
+      agentId: z.string().describe("Agent ID making the request"),
+      service: z
+        .string()
+        .describe(
+          "Service name for credential injection (e.g. 'github', 'railway', 'notion')",
+        ),
+      downstream: z.object({
+        url: z.string().describe("Full URL for the downstream API call"),
+        method: z
+          .enum(["GET", "POST", "PUT", "PATCH", "DELETE"])
+          .describe("HTTP method"),
+        headers: z
+          .record(z.string())
+          .optional()
+          .describe("Additional headers"),
+        body: z.unknown().optional().describe("Request body"),
+      }),
+      mode: z.enum(["HIC", "HITL", "HOTL"]).optional(),
+    }),
+  },
+
+  marchward_register_agent: {
+    name: "marchward_register_agent",
+    description:
+      "Register a new agent with Marchward so it is governed from its first action. Returns the agent record and its Marchward API key — the only credential the agent should hold. Call this when building or deploying a new agent.",
+    inputSchema: z.object({
+      name: z.string().describe("Human-readable name for the agent"),
+      description: z
+        .string()
+        .optional()
+        .describe("Description of what the agent does"),
+      agentId: z
+        .string()
+        .optional()
+        .describe(
+          "Custom agent ID (auto-generated from name if omitted)",
+        ),
+    }),
+  },
+
+  marchward_list_agents: {
+    name: "marchward_list_agents",
+    description:
+      "List the agents registered under your account, with their IDs, status, last-seen time, and bound policy. Use to find an agentId or check what is under governance.",
+    inputSchema: z.object({}),
+  },
+
+  marchward_get_decisions: {
+    name: "marchward_get_decisions",
+    description:
+      "Review recent governance decisions (the audit trail). Filter by agent, tool name, or outcome (ALLOW/BLOCK/ESCALATE). Use to verify governance is active or to investigate what an agent actually did.",
+    inputSchema: z.object({
+      agentId: z
+        .string()
+        .optional()
+        .describe("Filter decisions by agent ID"),
+      toolName: z
+        .string()
+        .optional()
+        .describe("Filter decisions by tool name"),
+      result: z
+        .enum(["ALLOW", "BLOCK", "ESCALATE", "ALLOW_WITH_CONDITIONS"])
+        .optional()
+        .describe("Filter by decision outcome"),
+      limit: z
+        .number()
+        .optional()
+        .default(20)
+        .describe("Number of decisions to return (default 20)"),
+    }),
+  },
+
+  marchward_check_coverage: {
+    name: "marchward_check_coverage",
+    description:
+      "Find governance gaps for an agent by comparing its declared tools against the tools it has actually called. Returns a coverage percentage and the uncovered tools, so ungoverned actions surface before they cause harm. This is the 'Dependabot for governance'.",
+    inputSchema: z.object({
+      agentId: z.string().describe("Agent ID to check coverage for"),
+    }),
+  },
+
+  marchward_bind_policy: {
+    name: "marchward_bind_policy",
+    description:
+      "Attach a governance policy to an agent. After binding, every authorize and execute call from that agent is evaluated against this policy.",
+    inputSchema: z.object({
+      agentId: z.string().describe("Agent ID to bind the policy to"),
+      policyBundleId: z.string().describe("Policy bundle ID to bind"),
+    }),
+  },
+} as const;
+
+// ─── Tool Handlers ──────────────────────────────────────────────
+
+export function createToolHandlers(client: MarchwardAPIClient) {
+  return {
+    async marchward_authorize(args: z.infer<typeof TOOL_DEFINITIONS.marchward_authorize.inputSchema>) {
+      const result = await client.authorize(args);
+      const decision = (result as any).result ?? (result as any).decision ?? "UNKNOWN";
+      const decisionId = (result as any).decisionId ?? "";
+      const explanation = (result as any).explanation ?? [];
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(
+              {
+                decision,
+                decisionId,
+                explanation,
+                toolName: args.toolName,
+                ...(args.policyBundleId ? { policyBundleId: args.policyBundleId } : {}),
+                full: result,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+
+    async marchward_execute(args: z.infer<typeof TOOL_DEFINITIONS.marchward_execute.inputSchema>) {
+      const result = await client.execute(args);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    },
+
+    async marchward_register_agent(args: z.infer<typeof TOOL_DEFINITIONS.marchward_register_agent.inputSchema>) {
+      const result = await client.createAgent(args);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(
+              {
+                message: `Agent "${args.name}" registered successfully.`,
+                ...result,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+
+    async marchward_list_agents(_args: z.infer<typeof TOOL_DEFINITIONS.marchward_list_agents.inputSchema>) {
+      const result = await client.listAgents();
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    },
+
+    async marchward_get_decisions(args: z.infer<typeof TOOL_DEFINITIONS.marchward_get_decisions.inputSchema>) {
+      const result = await client.listDecisions(args);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    },
+
+    async marchward_check_coverage(args: z.infer<typeof TOOL_DEFINITIONS.marchward_check_coverage.inputSchema>) {
+      const result = await client.checkCoverage(args.agentId);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    },
+
+    async marchward_bind_policy(args: z.infer<typeof TOOL_DEFINITIONS.marchward_bind_policy.inputSchema>) {
+      const result = await client.bindPolicy(
+        args.agentId,
+        args.policyBundleId,
+      );
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(
+              {
+                message: `Policy "${args.policyBundleId}" bound to agent "${args.agentId}".`,
+                ...result,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  };
+}

package/src/api-client.ts

@@ -0,0 +1,224 @@
+/**
+ * Lightweight Marchward API client for the MCP server.
+ *
+ * We don't import the full SDK to keep dependencies minimal.
+ * This makes HTTP calls directly to the Marchward API.
+ */
+
+export interface MarchwardConfig {
+  apiUrl: string;
+  apiKey: string;
+  timeout?: number;
+}
+
+export class MarchwardAPIClient {
+  private apiUrl: string;
+  private apiKey: string;
+  private timeout: number;
+
+  constructor(config: MarchwardConfig) {
+    this.apiUrl = config.apiUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout ?? 10_000;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const res = await fetch(`${this.apiUrl}${path}`, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      const data = await res.json();
+      if (!res.ok) {
+        throw new Error(
+          `Marchward API ${method} ${path} returned ${res.status}: ${JSON.stringify(data)}`,
+        );
+      }
+      return data as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // ─── Core Governance ──────────────────────────────────────────
+
+  async authorize(input: {
+    toolName: string;
+    arguments?: Record<string, unknown>;
+    policyBundleId?: string;
+    agentId?: string;
+    mode?: string;
+    context?: Record<string, unknown>;
+    signals?: Record<string, unknown>;
+  }) {
+    return this.request<Record<string, unknown>>("POST", "/v1/authorize", {
+      toolCall: {
+        toolName: input.toolName,
+        arguments: input.arguments ?? {},
+      },
+      // Only include policyBundle if explicitly provided — otherwise let
+      // the API auto-resolve from the API key → agent → policy chain.
+      policyBundle: input.policyBundleId ? { id: input.policyBundleId } : undefined,
+      agent: input.agentId ? { agentId: input.agentId } : undefined,
+      mode: input.mode,
+      context: input.context,
+      signals: input.signals,
+    });
+  }
+
+  async execute(input: {
+    toolName: string;
+    arguments?: Record<string, unknown>;
+    policyBundleId: string;
+    agentId: string;
+    service: string;
+    downstream: {
+      url: string;
+      method: string;
+      headers?: Record<string, string>;
+      body?: unknown;
+    };
+    mode?: string;
+  }) {
+    return this.request<Record<string, unknown>>("POST", "/v1/execute", {
+      toolCall: {
+        toolName: input.toolName,
+        arguments: input.arguments ?? {},
+      },
+      policyBundle: { id: input.policyBundleId },
+      agent: { agentId: input.agentId },
+      service: input.service,
+      downstream: input.downstream,
+      mode: input.mode,
+    });
+  }
+
+  // ─── Agent Registry ───────────────────────────────────────────
+
+  async createAgent(input: {
+    name: string;
+    description?: string;
+    agentId?: string;
+  }) {
+    return this.request<Record<string, unknown>>("POST", "/v1/agents", input);
+  }
+
+  async listAgents() {
+    return this.request<Record<string, unknown>>("GET", "/v1/agents");
+  }
+
+  async getAgent(agentId: string) {
+    return this.request<Record<string, unknown>>(
+      "GET",
+      `/v1/agents/${agentId}`,
+    );
+  }
+
+  async bindPolicy(agentId: string, policyBundleId: string) {
+    return this.request<Record<string, unknown>>(
+      "POST",
+      `/v1/agents/${agentId}/bind-policy`,
+      { policyBundleId },
+    );
+  }
+
+  // ─── Decisions ────────────────────────────────────────────────
+
+  async listDecisions(query?: {
+    agentId?: string;
+    toolName?: string;
+    result?: string;
+    limit?: number;
+    offset?: number;
+  }) {
+    const params = new URLSearchParams();
+    if (query?.agentId) params.set("agentId", query.agentId);
+    if (query?.toolName) params.set("toolName", query.toolName);
+    if (query?.result) params.set("result", query.result);
+    if (query?.limit) params.set("limit", String(query.limit));
+    if (query?.offset) params.set("offset", String(query.offset));
+
+    const qs = params.toString();
+    return this.request<Record<string, unknown>>(
+      "GET",
+      `/v1/decisions${qs ? `?${qs}` : ""}`,
+    );
+  }
+
+  // ─── Coverage Check ───────────────────────────────────────────
+
+  async checkCoverage(agentId: string) {
+    // Get agent's registered tools
+    const agent = await this.getAgent(agentId);
+    const registeredTools = (agent as any).tools ?? [];
+
+    // Get recent decisions for this agent
+    const decisions = await this.listDecisions({
+      agentId,
+      limit: 200,
+    });
+    const decisionList = (decisions as any).decisions ?? [];
+
+    // Find unique tool names that have produced decisions
+    const observedTools = new Set<string>();
+    for (const d of decisionList) {
+      if (d.toolName) observedTools.add(d.toolName);
+    }
+
+    // Compare declared vs observed
+    const declaredToolNames = registeredTools.map(
+      (t: any) => t.name ?? t.toolName ?? t,
+    );
+    const covered = declaredToolNames.filter((t: string) =>
+      observedTools.has(t),
+    );
+    const uncovered = declaredToolNames.filter(
+      (t: string) => !observedTools.has(t),
+    );
+    const undeclaredButObserved = [...observedTools].filter(
+      (t) => !declaredToolNames.includes(t),
+    );
+
+    const totalDeclared = declaredToolNames.length;
+    const coveragePercent =
+      totalDeclared > 0
+        ? Math.round((covered.length / totalDeclared) * 100)
+        : 0;
+
+    return {
+      agentId,
+      totalDeclaredTools: totalDeclared,
+      totalObservedTools: observedTools.size,
+      coveragePercent,
+      coveredTools: covered,
+      uncoveredTools: uncovered,
+      undeclaredButObserved,
+      totalDecisionsAnalyzed: decisionList.length,
+      summary:
+        totalDeclared === 0
+          ? `Agent "${agentId}" has no declared tools. Cannot calculate coverage.`
+          : coveragePercent === 100
+            ? `Agent "${agentId}" has 100% governance coverage (${totalDeclared}/${totalDeclared} tools producing decisions).`
+            : `Agent "${agentId}" has ${coveragePercent}% governance coverage (${covered.length}/${totalDeclared} tools). Missing: ${uncovered.join(", ")}`,
+    };
+  }
+
+  // ─── Health ───────────────────────────────────────────────────
+
+  async health() {
+    return this.request<Record<string, unknown>>("GET", "/health");
+  }
+}