intent-envelope-mcp 0.0.0-stage → 0.2.0

package/dist/relay.js

@@ -0,0 +1,188 @@
+/**
+ * An enforcement point that sits in the MCP wire protocol itself.
+ *
+ * The client launches this instead of the server it wants. Every tool call crosses this
+ * process, is decided against the envelope, and is forwarded only if the envelope
+ * permits it. A refused call is never written to the upstream server's stdin, which is
+ * the only property that matters: a decision made after the call has already run is a
+ * report, not an enforcement point.
+ *
+ * Why a line relay rather than the MCP SDK
+ * ----------------------------------------
+ * This understands exactly two methods, `tools/call` and `tools/list`, and relays
+ * every other line byte for byte. That is deliberate. The protocol has two eras in
+ * circulation, one using `server/discover` with inline `_meta` and one using the
+ * `initialize` handshake, and it keeps growing: `subscriptions/listen`,
+ * `notifications/cancelled`, `InputRequiredResult`. A proxy that modelled the whole
+ * protocol would need to track all of it and would break on the next addition. A relay
+ * that forwards what it does not recognise works across both eras and survives
+ * additions it has never heard of.
+ *
+ * It also means an unparseable line is passed along untouched rather than dropped. This
+ * process is not the arbiter of protocol validity; it is the arbiter of one question,
+ * which is whether a tool call is inside the envelope.
+ *
+ * stdout discipline
+ * -----------------
+ * The transport requires that nothing but valid MCP messages reach stdout. Every log,
+ * warning and summary this process emits goes to stderr, which the specification
+ * explicitly permits and tells clients not to treat as failure.
+ */
+import { EnforcementPoint } from 'intent-envelope';
+/** Implementation-defined JSON-RPC server error codes, per the JSON-RPC 2.0 spec. */
+export const DENIED = -32000;
+export const ESCALATION_REQUIRED = -32001;
+/**
+ * Split a byte stream into the transport's newline-delimited messages.
+ *
+ * Messages must not contain embedded newlines, so a line is a message. A trailing
+ * fragment is held until its newline arrives rather than being guessed at.
+ */
+function lines(stream, onLine, onEnd) {
+    let buffer = '';
+    stream.setEncoding?.('utf8');
+    stream.on('data', (chunk) => {
+        buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        let index = buffer.indexOf('\n');
+        while (index !== -1) {
+            const line = buffer.slice(0, index);
+            buffer = buffer.slice(index + 1);
+            if (line.trim())
+                onLine(line);
+            index = buffer.indexOf('\n');
+        }
+    });
+    stream.on('end', () => {
+        if (buffer.trim())
+            onLine(buffer);
+        onEnd();
+    });
+}
+function parse(line) {
+    try {
+        const value = JSON.parse(line);
+        return value && typeof value === 'object' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every tool name the envelope grants, for the optional tools/list filter. */
+function allowedNames(envelope) {
+    return new Set((envelope.tools?.allow ?? []).map((grant) => grant.name));
+}
+export class Relay {
+    point;
+    options;
+    allowed;
+    /** ids of tools/list requests in flight, so their replies can be filtered. */
+    listRequests = new Set();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        this.allowed = allowedNames(options.envelope);
+        this.point = new EnforcementPoint(options.envelope, {
+            onDecision: (decision) => options.ledger.record(decision),
+        });
+        // An operator who wrote on_no_response: allow asked for calls to proceed when a
+        // human does not answer in time. This process does not wait for a human at all, so
+        // honouring that would let a call through that nobody ever saw. It refuses instead,
+        // and says so, rather than being quietly stricter than the envelope asked.
+        if (options.envelope.on_no_response === 'allow') {
+            this.log('warning: this envelope sets on_no_response: allow, but this proxy does not ' +
+                'wait for a human, so escalated calls are refused rather than allowed.');
+        }
+    }
+    log(message) {
+        (this.options.log ?? ((m) => process.stderr.write(`[intent-envelope] ${m}\n`)))(message);
+    }
+    send(message) {
+        // One message per line, and nothing else on this stream, ever.
+        this.options.output.write(`${JSON.stringify(message)}\n`);
+    }
+    toUpstream(line) {
+        if (!this.closed)
+            this.options.upstream.stdin.write(`${line}\n`);
+    }
+    refuse(id, decision) {
+        const escalating = decision.result === 'escalate';
+        this.send({
+            jsonrpc: '2.0',
+            id,
+            error: {
+                code: escalating ? ESCALATION_REQUIRED : DENIED,
+                message: escalating
+                    ? `intent envelope: this call needs ${decision.escalateTo}: ${decision.detail}`
+                    : `intent envelope: refused by ${decision.rule}: ${decision.detail}`,
+                // The decision record travels with the refusal so a client can log the same
+                // thing the ledger holds, rather than re-deriving it from prose.
+                data: { intent_envelope: decision.record() },
+            },
+        });
+    }
+    /** Returns true when the line was handled here and must not reach the upstream. */
+    interceptFromClient(line, message) {
+        if (message.method === 'tools/list' && message.id !== undefined && message.id !== null) {
+            this.listRequests.add(String(message.id));
+            return false;
+        }
+        if (message.method !== 'tools/call')
+            return false;
+        const tool = typeof message.params?.name === 'string' ? message.params.name : '';
+        const args = (message.params?.arguments ?? {});
+        // No argument an agent passes can widen the envelope. The envelope was read from
+        // disk before this process accepted a single message and is never re-read.
+        const decision = this.point.check(tool, args);
+        if (decision.result === 'allow')
+            return false;
+        if (message.id === undefined || message.id === null) {
+            // A tools/call without an id is not answerable. It is still recorded, and it is
+            // still not forwarded, which is the part that matters.
+            this.log(`refused an unanswerable ${tool} call: ${decision.rule}`);
+            return true;
+        }
+        this.refuse(message.id, decision);
+        return true;
+    }
+    /** Filter a tools/list reply down to what the envelope grants. */
+    interceptFromUpstream(line, message) {
+        const id = message.id === undefined || message.id === null ? '' : String(message.id);
+        if (!id || !this.listRequests.has(id))
+            return line;
+        this.listRequests.delete(id);
+        if (this.options.filterToolList === false)
+            return line;
+        const tools = message.result?.tools;
+        if (!Array.isArray(tools))
+            return line;
+        const kept = tools.filter((tool) => typeof tool?.name === 'string' && this.allowed.has(tool.name));
+        if (kept.length !== tools.length) {
+            this.log(`tools/list: offering ${kept.length} of ${tools.length} tools the server exposes`);
+        }
+        return JSON.stringify({ ...message, result: { ...message.result, tools: kept } });
+    }
+    start() {
+        const { upstream, input, output } = this.options;
+        lines(input, (line) => {
+            const message = parse(line);
+            // An unparseable line is the client's business, not this process's. Relay it.
+            if (!message || !this.interceptFromClient(line, message))
+                this.toUpstream(line);
+        }, () => {
+            // Closing the upstream's stdin is the portable graceful shutdown signal.
+            this.closed = true;
+            upstream.stdin.end();
+        });
+        lines(upstream.stdout, (line) => {
+            const message = parse(line);
+            output.write(`${message ? this.interceptFromUpstream(line, message) : line}\n`);
+        }, () => { });
+        // The specification tells clients not to read failure into a server's stderr, so
+        // the upstream's logging is passed along rather than swallowed or reinterpreted.
+        upstream.stderr.on('data', (chunk) => process.stderr.write(chunk));
+    }
+    summary() {
+        return this.point.summary();
+    }
+}
+//# sourceMappingURL=relay.js.map

package/dist/relay.js.map

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

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "intent-envelope-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Enforce an intent envelope on an MCP server: refuse a tool call before it reaches the server.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "intent-envelope-mcp": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "ai",
+    "agents",
+    "security",
+    "intent",
+    "guardrails",
+    "proxy"
+  ],
+  "homepage": "https://securedai.org/agent-intent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/secured-ai/intent-envelope.git",
+    "directory": "packages/mcp-proxy"
+  },
+  "bugs": "https://github.com/secured-ai/intent-envelope/issues",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "intent-envelope": ">=0.1.0 <1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.ts",
+    "smoke": "node tools/consumer-smoke.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/bin.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * The command an MCP client launches in place of the server it wants governed.
+ *
+ * Exit codes: 0 if the upstream exited cleanly, the upstream's own code if it did not,
+ * and 2 for a configuration problem here. A client that cannot tell the difference
+ * between "the server failed" and "the envelope was unreadable" cannot be debugged.
+ */
+
+import { spawn } from 'node:child_process';
+
+import { ConfigError, parse } from './config.ts';
+import { fileLedger, memoryLedger } from './ledger.ts';
+import { Relay } from './relay.ts';
+
+const log = (message: string) => process.stderr.write(`[intent-envelope] ${message}\n`);
+
+function main(): void {
+  let config;
+  try {
+    config = parse(process.argv.slice(2), process.env);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      process.stderr.write(`${error.message}\n`);
+      process.exit(2);
+    }
+    // A schema failure arrives here. It names the field, which is the useful part.
+    process.stderr.write(`[intent-envelope] the envelope is not valid: ${(error as Error).message}\n`);
+    process.exit(2);
+  }
+
+  const { envelope, command, args } = config;
+  log(`enforcing ${envelope.id} revision ${envelope.revision ?? 1} on: ${command} ${args.join(' ')}`);
+
+  const upstream = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+
+  upstream.on('error', (error) => {
+    log(`cannot start the server: ${error.message}`);
+    process.exit(2);
+  });
+
+  const ledger = config.ledgerPath ? fileLedger(config.ledgerPath, log) : memoryLedger();
+  const relay = new Relay({
+    envelope,
+    ledger,
+    upstream,
+    input: process.stdin,
+    output: process.stdout,
+    log,
+    filterToolList: config.filterToolList,
+  });
+  relay.start();
+
+  upstream.on('exit', (code, signal) => {
+    const counts = relay.summary();
+    log(`${counts.allow} allowed, ${counts.deny} refused, ${counts.escalate} escalated`);
+    if (config.ledgerPath) log(`ledger: ${config.ledgerPath}`);
+    process.exit(signal ? 1 : (code ?? 0));
+  });
+}
+
+main();

