@ratifia/mcp 0.12.0 → 0.13.1

package/dist/server.d.ts

@@ -0,0 +1,22 @@
+import { McpServer, type McpHttpHandler } from '@modelcontextprotocol/server';
+import { type RatifiaConfig } from './client.js';
+export { ApiError, createClient, type RatifiaConfig } from './client.js';
+export interface ServerOptions {
+    version: string;
+    /** Hosted connector (FN-366): shorter waits, since remote clients time a tool call out sooner. */
+    hosted?: boolean;
+}
+/**
+ * The Ratifia MCP server: the same tools whether it runs over stdio
+ * (`npx @ratifia/mcp`) or hosted at the API's /mcp endpoint (FN-366). Build one
+ * per caller; it holds that caller's token.
+ */
+export declare function createRatifiaServer(cfg: RatifiaConfig, opts: ServerOptions): McpServer;
+/**
+ * FN-366: the hosted endpoint. A stateless Streamable HTTP handler that builds a
+ * fresh server per request from the caller's config — the host authenticates
+ * the request, then passes the config (token, default approver) in
+ * `authInfo.extra.ratifia`. A request without one is refused: the handler
+ * never reads credentials itself.
+ */
+export declare function createRatifiaMcpHandler(opts: Omit<ServerOptions, 'hosted'>): McpHttpHandler;

package/dist/server.js

