@irtio/mcp 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ApiClient } from '@irtio/cli/api';
+
+/**
+ * D39: how an agent authenticates to the MCP server.
+ *
+ * Resolution order is the credential file `irtio login` writes, then `IRTIO_TOKEN` in the
+ * environment. When neither exists the first tool call returns a narrated instruction rather than
+ * an auth error, which is handled one layer up in `narrate.ts`; this module's job is only to say
+ * honestly which of the three states we are in.
+ *
+ * **A credential is never read from, or written to, this server's own config file.** The published
+ * config snippet contains a command and no secret. That is the whole reason the resolution order
+ * starts at the file the CLI already owns: the secret lives in one place, written once by a browser
+ * login, mode 0600, and the MCP server borrows it rather than being handed a copy.
+ *
+ * `IRTIO_TOKEN` is second rather than first because the file is the path a human actually takes.
+ * The env var exists for headless cases (CI, a container, this package's own end-to-end tests)
+ * where no browser login can happen.
+ */
+
+/** Why there is no usable credential. The two cases read differently to a human, so they are kept
+ *  apart even though the narration for both is "run `irtio login`". */
+type AuthFailure = 'no-credential' | 'expired';
+interface AuthResolved {
+    readonly ok: true;
+    readonly controlUrl: string;
+    readonly token: string;
+    /** Where the token came from. Reported by `whoami` so an operator can tell which one is in play. */
+    readonly source: 'credential-file' | 'env';
+    /** Present only when the credential file supplied it, and only ever the file's own record. */
+    readonly email: string | undefined;
+}
+interface AuthMissing {
+    readonly ok: false;
+    readonly controlUrl: string;
+    readonly reason: AuthFailure;
+}
+type AuthState = AuthResolved | AuthMissing;
+/** Environment seam, so tests do not have to mutate `process.env`. */
+interface AuthEnv {
+    readonly IRTIO_TOKEN?: string | undefined;
+}
+/**
+ * Resolves the control URL and a token, in D39's order.
+ *
+ * An **expired** file credential does not fall through to the env var. If somebody's login has
+ * expired, the fix is to log in again, and silently switching to a different identity would make
+ * every later tool result describe an account the caller did not think they were using.
+ */
+declare function resolveAuth(env?: AuthEnv, controlUrlFlag?: string): Promise<AuthState>;
+/** Thrown when there is no usable credential. `narrate.ts` turns it into the D39 instruction. */
+declare class NoCredentialError extends Error {
+    readonly controlUrl: string;
+    readonly reason: AuthFailure;
+    readonly name = "NoCredentialError";
+    constructor(controlUrl: string, reason: AuthFailure);
+}
+/** Resolves auth and builds the client, or throws `NoCredentialError`. */
+declare function requireClient(env?: AuthEnv, controlUrlFlag?: string): Promise<{
+    client: ApiClient;
+    auth: AuthResolved;
+}>;
+
+/**
+ * The MCP server itself: a tool registry, an auth resolution, and a narration layer, wired to the
+ * SDK's low-level `Server`.
+ *
+ * The low-level `Server` is used rather than the higher-level helper because the tool schemas here
+ * are plain JSON Schema. Going through the helper would mean authoring every schema in zod and
+ * taking a second runtime dependency to describe data this package never validates itself, since
+ * the control plane is the authority on every argument's meaning.
+ *
+ * One thing worth stating because it is easy to get wrong: this process speaks the MCP protocol on
+ * **stdout**. Nothing may print there. `console.error` is available for diagnostics and the deploy
+ * tool captures the CLI's own log lines into its result instead of letting them through.
+ */
+
+interface McpServerOptions {
+    /** Environment the D39 `IRTIO_TOKEN` fallback reads. Defaults to the real one. */
+    readonly env?: AuthEnv;
+    /** Control URL override. Normally left alone so the credential file decides. */
+    readonly controlUrl?: string;
+    /** Working directory the `deploy` tool bundles from. Defaults to the process's. */
+    readonly cwd?: string;
+}
+declare const SERVER_NAME = "irtio";
+declare const SERVER_VERSION = "0.5.2";
+/**
+ * Builds the server. It does not connect: the caller supplies a transport, which is what lets the
+ * contract tests drive it in process over a linked pair rather than over a real pipe.
+ */
+declare function createMcpServer(options?: McpServerOptions): Server;
+
+/**
+ * The narration layer, which is one function rather than one per tool (part 2 plan §1.4).
+ *
+ * D40's contract is that every tool result is prose plus structured data and **ends with the next
+ * action**. That is an acceptance criterion, not a nicety: a tool result is read by a model with a
+ * finite context window, and the difference between "here is a JSON blob" and "here is what
+ * happened and here is what to do about it" is the difference between an agent that takes the next
+ * step and one that guesses.
+ *
+ * Keeping the shape in a single formatter is what stops nineteen tools drifting into nineteen
+ * tones. A tool hands over three things — a summary sentence, the structured payload, and the next
+ * action — and this module owns everything else: the ordering, the "next:" prefix, and the way an
+ * error becomes a narrated result rather than a stack trace.
+ *
+ * Style rule (m3-plan working rules): tool output is user-facing copy. No em dashes, no LLM tells.
+ */
+/** The three things a tool decides. Everything else about the result shape is decided here. */
+interface Narration {
+    /** One or more sentences of prose. What happened, in the terms the caller asked in. */
+    readonly summary: string;
+    /** The machine-readable payload. Always an object, so the MCP `structuredContent` field fits. */
+    readonly data: Record<string, unknown>;
+    /** The next action, without the "next:" prefix. A command, or a named tool, or both. */
+    readonly next: string;
+}
+/** The MCP tool result shape, narrowed to what this server produces. */
+interface ToolResult {
+    readonly content: readonly {
+        readonly type: 'text';
+        readonly text: string;
+    }[];
+    readonly structuredContent: Record<string, unknown>;
+    readonly isError?: boolean;
+}
+/**
+ * The one place the result shape is decided: prose, then the payload as pretty JSON, then the next
+ * action. The JSON is repeated inside the text block on purpose. `structuredContent` is the field a
+ * client should read, but not every client surfaces it to the model, and a tool whose numbers are
+ * invisible half the time is worse than a tool that repeats itself.
+ */
+declare function narrate(n: Narration): ToolResult;
+/** The D39 login narration. Deliberately an instruction, not an error. */
+declare const LOGIN_NARRATION: string;
+/**
+ * Maps a thrown error to a narrated result. Central, so the auth story and the deploy 409 read the
+ * same way through every tool that can raise them.
+ *
+ * The cases that earn their own wording:
+ *
+ * - **401 and `NotLoggedInError`** become the D39 instruction. An agent that reads "unauthorized"
+ *   invents a fix; an agent that reads "run `irtio login`" runs it.
+ * - **409 `E_BREAKING_SCHEMA`** relays the server's own `changes` and `hint` verbatim. Control
+ *   classifies breaking versus additive authoritatively, and restating its verdict in other words
+ *   would be a second implementation of the thing D40 says not to reimplement.
+ * - **404 on a project route** says "not found in your organisation", because the API deliberately
+ *   answers 404 rather than 403 across orgs and this server must not leak the distinction back.
+ */
+declare function narrateError(err: unknown, toolName: string): ToolResult;
+
+/**
+ * The tool surface (part 2 plan §1.3, D40).
+ *
+ * Thin, flat, `verb_noun`, one tool per intent. Every tool is a narrated client call: it takes an
+ * `ApiClient`, hits exactly one control-plane route (deploy is the documented exception, and it
+ * borrows the CLI's handshake rather than writing a second one), and hands `narrate.ts` a summary,
+ * a payload and a next action.
+ *
+ * Two rules the descriptions follow, because a tool description is the only documentation an agent
+ * reliably reads:
+ *
+ * 1. **Say what it changes.** A reader deciding between `project_get` and `project_update` needs to
+ *    know which one writes before it calls one.
+ * 2. **Say what it costs.** `deploy` bundles and uploads and can drain live rooms; `logs` is a
+ *    cheap read. Those are not the same kind of call and the description says so.
+ *
+ * What is deliberately absent: anything that mutates outside the project (org settings, billing,
+ * fleet) is out of the surface entirely per D40, and there is no tool that reads a stored secret.
+ * `jwt_secret_mint` returns a plaintext secret exactly once because that is the only moment it
+ * exists to be returned; there is no route that reads one back and there must not be one.
+ */
+
+/**
+ * What a tool is handed. `cwd` matters to `deploy` and `scenario_run`, the two tools that read
+ * local files.
+ *
+ * `client` is optional because one tool does not need it. `scenario_run` runs bots against a local
+ * dev room and never speaks to the control plane, and failing a local verification run because a
+ * credential expired would be the wrong answer to the right question. Every other tool reads it
+ * through `api()`, which turns an absent client into the D39 login narration.
+ */
+interface ToolContext {
+    readonly client: ApiClient | undefined;
+    readonly controlUrl: string;
+    readonly cwd: string;
+}
+/** A JSON Schema object, kept loose: the MCP wire format wants plain JSON Schema, not a zod type. */
+type JsonSchema = Record<string, unknown>;
+interface ToolDef {
+    readonly name: string;
+    /**
+     * D41: this tool needs no control-plane credential. `scenario_run` runs bots against a local
+     * dev room, and a local verification must not fail because a login expired.
+     */
+    readonly local?: boolean;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    readonly run: (ctx: ToolContext, args: Record<string, unknown>) => Promise<Narration>;
+}
+/** The registry, read-only tools first, then mutations, then deploy (plan §3). */
+declare const TOOLS: readonly ToolDef[];
+declare function toolByName(name: string): ToolDef | undefined;
+
+export { type AuthEnv, type AuthMissing, type AuthResolved, type AuthState, LOGIN_NARRATION, type McpServerOptions, type Narration, NoCredentialError, SERVER_NAME, SERVER_VERSION, TOOLS, type ToolContext, type ToolDef, type ToolResult, createMcpServer, narrate, narrateError, requireClient, resolveAuth, toolByName };

package/dist/index.js

@@ -0,0 +1,26 @@
+import {
+  LOGIN_NARRATION,
+  NoCredentialError,
+  SERVER_NAME,
+  SERVER_VERSION,
+  TOOLS,
+  createMcpServer,
+  narrate,
+  narrateError,
+  requireClient,
+  resolveAuth,
+  toolByName
+} from "./chunk-VFNFDDNZ.js";
+export {
+  LOGIN_NARRATION,
+  NoCredentialError,
+  SERVER_NAME,
+  SERVER_VERSION,
+  TOOLS,
+  createMcpServer,
+  narrate,
+  narrateError,
+  requireClient,
+  resolveAuth,
+  toolByName
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@irtio/mcp",
+  "version": "0.6.0",
+  "description": "irtio MCP server: provision, deploy, observe and restore irtio rooms from a coding agent",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "irtio-mcp": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@irtio/cli": "0.6.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}