@reunionstudio/airlock-mcp 0.1.0

package/src/cli.mjs

@@ -0,0 +1,89 @@
+import { DEFAULT_PACKAGE_SPEC, DEFAULT_SERVER_NAME, helpText } from "./text.mjs";
+import { installCodexServer } from "./install.mjs";
+import { runServer } from "./mcp.mjs";
+
+export function parseArgs(argv) {
+  const parsed = {
+    command: argv[0],
+    project: "Home",
+    serverName: DEFAULT_SERVER_NAME,
+    packageSpec: DEFAULT_PACKAGE_SPEC,
+    dryRun: false,
+    help: false,
+  };
+  for (let index = 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+    } else if (arg === "--project") {
+      if (!argv[index + 1] || argv[index + 1].startsWith("--")) {
+        throw new Error("--project requires a value");
+      }
+      parsed.project = argv[index + 1] || parsed.project;
+      index += 1;
+    } else if (arg === "--name") {
+      if (!argv[index + 1] || argv[index + 1].startsWith("--")) {
+        throw new Error("--name requires a value");
+      }
+      parsed.serverName = argv[index + 1] || parsed.serverName;
+      index += 1;
+    } else if (arg === "--package") {
+      if (!argv[index + 1] || argv[index + 1].startsWith("--")) {
+        throw new Error("--package requires a value");
+      }
+      parsed.packageSpec = argv[index + 1] || parsed.packageSpec;
+      index += 1;
+    } else if (arg === "--dry-run") {
+      parsed.dryRun = true;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  return parsed;
+}
+
+export async function main(argv = process.argv.slice(2), io = process) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (error) {
+    io.stderr.write(`error: ${error.message}\n`);
+    return 2;
+  }
+
+  if (!args.command || args.help) {
+    io.stdout.write(helpText());
+    return 0;
+  }
+
+  if (args.command === "install") {
+    try {
+      const result = installCodexServer({
+        project: args.project,
+        serverName: args.serverName,
+        packageSpec: args.packageSpec,
+        dryRun: args.dryRun,
+        beforeRun: (text) => io.stdout.write(text),
+      });
+      if (result.stdout) {
+        io.stdout.write(result.stdout);
+      }
+      if (result.stderr) {
+        io.stderr.write(result.stderr);
+      }
+      return result.status;
+    } catch (error) {
+      io.stderr.write(`error: ${error.message}\n`);
+      return 2;
+    }
+  }
+
+  if (args.command === "server") {
+    await runServer();
+    return 0;
+  }
+
+  io.stderr.write(`error: unknown command: ${args.command}\n`);
+  io.stdout.write(helpText());
+  return 2;
+}

package/src/install.mjs