package/src/config.ts

@@ -0,0 +1,89 @@
+/**
+ * Where the envelope and the upstream server come from.
+ *
+ * Both are supplied by whoever launches this process, never by the agent running
+ * behind it and never by anything the upstream server says. The envelope is read from
+ * disk once, before the first message is accepted, and is not re-read. There is no
+ * message an agent can send that changes what it is allowed to do.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { validate, type Envelope } from 'intent-envelope';
+
+export interface Config {
+  envelope: Envelope;
+  envelopePath: string;
+  command: string;
+  args: string[];
+  ledgerPath?: string;
+  filterToolList: boolean;
+}
+
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+export const USAGE = `intent-envelope-mcp: enforce an intent envelope on an MCP server
+
+  intent-envelope-mcp --envelope <path> [options] -- <server-command> [server-args...]
+
+Options
+  --envelope <path>    the envelope to enforce (or INTENT_ENVELOPE)
+  --ledger <path>      append decisions here as JSON lines (or INTENT_ENVELOPE_LEDGER)
+  --no-filter-tools    advertise every upstream tool, refusing the ones not granted
+  --help
+
+Everything after -- is the server to govern, run as a child process.
+
+  intent-envelope-mcp --envelope ./ap-agent.json -- npx -y @acme/invoice-mcp
+
+Point your MCP client at this command instead of the server's own. Nothing else about
+the client changes.`;
+
+/**
+ * Parse argv in the shape `[options] -- command args...`.
+ *
+ * The separator is required. Guessing where options end and the server command begins
+ * invites a mistake in which an option meant for this process is handed to the server,
+ * or worse, the reverse.
+ */
+export function parse(argv: string[], env: Record<string, string | undefined> = {}): Config {
+  const separator = argv.indexOf('--');
+  const flags = separator === -1 ? argv : argv.slice(0, separator);
+  const rest = separator === -1 ? [] : argv.slice(separator + 1);
+
+  let envelopePath = env.INTENT_ENVELOPE;
+  let ledgerPath = env.INTENT_ENVELOPE_LEDGER;
+  let filterToolList = true;
+
+  for (let i = 0; i < flags.length; i += 1) {
+    const flag = flags[i];
+    if (flag === '--envelope') envelopePath = flags[++i];
+    else if (flag === '--ledger') ledgerPath = flags[++i];
+    else if (flag === '--no-filter-tools') filterToolList = false;
+    else if (flag === '--help' || flag === '-h') throw new ConfigError(USAGE);
+    else throw new ConfigError(`unknown option ${flag}\n\n${USAGE}`);
+  }
+
+  if (!envelopePath) throw new ConfigError(`no envelope given\n\n${USAGE}`);
+  if (rest.length === 0) throw new ConfigError(`no server command given after --\n\n${USAGE}`);
+
+  const path = resolve(envelopePath);
+  let envelope: Envelope;
+  try {
+    envelope = JSON.parse(readFileSync(path, 'utf8')) as Envelope;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new ConfigError(`cannot read the envelope at ${path}: ${reason}`);
+  }
+
+  // Fail closed. An enforcement point that starts with an envelope it cannot understand
+  // is worse than one that does not start, because the client will assume it is running.
+  validate(envelope);
+
+  return { envelope, envelopePath: path, command: rest[0], args: rest.slice(1), ledgerPath, filterToolList };
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Enforce an intent envelope on an MCP server, in the wire protocol itself.
+ *
+ * The command in bin.ts is the usual way to use this. These exports are for embedding
+ * the relay in a host that already owns its own process and streams.
+ */
+
+export { ConfigError, USAGE, parse, type Config } from './config.ts';
+export { fileLedger, memoryLedger, type Ledger } from './ledger.ts';
+export { DENIED, ESCALATION_REQUIRED, Relay, type RelayOptions } from './relay.ts';
+
+export const VERSION = '0.2.0';

package/src/ledger.ts

@@ -0,0 +1,61 @@
+/**
+ * Every decision, appended as it is made.
+ *
+ * Refusals are recorded, not only successes. A log holding what succeeded cannot answer
+ * the question an incident asks, which is what the agent tried to do.
+ *
+ * One JSON object per line, append only, flushed per decision. A ledger that buffers
+ * loses exactly the records an operator wants when a process is killed mid-run, and the
+ * run where that happens is the interesting one.
+ */
+
+import { appendFileSync } from 'node:fs';
+import type { Decision, DecisionRecord } from 'intent-envelope';
+
+export interface Ledger {
+  record(decision: Decision): void;
+  entries(): DecisionRecord[];
+}
+
+/** Keeps decisions in memory only. Used by the tests and when no path is configured. */
+export function memoryLedger(): Ledger {
+  const held: DecisionRecord[] = [];
+  return {
+    record: (decision) => {
+      held.push(decision.record());
+    },
+    entries: () => held.slice(),
+  };
+}
+
+/**
+ * Appends to a file as well as keeping them in memory.
+ *
+ * A failed write must not take the enforcement point down with it: refusing calls
+ * correctly while unable to log is a degraded state, but silently allowing them because
+ * a disk filled up is a breach. So a write failure is reported once, to stderr, and
+ * enforcement carries on.
+ */
+export function fileLedger(path: string, onError?: (message: string) => void): Ledger {
+  const memory = memoryLedger();
+  let warned = false;
+
+  return {
+    record: (decision) => {
+      memory.record(decision);
+      try {
+        appendFileSync(path, `${JSON.stringify(decision.record())}\n`, 'utf8');
+      } catch (error) {
+        if (!warned) {
+          warned = true;
+          const reason = error instanceof Error ? error.message : String(error);
+          (onError ?? ((m: string) => process.stderr.write(`${m}\n`)))(
+            `[intent-envelope] cannot write the ledger to ${path}: ${reason}. ` +
+              'Enforcement continues; decisions are kept in memory only.',
+          );
+        }
+      }
+    },
+    entries: () => memory.entries(),
+  };
+}