@ratifia/mcp 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ratifia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# ratifia-mcp
+
+Human-in-the-loop for AI agents. This [MCP](https://modelcontextprotocol.io) server lets an agent (Claude Code, Claude Desktop, etc.) **pause on a human decision mid-task and resume once it's answered** — the agent is the "engine", [Ratifia](https://ratifia.com) owns the decision, notification, and verdict.
+
+## Install
+
+Published on npm as [`@ratifia/mcp`](https://www.npmjs.com/package/@ratifia/mcp).
+Add it to your MCP client — `npx` fetches and runs it:
+
+```json
+{
+  "mcpServers": {
+    "ratifia": {
+      "command": "npx",
+      "args": ["-y", "@ratifia/mcp"],
+      "env": {
+        "RATIFIA_API_KEY": "your-org-worker-api-key",
+        "RATIFIA_APPROVER_EMAIL": "you@example.com"
+      }
+    }
+  }
+}
+```
+
+Point separate registrations at different environments by giving each its own `RATIFIA_API_URL` + key (e.g. `ratifia-stg` and `ratifia-prod`).
+
+### Local clone (development)
+
+```json
+{
+  "mcpServers": {
+    "ratifia": {
+      "command": "node",
+      "args": ["/absolute/path/to/ratifia-mcp/dist/index.js"],
+      "env": {
+        "RATIFIA_API_KEY": "your-org-worker-api-key",
+        "RATIFIA_APPROVER_EMAIL": "you@example.com"
+      }
+    }
+  }
+}
+```
+
+Clone, then `npm install && npm run build` (rebuild after source changes). Use
+`npx tsx src/index.ts` instead of the built file to skip the build step while iterating.
+
+## Configuration (env)
+
+| Var | Required | Default | Purpose |
+|-----|----------|---------|---------|
+| `RATIFIA_API_KEY` | ✅ | — | Org-scoped worker API key. |
+| `RATIFIA_API_URL` | | `https://api.ratifia.com` | Ratifia API base. |
+| `RATIFIA_APP_URL` | | `https://app.ratifia.com` | Dashboard base for decision links. |
+| `RATIFIA_APPROVER_EMAIL` | | — | Who the decision is assigned to / notified. |
+| `RATIFIA_POLICY` | | — | Named policy whose route decides **how** you're notified (e.g. to your phone). |
+
+Routing (email / SMS / escalation) is decided **inside Ratifia** by your org's policy — this server is a thin request/verdict bridge.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `request_decision` | Create a decision, notify the human, return a `decision_id`. |
+| `check_decision` | Poll a decision's status once. |
+| `await_decision` | Block until the verdict lands (or a max wait elapses). |
+| `list_pending_decisions` | The agent's inbox — what's outstanding. |
+| `cancel_decision` | Withdraw a decision the agent no longer needs. |
+
+## Decision shapes
+
+`request_decision` isn't only yes/no. Shape the answer with `response_type`:
+
+| `response_type` | The human… | You read the answer from |
+|-----------------|-----------|--------------------------|
+| `approval` (default) | approves or rejects | `verdict` (+ `note`) |
+| `select` | picks from `options` you provide (set `allow_multiple` for many) | `response_value.selected` (option ids → labels via `response_spec.options`) |
+| `text` | types a value | `response_value.text` |
+
+```
+request_decision(
+  title: "Which environment?",
+  question: "Where should I deploy?",
+  response_type: "select",
+  options: [{ label: "Staging" }, { label: "Production" }]
+)
+```
+
+### Conversational Approvals — propose a draft, get it refined
+
+Pass `proposed_output` to attach an **editable draft** (e.g. an email you want to
+send). The human refines it in conversation — in the dashboard or by replying in the
+Slack thread — and you get **their** final version back:
+
+```
+request_decision(
+  title: "Send welcome email",
+  question: "Review this before I send it.",
+  proposed_output: { title: "Welcome email", content: "<your draft>" }
+)
+```
+
+When it resolves, `await_decision` / `check_decision` return the final text in
+`output.content` (with a `refined` flag telling you whether the human changed it).
+**Act on `output.content`, not the draft you sent** — it may differ.
+
+### Gate a specific tool call — show what you'd run
+
+When the decision gates a concrete tool/function call, pass `tool_name` (and
+`tool_args`). The reviewer sees a structured **Tool call** panel — the exact
+action and arguments — instead of it being buried in free-text `context`:
+
+```
+request_decision(
+  title: "Approve refund?",
+  question: "This exceeds the $5,000 auto-approve floor.",
+  tool_name: "issue_refund",
+  tool_args: { amount_cents: 600000, currency: "USD", claim_id: "ACM-2024-00003" }
+)
+```
+
+`tool_args` is optional (some tools take none); it's ignored unless `tool_name`
+is set.
+
+## How it works
+
+1. The agent calls `request_decision` before a consequential/irreversible step (deploy, delete, spend, send externally), an ambiguous call it shouldn't guess, or to get a human to pick/refine something.
+2. Ratifia notifies the human (even away from keyboard) per the org's routing.
+3. The agent `await_decision`s (or polls `check_decision`) — read `verdict`/`note`, plus `response_value` (select/text) or `output` (a refined draft).
+4. The agent proceeds only on `approved`; on `rejected`/`expired` it adapts.
+
+Learn more at [ratifia.com](https://ratifia.com).

package/dist/index.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * Ratifia MCP server (HITL for AI agents).
+ *
+ * Exposes tools so an agent (e.g. Claude Code) can park on a human decision
+ * mid-task and resume once it's answered — the agent is the "engine", Ratifia
+ * owns the decision + notification + verdict:
+ *   - request_decision : create a Ratifia decision, notify the human (per the
+ *                        org's routing), return a decision_id.
+ *   - check_decision   : poll the verdict once (pending → approved/rejected + note).
+ *   - await_decision   : block until the verdict lands (or a max wait elapses),
+ *                        so the agent doesn't have to poll in a loop.
+ *   - list_pending_decisions : the agent's own inbox — what's outstanding.
+ *   - cancel_decision  : withdraw a decision the agent no longer needs.
+ *
+ * Routing (HOW a human is reached — email/SMS/phone/escalation) is decided
+ * INSIDE Ratifia by the org's policy/route, never by this client. The MCP is a
+ * thin request/verdict bridge.
+ *
+ * Config via env (so `ratifia-prod` and `ratifia-stg` are just two registrations
+ * pointing at different API URLs / keys):
+ *   RATIFIA_API_URL         API base (default https://api.ratifia.com)
+ *   RATIFIA_API_KEY         org-scoped worker API key (required)
+ *   RATIFIA_APP_URL         dashboard base for the decision link (default https://app.ratifia.com)
+ *   RATIFIA_APPROVER_EMAIL  who the decision is assigned to / notified
+ *   RATIFIA_POLICY          optional: policy name whose route decides HOW you're notified
+ *                           (e.g. a route to your phone)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+const API_URL = (process.env.RATIFIA_API_URL ?? 'https://api.ratifia.com').replace(/\/+$/, '');
+const API_KEY = process.env.RATIFIA_API_KEY;
+const APP_URL = (process.env.RATIFIA_APP_URL ?? 'https://app.ratifia.com').replace(/\/+$/, '');
+const APPROVER_EMAIL = process.env.RATIFIA_APPROVER_EMAIL;
+const POLICY = process.env.RATIFIA_POLICY;
+if (!API_KEY) {
+    console.error('RATIFIA_API_KEY is required');
+    process.exit(1);
+}
+async function api(path, init) {
+    const res = await fetch(`${API_URL}${path}`, {
+        ...init,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${API_KEY}`,
+            ...(init?.headers ?? {}),
+        },
+    });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`Ratifia ${path} → ${res.status}: ${text.slice(0, 300)}`);
+    return (text ? JSON.parse(text) : {});
+}
+const getDecision = (id) => api(`/v1/worker/decisions/${encodeURIComponent(id)}`, { method: 'GET' });
+/** Agent-facing shape for a decision's current state. */
+const formatDecision = (d) => ({
+    decision_id: d.id,
+    status: d.status, // PENDING | APPROVED | REJECTED | EXPIRED
+    verdict: d.decision, // approve | reject | null
+    note: d.note, // the human's free-text input/answer — read and follow it
+    // FN-181: for a select/text decision the real answer is here, not in `note`.
+    // `response_value.selected` holds the chosen option id(s); map them back to
+    // labels via `response_spec.options`. `response_value.text` holds a typed value.
+    ...(d.responseSpec ? { response_spec: d.responseSpec } : {}),
+    ...(d.responseValue ? { response_value: d.responseValue } : {}),
+    // FN-185: if you sent a proposed_output (e.g. a draft email), the human may
+    // have refined it (in the dashboard or a Slack thread). `output.content` is the
+    // effective final text to act on — use it over your original draft.
+    ...(d.output ? { output: d.output, refined: Boolean(d.refinedOutput) } : {}),
+    decided_by: d.decidedBy,
+    decided_at: d.decidedAt,
+});
+const asToolResult = (payload) => ({
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+});
+function buildResponseSpec(responseType, options, allowMultiple) {
+    if (!responseType || responseType === 'approval')
+        return undefined;
+    if (responseType === 'text')
+        return { type: 'text' };
+    // select
+    const seen = new Set();
+    const specOptions = (options ?? []).map((o, i) => {
+        // Cap at 40: option ids ride in a Discord button custom_id (100-char limit)
+        // alongside the 28-char decision id, so keep them short.
+        let id = (o.label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || `opt-${i}`).slice(0, 40);
+        while (seen.has(id))
+            id = `${id}-${i}`;
+        seen.add(id);
+        return { id, label: o.label, ...(o.description ? { description: o.description } : {}) };
+    });
+    return {
+        type: 'select',
+        options: specOptions,
+        min: 1,
+        max: allowMultiple ? specOptions.length : 1,
+    };
+}
+const server = new McpServer({ name: 'ratifia', version: '0.4.0' }, {
+    instructions: [
+        'Ratifia lets you request a HUMAN decision or input mid-task (human-in-the-loop) and resume once it is answered.',
+        '',
+        'When to use request_decision: before a consequential or irreversible action (prod deploy, delete/drop, data migration, spending, sending something externally, credential rotation), or when a requirement is ambiguous and guessing wrong would be costly. Skip it for trivial, reversible, or clearly-authorized steps — that is just friction.',
+        '',
+        'Workflow:',
+        '1. Call request_decision with a short title, a precise question, and enough context to decide (the command/diff/options + tradeoffs). Set timeout_minutes if it is time-sensitive.',
+        '2. It returns a decision_id (+ url). The human is notified and may be away from their keyboard, so a verdict can take a while. (If the org policy auto-resolved that no approval was needed, it returns approval_required=false — just proceed.)',
+        '3. Wait for the verdict: prefer await_decision (it blocks until answered) over polling check_decision in a loop. Either way, "approved"/"rejected" comes with a note — the note is the human\'s actual answer/input, so read and follow it. If you asked for a choice/typed value (response_type select/text), the answer is in response_value (selected option ids — map them back via response_spec.options — or text), not just the note.',
+        '4. Do NOT perform the gated action until it resolves approved. On rejected or expired, do not proceed — adapt or ask again.',
+        'Refining content: to have a human review/edit a draft (e.g. an email you want to send), pass proposed_output.content. They can refine it (in the dashboard or by replying in the Slack thread); once approved, use output.content as the final text — it may differ from what you sent.',
+        'Prefer one well-scoped decision with rich context over many small ones.',
+    ].join('\n'),
+});
+server.tool('request_decision', 'Ask the human for a decision or input before proceeding (human-in-the-loop). Creates a Ratifia decision, notifies them (even away from keyboard), and returns a decision_id to await/poll. Use whenever you need approval, a choice, or input you should not assume. Set response_type to shape the answer: "approval" (yes/no, default), "select" (pick from options you provide), or "text" (a typed value) — for select/text the answer comes back in response_value. To have a human refine a draft (e.g. an email), pass proposed_output — the approved/edited text comes back in output.content. If this decision gates a specific tool/function call, pass tool_name (and tool_args) so the reviewer sees a structured "Tool call" panel of exactly what you would run.', {
+    title: z.string().describe('Short title, e.g. "Deploy API to prod?"'),
+    question: z.string().describe('Exactly what you need the human to decide or provide.'),
+    context: z
+        .string()
+        .optional()
+        .describe('Details to help them decide: options, tradeoffs, a diff, the command you would run.'),
+    timeout_minutes: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Auto-expire (and reject) if unanswered after N minutes. Omit to wait indefinitely.'),
+    response_type: z
+        .enum(['approval', 'select', 'text'])
+        .optional()
+        .describe("What kind of answer you need. 'approval' (default) = yes/no gate. 'select' = the human picks from `options`. 'text' = the human types a value. For select/text, read the answer from `response_value` (not just `note`)."),
+    options: z
+        .array(z.object({
+        label: z.string().describe('What the human sees for this choice.'),
+        description: z.string().optional().describe('Optional one-line clarification of the choice.'),
+    }))
+        .min(2)
+        .optional()
+        .describe("The choices for a 'select' decision (at least 2). Required when response_type is 'select'."),
+    allow_multiple: z
+        .boolean()
+        .optional()
+        .describe("For 'select': allow picking more than one option (default single-choice)."),
+    proposed_output: z
+        .object({
+        title: z.string().optional().describe('Short label for the artifact, e.g. "Email body".'),
+        content: z.string().describe('The draft the human can edit before approving (e.g. the email text).'),
+    })
+        .optional()
+        .describe('A draft artifact the human can refine before approving — e.g. an email you propose to send. They can edit it (in the dashboard or by replying in the Slack thread); on approval the final text comes back in `output.content`. Use this when you want a human to review/refine content, not just say yes/no.'),
+    tool_name: z
+        .string()
+        .optional()
+        .describe('The tool/function this decision gates, e.g. "issue_refund" or "delete_database". Shown to the reviewer as a structured "Tool call" panel — the concrete action you would take if approved.'),
+    tool_args: z
+        .record(z.unknown())
+        .optional()
+        .describe('The arguments you would call `tool_name` with, as an object, e.g. { "amount_cents": 600000, "currency": "USD" }. Displayed next to the tool name. Ignored unless `tool_name` is set.'),
+}, async ({ title, question, context, timeout_minutes, response_type, options, allow_multiple, proposed_output, tool_name, tool_args }) => {
+    if (response_type === 'select' && (!options || options.length < 2)) {
+        return asToolResult({
+            error: 'invalid_request',
+            message: "response_type 'select' requires at least 2 options.",
+        });
+    }
+    const responseSpec = buildResponseSpec(response_type, options, allow_multiple);
+    const externalRunId = `mcp-${Date.now()}-${Math.round(Math.random() * 1e6)}`;
+    // Structured context blocks (FN-83): a tool_call panel when the agent names
+    // the tool it's gating, plus any free-text context. Order = display order.
+    const contextBlocks = [];
+    if (tool_name) {
+        contextBlocks.push({ kind: 'tool_call', title: 'Tool call', tool: tool_name, args: tool_args ?? {} });
+    }
+    if (context) {
+        contextBlocks.push({ kind: 'text', title, text: context });
+    }
+    const res = await api('/v1/worker/decisions', {
+        method: 'POST',
+        body: JSON.stringify({
+            // The agent is its own "engine" — it polls (check/await) for the
+            // verdict rather than parking on an engine resume event.
+            engine: 'mcp',
+            externalRunId,
+            stepRef: title.slice(0, 80),
+            workflowRef: 'ratifia-mcp',
+            ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
+            ...(POLICY ? { policy: POLICY } : {}),
+            required: true,
+            ...(timeout_minutes ? { timeoutSec: timeout_minutes * 60 } : {}),
+            ...(responseSpec ? { responseSpec } : {}),
+            ...(proposed_output
+                ? { proposedOutput: { title: proposed_output.title, format: 'text', content: proposed_output.content } }
+                : {}),
+            context: {
+                prompt: question,
+                ...(contextBlocks.length ? { blocks: contextBlocks } : {}),
+            },
+        }),
+    });
+    // The policy gate can resolve "no approval needed" — no decision is created.
+    // Tell the agent it may just proceed, rather than returning a bogus id/url.
+    if (res.approvalNeeded === false || !res.decisionId) {
+        return asToolResult({
+            approval_required: false,
+            status: 'not_required',
+            reason: res.reason ?? 'policy_gate_not_required',
+            note: 'Ratifia policy did not require a human decision — you may proceed.',
+        });
+    }
+    return asToolResult({
+        approval_required: true,
+        decision_id: res.decisionId,
+        status: 'pending',
+        url: `${APP_URL}/decisions/${res.decisionId}`,
+    });
+});
+server.tool('check_decision', "Check a Ratifia decision's status ONCE (non-blocking). Returns 'pending' until the human acts, then 'approved'/'rejected' plus their note (their input/answer). Prefer await_decision if you just want to wait for the verdict.", {
+    decision_id: z.string().describe('The decision_id returned by request_decision.'),
+}, async ({ decision_id }) => asToolResult(formatDecision(await getDecision(decision_id))));
+server.tool('await_decision', "Block until a Ratifia decision resolves (or max_wait_seconds elapses), so you don't have to poll in a loop. Returns as soon as the human acts ('approved'/'rejected' + their note), or status 'pending' with timed_out=true if still unanswered after the wait — just call await_decision again to keep waiting. Use this after request_decision to wait for the verdict.", {
+    decision_id: z.string().describe('The decision_id returned by request_decision.'),
+    max_wait_seconds: z
+        .number()
+        .int()
+        .positive()
+        .max(240)
+        .optional()
+        .describe('How long to block before returning (default 60, max 240). If still pending, call again to keep waiting.'),
+}, async ({ decision_id, max_wait_seconds }) => {
+    const budgetMs = (max_wait_seconds ?? 60) * 1000;
+    const pollMs = 4000;
+    const start = Date.now();
+    let d = await getDecision(decision_id);
+    while (d.status === 'PENDING' && Date.now() - start + pollMs <= budgetMs) {
+        await new Promise((r) => setTimeout(r, pollMs));
+        d = await getDecision(decision_id);
+    }
+    return asToolResult({
+        ...formatDecision(d),
+        ...(d.status === 'PENDING' ? { timed_out: true } : {}),
+    });
+});
+server.tool('list_pending_decisions', 'List the decisions you have outstanding with Ratifia (default: still-pending), newest first. Use to reconcile after a restart, or to see what you are waiting on before deciding whether to keep waiting or cancel.', {
+    status: z
+        .enum(['PENDING', 'APPROVED', 'REJECTED', 'EXPIRED', 'CANCELLED'])
+        .optional()
+        .describe('Filter by status. Omit for PENDING (your outstanding asks).'),
+    limit: z.number().int().positive().max(200).optional().describe('Max to return (default 50).'),
+}, async ({ status, limit }) => {
+    const qs = new URLSearchParams({ status: status ?? 'PENDING' });
+    if (limit)
+        qs.set('limit', String(limit));
+    const res = await api(`/v1/worker/decisions?${qs.toString()}`, {
+        method: 'GET',
+    });
+    return asToolResult({ count: res.decisions.length, decisions: res.decisions });
+});
+server.tool('cancel_decision', 'Withdraw a decision you requested but no longer need (the task was aborted or the question became moot). Resolves it and stops notifying the human. Only PENDING decisions cancel; an already-answered one is returned unchanged (cancelled=false).', {
+    decision_id: z.string().describe('The decision_id returned by request_decision.'),
+    note: z.string().optional().describe('Optional reason, recorded on the decision.'),
+}, async ({ decision_id, note }) => asToolResult(await api(`/v1/worker/decisions/${encodeURIComponent(decision_id)}/cancel`, {
+    method: 'POST',
+    body: JSON.stringify(note ? { note } : {}),
+})));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`ratifia-mcp connected → ${API_URL}`);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ratifia/mcp",
+  "version": "0.4.0",
+  "type": "module",
+  "description": "Ratifia MCP server — let an AI agent request a human decision/approval (HITL) mid-task and resume once it's answered. The agent becomes a Ratifia 'engine'.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "hitl",
+    "human-in-the-loop",
+    "approval",
+    "ai-agent",
+    "ratifia"
+  ],
+  "homepage": "https://ratifia.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/themillhouse/ratifia-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/themillhouse/ratifia-mcp/issues"
+  },
+  "license": "MIT",
+  "bin": {
+    "ratifia-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepare": "tsc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}