@@ -0,0 +1,100 @@
+import { spawnSync } from "node:child_process";
+
+import { DEFAULT_PACKAGE_SPEC, DEFAULT_SERVER_NAME, nextSteps } from "./text.mjs";
+
+const SERVER_NAME_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;
+const PACKAGE_SPEC_MAX_LENGTH = 200;
+
+export function validateServerName(value) {
+  if (!SERVER_NAME_PATTERN.test(value || "")) {
+    throw new Error("server name must be 1-64 characters: letters, numbers, dot, underscore, or hyphen");
+  }
+  return value;
+}
+
+export function validatePackageSpec(value) {
+  const packageSpec = String(value || "");
+  if (
+    packageSpec.length < 1 ||
+    packageSpec.length > PACKAGE_SPEC_MAX_LENGTH ||
+    /[\s\u0000-\u001f\u007f]/.test(packageSpec)
+  ) {
+    throw new Error("package spec must be 1-200 characters with no whitespace or control characters");
+  }
+  return packageSpec;
+}
+
+export function shellQuote(value) {
+  if (/^[a-zA-Z0-9_./:@=-]+$/.test(value)) {
+    return value;
+  }
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+export function codexInstallArgs(serverName = DEFAULT_SERVER_NAME, packageSpec = DEFAULT_PACKAGE_SPEC) {
+  return [
+    "mcp",
+    "add",
+    validateServerName(serverName),
+    "--",
+    "npx",
+    "-y",
+    validatePackageSpec(packageSpec),
+    "server",
+  ];
+}
+
+export function codexInstallCommand(serverName = DEFAULT_SERVER_NAME, packageSpec = DEFAULT_PACKAGE_SPEC) {
+  return ["codex", ...codexInstallArgs(serverName, packageSpec)].map(shellQuote).join(" ");
+}
+
+export function installCodexServer({
+  project = "Home",
+  serverName = DEFAULT_SERVER_NAME,
+  packageSpec = DEFAULT_PACKAGE_SPEC,
+  dryRun = false,
+  beforeRun = () => {},
+  spawn = spawnSync,
+} = {}) {
+  const command = codexInstallCommand(serverName, packageSpec);
+  const intro = `Airlock MCP install
+
+Registering Codex MCP server:
+  ${command}
+`;
+
+  if (dryRun) {
+    return {
+      status: 0,
+      stdout: `${intro}
+dry-run: not running registration.
+
+${nextSteps(project)}
+`,
+    };
+  }
+
+  beforeRun(`${intro}\n`);
+  const result = spawn("codex", codexInstallArgs(serverName, packageSpec), { stdio: "inherit" });
+  if (result.error) {
+    return {
+      status: 1,
+      stderr: `error: could not run codex: ${result.error.message}
+Run this command manually after Codex is installed:
+  ${command}
+`,
+    };
+  }
+  if (result.status !== 0) {
+    return { status: result.status || 1 };
+  }
+
+  return {
+    status: 0,
+    stdout: `
+installed: Codex MCP server '${serverName}'
+
+${nextSteps(project)}
+`,
+  };
+}

package/src/mcp.mjs

@@ -0,0 +1,184 @@
+import readline from "node:readline";
+
+import { PROTOCOL_VERSION, airlockPrompt, gettingStartedText } from "./text.mjs";
+import { WORKBENCH_TOOLS, callWorkbenchTool } from "./workbench.mjs";
+
+const GETTING_STARTED_URI = "airlock://getting-started";
+
+const START_TOOL = {
+  name: "airlock_start",
+  description: "Return Airlock MCP setup guidance for building and using Airlock specs.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project: {
+        type: "string",
+        description: "Project or organization name, for example Home.",
+        maxLength: 80,
+      },
+    },
+    additionalProperties: false,
+  },
+};
+
+export const AIRLOCK_TOOLS = [START_TOOL, ...WORKBENCH_TOOLS];
+
+export function makeResponse(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+export function makeError(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+export function handleMcpRequest(message) {
+  const { id, method, params } = message;
+
+  if (method === "initialize") {
+    return makeResponse(id, {
+      protocolVersion: params?.protocolVersion || PROTOCOL_VERSION,
+      capabilities: {
+        prompts: {},
+        resources: {},
+        tools: {},
+      },
+      serverInfo: {
+        name: "airlock",
+        version: "0.1.0",
+      },
+      instructions:
+        "Airlock MCP helps agents build and use Airlock specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",
+    });
+  }
+
+  if (method === "notifications/initialized") {
+    return undefined;
+  }
+
+  if (method === "tools/list") {
+    return makeResponse(id, { tools: AIRLOCK_TOOLS });
+  }
+
+  if (method === "tools/call") {
+    const name = params?.name || "";
+    if (name === "airlock_start") {
+      const project = params?.arguments?.project || "Home";
+      return makeResponse(id, {
+        content: [{ type: "text", text: gettingStartedText(project) }],
+      });
+    }
+    try {
+      const result = callWorkbenchTool(name, params?.arguments || {});
+      if (result) {
+        return makeResponse(id, result);
+      }
+      return makeError(id, -32602, `unknown tool: ${name}`);
+    } catch (error) {
+      return makeError(id, -32602, error.message);
+    }
+  }
+
+  if (method === "prompts/list") {
+    return makeResponse(id, {
+      prompts: [
+        {
+          name: "airlock-start",
+          title: "Start Airlock",
+          description: "Bootstrap a blank specs repo and choose the first Airlock path.",
+          arguments: [
+            {
+              name: "project",
+              description: "Project or organization name, for example Home.",
+              required: false,
+            },
+          ],
+        },
+      ],
+    });
+  }
+
+  if (method === "prompts/get") {
+    if (params?.name !== "airlock-start") {
+      return makeError(id, -32602, `unknown prompt: ${params?.name || ""}`);
+    }
+    const project = params?.arguments?.project || "Home";
+    return makeResponse(id, {
+      description: "Start building and using Airlock specs in a blank specs repo.",
+      messages: [
+        {
+          role: "user",
+          content: { type: "text", text: airlockPrompt(project) },
+        },
+      ],
+    });
+  }
+
+  if (method === "resources/list") {
+    return makeResponse(id, {
+      resources: [
+        {
+          uri: GETTING_STARTED_URI,
+          name: "Airlock getting started",
+          description: "How to start building and using Airlock specs with Codex.",
+          mimeType: "text/markdown",
+        },
+      ],
+    });
+  }
+
+  if (method === "resources/read") {
+    if (params?.uri !== GETTING_STARTED_URI) {
+      return makeError(id, -32602, `unknown resource: ${params?.uri || ""}`);
+    }
+    return makeResponse(id, {
+      contents: [
+        {
+          uri: params.uri,
+          mimeType: "text/markdown",
+          text: gettingStartedText("Home"),
+        },
+      ],
+    });
+  }
+
+  return makeError(id, -32601, `method not found: ${method}`);
+}
+
+export function encodeMessage(message) {
+  return `${JSON.stringify(message)}\n`;
+}
+
+export async function runServer({ input = process.stdin, output = process.stdout } = {}) {
+  const rl = readline.createInterface({
+    input,
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of rl) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch (_error) {
+      output.write(encodeMessage(makeError(null, -32700, "parse error")));
+      continue;
+    }
+
+    if (message.id === undefined) {
+      handleMcpRequest(message);
+      continue;
+    }
+
+    try {
+      const response = handleMcpRequest(message);
+      if (response) {
+        output.write(encodeMessage(response));
+      }
+    } catch (error) {
+      output.write(encodeMessage(makeError(message.id, -32603, error.message)));
+    }
+  }
+}

package/src/text.mjs

@@ -0,0 +1,108 @@
+export const PACKAGE_NAME = "@reunionstudio/airlock-mcp";
+export const DEFAULT_PACKAGE_SPEC = PACKAGE_NAME;
+export const DEFAULT_SERVER_NAME = "airlock";
+export const PROTOCOL_VERSION = "2025-06-18";
+
+export function slug(value) {
+  const cleaned = String(value || "project")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return cleaned || "project";
+}
+
+export function specsRepoName(project) {
+  const value = slug(project);
+  return value.endsWith("-specs") ? value : `${value}-specs`;
+}
+
+export function airlockPrompt(project) {
+  const repoName = specsRepoName(project);
+  return `I want to use Airlock MCP to start working with Airlock specs for ${repoName}.
+
+Set up this project as an Airlock specs repo. Use Airlock MCP
+spec-building when we need to draft or revise specs. Welcome me,
+help me think through real Airlock use cases, and ask only for the missing
+decisions. Do not create the first workspace until I choose a path.`;
+}
+
+export function nextSteps(project) {
+  const repoName = specsRepoName(project);
+  return `Next:
+  1. Open Codex.
+  2. Create a new blank project named ${repoName}.
+  3. Ask Codex:
+
+${airlockPrompt(project)
+  .split("\n")
+  .map((line) => `     ${line}`)
+  .join("\n")}
+
+Airlock MCP will offer:
+  - spec-building with the bundled workbench
+  - spec use and improvement loops with Airlock Star
+  - guidance for pulling and pushing governed data through specs
+  - OODA brainstorming for possible specs
+  - a blank workspace for a known process
+  - a posts feedback loop for shared human/agent feedback`;
+}
+
+export function gettingStartedText(project) {
+  return `# Airlock MCP
+
+Airlock MCP is the single installed interface for AI agents working with
+Airlock. It helps a person and their agent build specs, pull and push governed data
+through specs, and improve Airlock workflows from real use cases.
+
+The Airlock MCP spec-building workbench drafts, checks, revises, imports,
+clones, and prepares specs for installed Airlock validation.
+
+Airlock Star is the use-and-improve capability inside Airlock MCP. Use it when
+someone wants to pull or push governed data through specs, exercise real
+Airlock workflows, inspect outputs, or turn field experience into spec
+improvements.
+
+Start in a blank project specs repo such as ${specsRepoName(project)}. Do not
+work inside the Airlock MCP implementation repo unless you are changing the
+tools themselves.
+
+Use this prompt in the blank specs repo:
+
+${airlockPrompt(project)}
+
+After bootstrap, choose the next useful path:
+
+1. Brainstorm possible specs using the OODA loop.
+2. Start from a known process and create a blank workspace.
+3. Create a posts feedback loop for humans and agents to submit requests,
+   observations, and responses.
+4. Use Airlock Star with an installed Airlock app to validate specs, load data,
+   read outputs, plan push/pull workflows, and capture improvements.
+
+Create posts only when the user chooses the feedback-loop path.`;
+}
+
+export function helpText() {
+  return `airlock-mcp
+
+Usage:
+  npx @reunionstudio/airlock-mcp install [--project <name>] [--name <server-name>] [--package <spec>] [--dry-run]
+  npx @reunionstudio/airlock-mcp server
+
+Commands:
+  install   Register the Airlock MCP server with Codex.
+  server    Run the Airlock MCP stdio server.
+
+Options:
+  --project <name>      Show next steps using <name>-specs.
+  --name <server-name>  Codex MCP server name. Defaults to airlock.
+  --package <spec>      npm or GitHub package spec for the registered server.
+  --dry-run             Print the Codex registration command without running it.
+  --help                Show this help.
+
+Airlock MCP is the single installed interface for agents working with Airlock.
+Spec building is bundled inside that experience.
+Airlock Star is the use-and-improve capability inside that experience.
+`;
+}