@ratifia/mcp 0.8.0 → 0.9.0

package/README.md

@@ -58,9 +58,26 @@ real decisions. CI runs it on every push.
 | `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 deciding **who** reviews and the quorum they need. It must exist in your org: an unknown name is a tool error, and the `gate` hook denies. |
+| `RATIFIA_POLICY` | | — | The **key** of a policy deciding **who** reviews and the quorum they need. It must exist in your org: an unknown key is a tool error, and the `gate` hook denies. |
+| `RATIFIA_WORKFLOW` | | `ratifia-mcp` (`ratifia-gate` for the hook) | The **workflow** decisions are filed under — the category the dashboard's Workflow filter groups by, e.g. `deploys` or `billing-agent`. A `request_decision` call can override it. |
 
-Routing (email / SMS / escalation) is decided **inside Ratifia** by your org's policy — this server is a thin request/verdict bridge.
+Who is notified is decided **inside Ratifia** by your org's policy — this server is a thin request/verdict bridge.
+
+### Filing decisions: workflow and step
+
+Every decision carries two labels:
+
+- **Workflow** (`workflowRef`) — the *category*: "deploys", "refunds". The dashboard's Workflow filter groups by it. Set a default per server with `RATIFIA_WORKFLOW`, or pass `workflow` to `request_decision`.
+- **Step** (`stepRef`) — the *specific instance* inside it: "api-v2.3-to-prod", "refund-INV-1042". Pass `step` to `request_decision`; it defaults to the title.
+
+```
+request_decision(
+  title: "Deploy API to prod?",
+  question: "Ship v2.3 to production?",
+  workflow: "deploys",
+  step: "api-v2.3-to-prod"
+)
+```
 
 ## Tools
 

package/dist/index.js

@@ -25,8 +25,11 @@
  *   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 deciding who reviews (must exist in the org)
+ *   RATIFIA_POLICY          optional: policy key deciding who reviews (must exist in the org)
  *                           (e.g. a route to your phone)
+ *   RATIFIA_WORKFLOW        optional: the workflow (category) decisions are filed under —
+ *                           what the dashboard's Workflow filter groups by. Defaults to
+ *                           `ratifia-mcp` (tools) / `ratifia-gate` (the gate hook).
  */
 import { McpServer } from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
@@ -37,6 +40,17 @@ 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;
+const WORKFLOW = process.env.RATIFIA_WORKFLOW;
+/**
+ * Where a decision is filed. `workflowRef` is the category (the dashboard's
+ * Workflow filter groups by it — e.g. "deploys", "billing-agent");
+ * `stepRef` is the specific instance within it. Blank or whitespace-only values
+ * fall back rather than filing under an empty name.
+ */
+function label(value, fallback, max) {
+    const v = value?.trim();
+    return (v ? v : fallback).slice(0, max);
+}
 if (!API_KEY) {
     console.error('RATIFIA_API_KEY is required');
     process.exit(1);
@@ -75,7 +89,7 @@ function errorCode(body) {
 }
 /** FN-255: RATIFIA_POLICY names a policy the org doesn't have. A misconfiguration, not an outage. */
 const isUnknownPolicy = (err) => err instanceof ApiError && err.code === 'unknown_policy';
-const unknownPolicyMessage = () => `RATIFIA_POLICY "${POLICY}" does not exist in this Ratifia org. Create the policy in the Ratifia dashboard (Policies) or fix RATIFIA_POLICY in this MCP server's config. No decision was created: do not proceed with the action.`;
+const unknownPolicyMessage = () => `RATIFIA_POLICY "${POLICY}" is not a policy key in this Ratifia org. Create a policy with this key in the Ratifia dashboard (Policies) or fix RATIFIA_POLICY in this MCP server's config. No decision was created: do not proceed with the action.`;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** `idempotencyKey` makes a retried write safe to collapse server-side; mint it
  *  once per tool invocation so two independent asks never share one. */
@@ -289,7 +303,7 @@ async function runGate() {
                 engine: 'mcp',
                 externalRunId,
                 stepRef: `tool:${toolName}`.slice(0, 80),
-                workflowRef: 'ratifia-gate',
+                workflowRef: label(WORKFLOW, 'ratifia-gate', 100),
                 ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
                 ...(POLICY ? { policy: POLICY } : {}),
                 required: true,
@@ -343,6 +357,7 @@ const server = new McpServer({ name: 'ratifia', version: '0.7.0' }, {
         '',
         '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.',
@@ -397,13 +412,23 @@ server.registerTool('request_decision', {
             .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.'),
+        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_WORKFLOW, else "ratifia-mcp").'),
+        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, evidence }) => {
+}, async ({ title, question, context, timeout_minutes, response_type, options, allow_multiple, proposed_output, tool_name, tool_args, workflow, step, evidence }) => {
     if (response_type === 'select' && (!options || options.length < 2)) {
         return asToolResult({
             error: 'invalid_request',
@@ -435,8 +460,8 @@ server.registerTool('request_decision', {
                 // verdict rather than parking on an engine resume event.
                 engine: 'mcp',
                 externalRunId,
-                stepRef: title.slice(0, 80),
-                workflowRef: 'ratifia-mcp',
+                stepRef: label(step, title, 80),
+                workflowRef: label(workflow, label(WORKFLOW, 'ratifia-mcp', 100), 100),
                 ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
                 ...(POLICY ? { policy: POLICY } : {}),
                 required: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ratifia/mcp",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Ratifia MCP server \u2014 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": [