@@ -0,0 +1,400 @@
+import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { apiRetry, ApiError, createClient, isUnknownPolicy, label, trimUrl, unknownPolicyMessage, who, } from './client.js';
+export { ApiError, createClient } from './client.js';
+/** 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 edited it in the Ratifia app (Slack can only approve or reject it).
+    // `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,
+    // FN-316: which version of the policy governed this decision, so an agent can
+    // cite it ("approved under refunds v3"). Stays put when the policy is edited.
+    policy_version: d.policyVersion ?? null,
+    policy_version_id: d.policyVersionId ?? null,
+});
+const asToolResult = (payload) => ({
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+});
+/** Report an API failure as a structured result rather than an MCP exception,
+ *  so the agent can retry on `retryable` instead of treating the step as lost
+ *  and abandoning a decision a human may already be looking at. */
+const asToolError = (err, policy) => isUnknownPolicy(err)
+    ? asToolResult({ error: 'unknown_policy', policy, message: unknownPolicyMessage(policy), retryable: false })
+    : asToolResult({
+        error: err instanceof ApiError && err.status ? `http_${err.status}` : 'unreachable',
+        message: err instanceof Error ? err.message : String(err),
+        retryable: err instanceof ApiError ? err.retryable : true,
+    });
+/** FN-239: one piece of evidence, shared by request_decision and attach_evidence. */
+const evidenceItemSchema = z.object({
+    kind: z
+        .enum(['slack_thread', 'email', 'document', 'link', 'note'])
+        .describe("What this material is. 'slack_thread' / 'email' for a captured conversation, 'document' for a doc or policy excerpt, 'link' for a bare reference with no text, 'note' for your own written rationale."),
+    title: z.string().optional().describe('Short reviewer-facing label, e.g. "#incidents — refund thread".'),
+    source_system: z.string().optional().describe('Where it came from, e.g. "slack", "email", "notion".'),
+    source_url: z.string().optional().describe('Deep link back to the original, for provenance.'),
+    body: z
+        .string()
+        .optional()
+        .describe('The actual text, captured. Send the content, not just a link — a link can be edited or deleted after the decision, and the stored snapshot is what the audit trail keeps. Required unless kind is "link".'),
+    captured_at: z
+        .string()
+        .optional()
+        .describe('ISO timestamp of when the material was originally written, if it predates now.'),
+});
+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,
+    };
+}
+/**
+ * The Ratifia MCP server: the same tools whether it runs over stdio
+ * (`npx @ratifia/mcp`) or hosted at the API's /mcp endpoint (FN-366). Build one
+ * per caller; it holds that caller's token.
+ */
+export function createRatifiaServer(cfg, opts) {
+    const { api, getDecision, attachEvidence, waitForDecision } = createClient(cfg);
+    const APP_URL = trimUrl(cfg.appUrl);
+    // A local harness backgrounds a tool call at ~120s; hosted clients give up
+    // sooner (ChatGPT at ~60s), so a hosted await returns well inside that.
+    const maxWait = opts.hosted ? 55 : 110;
+    const defaultWait = opts.hosted ? 45 : 90;
+    const server = new McpServer({ name: 'ratifia', version: opts.version }, {
+        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.',
+            'Filing: set `workflow` to the project or ongoing effort the decision belongs to (e.g. the repo name, "billing-refunds") so a human can see related decisions together in the dashboard, and reuse the exact same string every time. Put what is specific to this decision (the release, record, environment) in `step`, e.g. "deploy-v2.3-prod". Without them every decision lands in one "ratifia-mcp" bucket.',
+            '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 edit it in the Ratifia app (Slack can only approve or reject it); once approved, use output.content as the final text — it may differ from what you sent.',
+            'Evidence: if your ask rests on material the human should see — a Slack conversation, an email, a policy excerpt — attach it (the `evidence` array on request_decision, or attach_evidence afterwards). Send the text, not just a link: the snapshot is what the audit trail keeps, and a link can change. Evidence can only be attached while the decision is pending; once it resolves the set is sealed, so attach before you await.',
+            'Prefer one well-scoped decision with rich context over many small ones.',
+        ].join('\n'),
+    });
+    server.registerTool('request_decision', {
+        description: '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.',
+        inputSchema: {
+            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. Ignored when a policy decides who answers: the policy's expiry applies."),
+            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 Ratifia app (Slack can only approve or reject it); 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.string(), 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.'),
+            approvers: z
+                .array(z.string().email())
+                .min(1)
+                .max(20)
+                .optional()
+                .describe('Who may answer: one or more email addresses of people in your Ratifia org. Omit to use the default (the signed-in user on a hosted connector, else RATIFIA_APPROVER_EMAIL). Do not combine with `policy`.'),
+            policy: z
+                .string()
+                .max(100)
+                .optional()
+                .describe('Instead of approvers: the key of a Ratifia policy that decides who answers, the quorum and the expiry. It must exist in the org. Do not combine with `approvers`.'),
+            workflow: z
+                .string()
+                .max(100)
+                .optional()
+                .describe('The project or ongoing effort this decision belongs to, e.g. the repo name or "billing-refunds" — the dashboard groups and filters by it, so reuse the exact same string for related decisions and keep ids/versions out of it. Omit to use the server default ("ratifia-mcp" unless configured).'),
+            step: z
+                .string()
+                .max(80)
+                .optional()
+                .describe('What is specific to this decision within the workflow, e.g. "deploy-v2.3-prod" or "refund-INV-1042". Omit to use the title.'),
+            evidence: z
+                .array(evidenceItemSchema)
+                .max(20)
+                .optional()
+                .describe('Material this decision should be made ON — the Slack thread, the email, the policy excerpt you are relying on. Stored immutably against the decision and sealed when it resolves, so the record shows what the human could see. Attach what you already have; use attach_evidence for anything you find afterwards.'),
+        },
+    }, async ({ title, question, context, timeout_minutes, response_type, options, allow_multiple, proposed_output, tool_name, tool_args, approvers, policy, workflow, step, evidence }) => {
+        if (approvers?.length && policy) {
+            return asToolResult({
+                error: 'invalid_request',
+                message: 'Pass approvers or policy, not both: a policy decides who answers.',
+            });
+        }
+        // A call's own choice wins; otherwise the server's defaults.
+        const effectivePolicy = approvers?.length ? undefined : (policy ?? cfg.policy);
+        const whoBody = who(effectivePolicy, approvers ?? cfg.approvers);
+        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);
+        // Minted once per tool invocation and reused as the Idempotency-Key: a
+        // retry of *this* call collapses server-side, while a second, independent
+        // request_decision — even with identical arguments — gets its own id and is
+        // correctly treated as a new ask.
+        const externalRunId = `mcp-${randomUUID()}`;
+        // 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 });
+        }
+        let res;
+        try {
+            res = await apiRetry(() => api('/v1/worker/decisions', {
+                method: 'POST',
+                idempotencyKey: externalRunId,
+                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: label(step, title, 80),
+                    workflowRef: label(workflow, label(cfg.workflow, 'ratifia-mcp', 100), 100),
+                    ...whoBody,
+                    required: true,
+                    // With a policy, the policy sets the expiry (a timeoutSec would be refused).
+                    ...(timeout_minutes && !effectivePolicy ? { 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 } : {}),
+                    },
+                }),
+            }));
+        }
+        catch (err) {
+            return asToolError(err, effectivePolicy);
+        }
+        // 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.',
+            });
+        }
+        // FN-239: evidence is attached after the decision exists — it hangs off the
+        // decision id, so there is nothing to attach to before this point. A failure
+        // here is reported, never thrown: the decision is open and the human has
+        // already been notified, so aborting would strand it and tempt a duplicate
+        // ask. The agent can retry the failed items with attach_evidence.
+        const evidenceErrors = [];
+        let evidenceAttached = 0;
+        for (const item of evidence ?? []) {
+            try {
+                await apiRetry(() => attachEvidence(res.decisionId, item));
+                evidenceAttached++;
+            }
+            catch (err) {
+                evidenceErrors.push(`${item.kind}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return asToolResult({
+            approval_required: true,
+            decision_id: res.decisionId,
+            status: 'pending',
+            url: `${APP_URL}/decisions/${res.decisionId}`,
+            ...(evidence?.length ? { evidence_attached: evidenceAttached } : {}),
+            ...(evidenceErrors.length
+                ? {
+                    evidence_errors: evidenceErrors,
+                    evidence_note: 'The decision was created and the human notified; only these evidence items failed. Retry them with attach_evidence — do NOT request a second decision.',
+                }
+                : {}),
+        });
+    });
+    server.registerTool('attach_evidence', {
+        description: "Attach material a decision should be judged ON — a Slack conversation, an email, a policy excerpt — to a decision you already opened. Use it when you find something relevant after asking, or when the human asks 'what did the customer actually say?'. Evidence is immutable and append-only, and can only be attached while the decision is still pending: once it resolves the set is sealed, so the record shows exactly what the reviewer could see. Send the text itself, not just a link.",
+        inputSchema: {
+            decision_id: z.string().describe('The decision_id returned by request_decision.'),
+            ...evidenceItemSchema.shape,
+        },
+    }, async ({ decision_id, ...item }) => {
+        try {
+            const res = await apiRetry(() => attachEvidence(decision_id, item));
+            return asToolResult({
+                decision_id,
+                evidence_id: res.evidence?.id ?? null,
+                // The API dedupes on content hash, so re-sending the same material is a
+                // no-op rather than a second panel for the reviewer.
+                deduplicated: Boolean(res.deduplicated),
+                status: 'attached',
+            });
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool('check_decision', {
+        description: "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.",
+        inputSchema: {
+            decision_id: z.string().describe('The decision_id returned by request_decision.'),
+        },
+    }, async ({ decision_id }) => {
+        try {
+            return asToolResult(formatDecision(await apiRetry(() => getDecision(decision_id))));
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool('await_decision', {
+        description: "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 (that is normal, not a failure). Transient API errors are retried internally; if one still surfaces it comes back as error + retryable rather than throwing, so call again rather than re-requesting the decision. Use this after request_decision to wait for the verdict.",
+        inputSchema: {
+            decision_id: z.string().describe('The decision_id returned by request_decision.'),
+            max_wait_seconds: z
+                .number()
+                .int()
+                .positive()
+                .max(maxWait)
+                .optional()
+                .describe(`How long to block before returning (default ${defaultWait}, max ${maxWait}). Kept under the point at which your client gives up on a tool call — a longer wait does not reach you sooner, it just lands late. If still pending, call again to keep waiting.`),
+        },
+    }, async ({ decision_id, max_wait_seconds }) => {
+        try {
+            const d = await waitForDecision(decision_id, (max_wait_seconds ?? defaultWait) * 1000);
+            return asToolResult({
+                ...formatDecision(d),
+                ...(d.status === 'PENDING' ? { timed_out: true } : {}),
+            });
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool('list_pending_decisions', {
+        description: '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.',
+        inputSchema: {
+            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));
+        try {
+            const res = await apiRetry(() => api(`/v1/worker/decisions?${qs.toString()}`, { method: 'GET' }));
+            return asToolResult({ count: res.decisions.length, decisions: res.decisions });
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    server.registerTool('cancel_decision', {
+        description: '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).',
+        inputSchema: {
+            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 }) => {
+        // Cancel is naturally idempotent (only PENDING transitions), so a retry is
+        // safe without a key: a second one returns the already-resolved decision.
+        try {
+            return asToolResult(await apiRetry(() => api(`/v1/worker/decisions/${encodeURIComponent(decision_id)}/cancel`, {
+                method: 'POST',
+                body: JSON.stringify(note ? { note } : {}),
+            })));
+        }
+        catch (err) {
+            return asToolError(err);
+        }
+    });
+    return server;
+}
+/**
+ * FN-366: the hosted endpoint. A stateless Streamable HTTP handler that builds a
+ * fresh server per request from the caller's config — the host authenticates
+ * the request, then passes the config (token, default approver) in
+ * `authInfo.extra.ratifia`. A request without one is refused: the handler
+ * never reads credentials itself.
+ */
+export function createRatifiaMcpHandler(opts) {
+    return createMcpHandler((ctx) => {
+        const cfg = ctx.authInfo?.extra?.ratifia;
+        if (!cfg?.token)
+            throw new Error('ratifia-mcp: no caller config on this request');
+        return createRatifiaServer(cfg, { ...opts, hosted: true });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ratifia/mcp",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "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": [
@@ -24,7 +24,7 @@
   "bin": {
     "ratifia-mcp": "dist/index.js"
   },
-  "main": "./dist/index.js",
+  "main": "./dist/server.js",
   "files": [
     "dist"
   ],
@@ -49,5 +49,13 @@
     "@types/node": "^20.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0"
+  },
+  "types": "./dist/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
   }
 }