@marchward/mcp-server 0.2.2

package/README.md

@@ -0,0 +1,81 @@
+# Marchward MCP Server
+
+Govern what an AI coding agent is allowed to **do**, from inside the agent. This is an
+[MCP](https://modelcontextprotocol.io) server that exposes [Marchward](https://marchward.ai) governance
+operations as tools, so an agent (Claude, Cursor, Copilot, Windsurf, etc.) can check authorization
+before it acts, run actions through a credential-mediated gateway, and read its own tamper-evident
+audit trail.
+
+Apache-2.0. The agent holds only a Marchward API key; the real downstream credentials are injected
+server-side, never by the agent.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `marchward_authorize` | Check whether an action is allowed before the agent takes it (ALLOW / BLOCK / ESCALATE / ALLOW_WITH_CONDITIONS). |
+| `marchward_execute` | Run an action through Marchward's credential-mediated gateway. |
+| `marchward_register_agent` | Register a new agent so it is governed from its first action. |
+| `marchward_list_agents` | List registered agents and their bound policies. |
+| `marchward_get_decisions` | Read the governance decision audit trail. |
+| `marchward_check_coverage` | Find governance gaps between declared and actually-called tools. |
+| `marchward_bind_policy` | Attach a governance policy to an agent. |
+
+## Quick start
+
+You need a Marchward API key (`mw_...`), free at [marchward.ai](https://marchward.ai).
+
+### stdio (Claude Code, Cursor, local)
+
+```json
+{
+  "mcpServers": {
+    "marchward": {
+      "command": "npx",
+      "args": ["-y", "@marchward/mcp-server"],
+      "env": {
+        "MARCHWARD_API_URL": "https://api.marchward.ai",
+        "MARCHWARD_API_KEY": "mw_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Streamable HTTP (remote)
+
+```json
+{
+  "mcpServers": {
+    "marchward": {
+      "type": "url",
+      "url": "https://mcp.marchward.ai/mcp",
+      "headers": { "Authorization": "Bearer mw_your_key_here" }
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MARCHWARD_API_URL` | yes | — | Marchward API base URL (`https://api.marchward.ai`) |
+| `MARCHWARD_API_KEY` | yes (stdio) | — | Your Marchward API key (`mw_...`) |
+| `TRANSPORT` | no | `stdio` | `stdio` or `http` |
+| `PORT` | no | `3100` | HTTP server port (http transport only) |
+
+## Run from source
+
+```bash
+npm install
+npm run build
+MARCHWARD_API_URL=https://api.marchward.ai MARCHWARD_API_KEY=mw_... npm start
+```
+
+## How it fits
+
+This server is the agent-facing surface of the Marchward runtime authority. The open governance engine
+and proxy live at [github.com/marchward/marchward](https://github.com/marchward/marchward); the hosted
+control plane (credential vault, audit-as-a-service, approval workflow) is at
+[marchward.ai](https://marchward.ai).

package/dist/api-client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 declare class MarchwardAPIClient {
+    private apiUrl;
+    private apiKey;
+    private timeout;
+    constructor(config: MarchwardConfig);
+    private request;
+    authorize(input: {
+        toolName: string;
+        arguments?: Record<string, unknown>;
+        policyBundleId?: string;
+        agentId?: string;
+        mode?: string;
+        context?: Record<string, unknown>;
+        signals?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    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;
+    }): Promise<Record<string, unknown>>;
+    createAgent(input: {
+        name: string;
+        description?: string;
+        agentId?: string;
+    }): Promise<Record<string, unknown>>;
+    listAgents(): Promise<Record<string, unknown>>;
+    getAgent(agentId: string): Promise<Record<string, unknown>>;
+    bindPolicy(agentId: string, policyBundleId: string): Promise<Record<string, unknown>>;
+    listDecisions(query?: {
+        agentId?: string;
+        toolName?: string;
+        result?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Record<string, unknown>>;
+    checkCoverage(agentId: string): Promise<{
+        agentId: string;
+        totalDeclaredTools: any;
+        totalObservedTools: number;
+        coveragePercent: number;
+        coveredTools: any;
+        uncoveredTools: any;
+        undeclaredButObserved: string[];
+        totalDecisionsAnalyzed: any;
+        summary: string;
+    }>;
+    health(): Promise<Record<string, unknown>>;
+}

package/dist/api-client.js

@@ -0,0 +1,144 @@
+/**
+ * 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 class MarchwardAPIClient {
+    apiUrl;
+    apiKey;
+    timeout;
+    constructor(config) {
+        this.apiUrl = config.apiUrl.replace(/\/$/, "");
+        this.apiKey = config.apiKey;
+        this.timeout = config.timeout ?? 10_000;
+    }
+    async request(method, path, body) {
+        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;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ─── Core Governance ──────────────────────────────────────────
+    async authorize(input) {
+        return this.request("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) {
+        return this.request("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) {
+        return this.request("POST", "/v1/agents", input);
+    }
+    async listAgents() {
+        return this.request("GET", "/v1/agents");
+    }
+    async getAgent(agentId) {
+        return this.request("GET", `/v1/agents/${agentId}`);
+    }
+    async bindPolicy(agentId, policyBundleId) {
+        return this.request("POST", `/v1/agents/${agentId}/bind-policy`, { policyBundleId });
+    }
+    // ─── Decisions ────────────────────────────────────────────────
+    async listDecisions(query) {
+        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("GET", `/v1/decisions${qs ? `?${qs}` : ""}`);
+    }
+    // ─── Coverage Check ───────────────────────────────────────────
+    async checkCoverage(agentId) {
+        // Get agent's registered tools
+        const agent = await this.getAgent(agentId);
+        const registeredTools = agent.tools ?? [];
+        // Get recent decisions for this agent
+        const decisions = await this.listDecisions({
+            agentId,
+            limit: 200,
+        });
+        const decisionList = decisions.decisions ?? [];
+        // Find unique tool names that have produced decisions
+        const observedTools = new Set();
+        for (const d of decisionList) {
+            if (d.toolName)
+                observedTools.add(d.toolName);
+        }
+        // Compare declared vs observed
+        const declaredToolNames = registeredTools.map((t) => t.name ?? t.toolName ?? t);
+        const covered = declaredToolNames.filter((t) => observedTools.has(t));
+        const uncovered = declaredToolNames.filter((t) => !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("GET", "/health");
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Marchward MCP Server
+ *
+ * Exposes Marchward governance operations as MCP tools for AI coding agents.
+ * Supports two transports:
+ *   - stdio:  Single-user, local. API key from MARCHWARD_API_KEY env var.
+ *   - http:   Multi-tenant shared service. Each user passes their own
+ *             API key via the Authorization header in their MCP config.
+ *             The server holds NO credentials — it's a stateless proxy.
+ *
+ * Environment variables (TENET_* names still read as a fallback for back-compat):
+ *   MARCHWARD_API_URL   — Marchward API base URL (required)
+ *   MARCHWARD_API_KEY   — Marchward API key (required for stdio only)
+ *   PORT                — HTTP server port (default: 3100, http transport only)
+ *   TRANSPORT           — "stdio" or "http" (default: "stdio")
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * Marchward MCP Server
+ *
+ * Exposes Marchward governance operations as MCP tools for AI coding agents.
+ * Supports two transports:
+ *   - stdio:  Single-user, local. API key from MARCHWARD_API_KEY env var.
+ *   - http:   Multi-tenant shared service. Each user passes their own
+ *             API key via the Authorization header in their MCP config.
+ *             The server holds NO credentials — it's a stateless proxy.
+ *
+ * Environment variables (TENET_* names still read as a fallback for back-compat):
+ *   MARCHWARD_API_URL   — Marchward API base URL (required)
+ *   MARCHWARD_API_KEY   — Marchward API key (required for stdio only)
+ *   PORT                — HTTP server port (default: 3100, http transport only)
+ *   TRANSPORT           — "stdio" or "http" (default: "stdio")
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { randomUUID } from "node:crypto";
+import { MarchwardAPIClient } from "./api-client.js";
+import { TOOL_DEFINITIONS, createToolHandlers } from "./tools.js";
+// ─── Configuration ──────────────────────────────────────────────
+const MARCHWARD_API_URL = (process.env.MARCHWARD_API_URL ?? process.env.TENET_API_URL);
+const MARCHWARD_API_KEY = (process.env.MARCHWARD_API_KEY ?? process.env.TENET_API_KEY);
+const PORT = parseInt(process.env.PORT ?? "3100", 10);
+const TRANSPORT = process.env.TRANSPORT ?? "stdio";
+// ─── Build Server ───────────────────────────────────────────────
+/**
+ * Create an MCP server wired to a specific Marchward API client.
+ * For stdio: one client per process (key from env).
+ * For HTTP: one client per session (key from request headers).
+ */
+function createMcpServer(apiKey) {
+    if (!MARCHWARD_API_URL) {
+        throw new Error("MARCHWARD_API_URL environment variable is required");
+    }
+    const server = new McpServer({
+        name: "marchward",
+        version: "0.2.1",
+    });
+    const client = new MarchwardAPIClient({
+        apiUrl: MARCHWARD_API_URL,
+        apiKey,
+    });
+    const handlers = createToolHandlers(client);
+    // Register each tool with the MCP server
+    for (const [key, def] of Object.entries(TOOL_DEFINITIONS)) {
+        const handlerFn = handlers[key];
+        if (handlerFn) {
+            server.tool(def.name, def.description, def.inputSchema.shape, handlerFn);
+        }
+    }
+    return server;
+}
+// ─── stdio Transport (single-user, local) ───────────────────────
+async function runStdio() {
+    if (!MARCHWARD_API_KEY) {
+        throw new Error("MARCHWARD_API_KEY environment variable is required for stdio transport");
+    }
+    const server = createMcpServer(MARCHWARD_API_KEY);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[marchward-mcp] Running on stdio transport");
+}
+// ─── HTTP Transport (multi-tenant, shared service) ──────────────
+function extractApiKey(req) {
+    // 1. Check Authorization header (standard MCP auth)
+    const auth = req.headers["authorization"];
+    if (auth) {
+        if (auth.startsWith("Bearer ")) {
+            return auth.slice(7);
+        }
+        if (auth.startsWith("mw_") || auth.startsWith("tnt_")) {
+            return auth;
+        }
+    }
+    // 2. Check URL query parameter (for clients like Claude's custom connector
+    //    that don't support static Authorization headers — they use OAuth or authless)
+    const queryKey = req.query.key;
+    if (queryKey?.startsWith("mw_") || queryKey?.startsWith("tnt_")) {
+        return queryKey;
+    }
+    // 3. Fall back to environment variable (single-tenant deployment mode)
+    if (MARCHWARD_API_KEY) {
+        return MARCHWARD_API_KEY;
+    }
+    return null;
+}
+async function runHttp() {
+    if (!MARCHWARD_API_URL) {
+        throw new Error("MARCHWARD_API_URL environment variable is required");
+    }
+    const app = express();
+    app.use(express.json());
+    // Request logging for debugging connector issues
+    app.use((req, _res, next) => {
+        const hasAuth = !!req.headers["authorization"];
+        const hasQueryKey = !!req.query.key;
+        const hasEnvKey = !!MARCHWARD_API_KEY;
+        console.log(`[marchward-mcp] ${req.method} ${req.path} | auth-header: ${hasAuth} | query-key: ${hasQueryKey} | env-fallback: ${hasEnvKey}`);
+        next();
+    });
+    // Track active sessions (transport + the API key they authenticated with)
+    const sessions = new Map();
+    app.post("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        // ── Existing session ──────────────────────────────────────
+        if (sessionId && sessions.has(sessionId)) {
+            const entry = sessions.get(sessionId);
+            await entry.transport.handleRequest(req, res, req.body);
+            return;
+        }
+        // ── New session — extract user's API key from headers ─────
+        const apiKey = extractApiKey(req);
+        if (!apiKey) {
+            res.status(401).json({
+                error: "Missing Authorization header. Include your Marchward API key as: Authorization: Bearer mw_your_key",
+            });
+            return;
+        }
+        // Create a server + client scoped to this user's API key
+        const server = createMcpServer(apiKey);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+        });
+        transport.onclose = () => {
+            const sid = transport.sessionId;
+            if (sid)
+                sessions.delete(sid);
+        };
+        await server.connect(transport);
+        // Handle the initial request
+        await transport.handleRequest(req, res, req.body);
+        // Store session for subsequent requests
+        if (transport.sessionId) {
+            sessions.set(transport.sessionId, { transport, apiKey });
+        }
+    });
+    // Handle GET for SSE streams
+    app.get("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId || !sessions.has(sessionId)) {
+            res.status(400).json({ error: "Invalid or missing session ID" });
+            return;
+        }
+        const entry = sessions.get(sessionId);
+        await entry.transport.handleRequest(req, res);
+    });
+    // Handle DELETE for session cleanup
+    app.delete("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (sessionId && sessions.has(sessionId)) {
+            const entry = sessions.get(sessionId);
+            await entry.transport.close();
+            sessions.delete(sessionId);
+        }
+        res.status(200).json({ ok: true });
+    });
+    // Health check (no auth required)
+    app.get("/health", (_req, res) => {
+        res.json({
+            status: "ok",
+            server: "marchward-mcp-server",
+            version: "0.2.1",
+            transport: "streamable-http",
+            activeSessions: sessions.size,
+            marchwardApiUrl: MARCHWARD_API_URL,
+        });
+    });
+    app.listen(PORT, () => {
+        console.log(`[marchward-mcp] HTTP server listening on port ${PORT}`);
+        console.log(`[marchward-mcp] MCP endpoint: http://localhost:${PORT}/mcp`);
+        console.log(`[marchward-mcp] Health check: http://localhost:${PORT}/health`);
+        console.log(`[marchward-mcp] Marchward API: ${MARCHWARD_API_URL}`);
+        console.log(`[marchward-mcp] Mode: multi-tenant (API key per session from Authorization header)`);
+    });
+}
+// ─── Entry Point ────────────────────────────────────────────────
+async function main() {
+    try {
+        if (TRANSPORT === "http") {
+            await runHttp();
+        }
+        else {
+            await runStdio();
+        }
+    }
+    catch (err) {
+        console.error("[marchward-mcp] Fatal error:", err);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}