@quirna/mcp 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+Notable changes to `@quirna/mcp`. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the versions
+[semver](https://semver.org/), with the usual 0.x caveat that a minor bump may
+still move something.
+
+Two surfaces here are public and change under semver like any API: **the tools'
+names and input schemas**, and **the text a tool returns**. The text is read by
+a language model that acts on it, so rewording it is a product change, not
+editing.
+
+Releases are cut with the *MCP* workflow — see
+[ADR-0030](../../docs/adr/0030-servidor-mcp.md).
+
+## [0.1.0] — 2026-09-20
+
+First release.
+
+The mobile app is in **private beta**, and decisions are made there and nowhere
+else. Write to hello@quirna.com and we will add you; until then an approval
+request is created and then waits until it expires.
+
+### Added
+
+- **`request_approval`** — creates an Approval Request and blocks while a
+  nominated human decides on their phone. Takes `kind`, `message`, and
+  optionally `identifiers`, `environment` and `tier`.
+
+  It deliberately does not take who approves, how many are needed, or how long
+  the request stays open. Those live in your organization's Policy, so an agent
+  cannot choose its own approvers and neither can a prompt injection.
+
+- **`check_approval`** — resumes a request that is already open, by id. Agent
+  clients kill long tool calls well before a human finishes deciding; without
+  this, an agent returning from a cut-off call could only create a second
+  request, putting the same action in front of a second person.
+
+- **A declared `outputSchema`** on both tools, so `structuredContent` is a
+  contract a client can type against rather than JSON it may render if it
+  feels like it.
+
+- **`quirna-mcp`**, the executable, configured through `QUIRNA_API_KEY`,
+  `QUIRNA_BASE_URL`, `QUIRNA_REQUESTER_ID`, `QUIRNA_REQUESTER_NAME`,
+  `QUIRNA_ENVIRONMENT` and `QUIRNA_WAIT_MS`.
+
+### The rule worth knowing before you use it
+
+**`isError` means the tool could not run, never that the answer was no.**
+Approved, rejected, timed out, cancelled and still-pending are all successful
+calls, because in all of them we asked and got an answer. `isError` is reserved
+for learning nothing at all: the API unreachable, a key rejected, the call
+aborted.
+
+The verdict is carried by the text instead, and by its order — every
+unauthorized outcome opens with `NOT AUTHORIZED` — plus `authorized` in
+`structuredContent` for code that parses rather than reads.
+
+Marking a denial as an error was tried first and is wrong in a way that looks
+safer than it is: it contradicts `idempotentHint: false` (retrying asks a
+second human), and it collapses "a person said no" and "the service is down"
+into one bit. Nothing other than `approved` reads as permission.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quirna
+
+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

@@ -1,3 +1,146 @@
 # @quirna/mcp
 
-Placeholder. The real package starts at 0.1.0.
+Ask a human before your agent acts. Official [Quirna](https://quirna.com)
+server for the [Model Context Protocol](https://modelcontextprotocol.io).
+
+Add one block of config and your agent gains a tool it can call before doing
+something consequential — a refund, a production deploy, a destructive
+migration. A named human approves it on their phone. The agent proceeds only
+if they said yes, and the decision is signed and kept.
+
+> **Nothing moves until someone says yes.**
+
+Your agent's framework may already have a way to pause for confirmation. This
+is different in three ways that matter once it is not just you at the terminal:
+
+- **The decision leaves the loop.** It goes to whoever your policy nominates,
+  on their phone, behind Face ID — not to whoever happens to be watching the
+  agent run.
+- **Who approves is policy, not prompt.** Quorum, risk tier and which group is
+  asked live in your organization's settings. The agent cannot choose its own
+  approvers, and neither can a prompt injection.
+- **It leaves evidence.** Every decision is signed at the moment it is made,
+  and exports to a file a third party can verify without trusting us.
+
+## Install
+
+Nothing to install: the config below runs it on demand with `npx`. To pin it,
+`npm install -g @quirna/mcp` and use `quirna-mcp` as the command.
+
+## Before you start
+
+> **The mobile app is in private beta.** Decisions are made on the phone and
+> nowhere else — the Console configures policies and never decides one — so
+> without the app an approval request is created and then waits until it
+> expires. Write to **hello@quirna.com** and we will get you in. Everything
+> else below works today.
+
+Then, in the [Console](https://console.quirna.com):
+
+1. **A System key.** Open **Users → Systems** and register one for this agent.
+   You get a key (`ck_…`), shown once.
+2. **A Policy**, which decides who approves a given kind of request and how
+   many of them are needed.
+3. **The app**, on the phone of whoever will approve.
+
+## Configure your agent
+
+**Claude Code** — `claude mcp add quirna --env QUIRNA_API_KEY=ck_… -- npx -y @quirna/mcp`
+
+**Cursor** (`~/.cursor/mcp.json`), **Claude Desktop**
+(`claude_desktop_config.json`) and most other clients take the same shape:
+
+```json
+{
+  "mcpServers": {
+    "quirna": {
+      "command": "npx",
+      "args": ["-y", "@quirna/mcp"],
+      "env": {
+        "QUIRNA_API_KEY": "ck_your_system_key",
+        "QUIRNA_REQUESTER_NAME": "Ops Agent",
+        "QUIRNA_ENVIRONMENT": "production"
+      }
+    }
+  }
+}
+```
+
+### Environment
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `QUIRNA_API_KEY` | — | **Required.** The System key from the Console. |
+| `QUIRNA_REQUESTER_NAME` | `AI agent` | The name an approver sees as having asked. |
+| `QUIRNA_REQUESTER_ID` | `mcp` | Stable id for this caller in the audit trail. |
+| `QUIRNA_ENVIRONMENT` | — | Applied when a call does not name one. |
+| `QUIRNA_WAIT_MS` | `90000` | How long a tool call waits before reporting back. |
+| `QUIRNA_BASE_URL` | `https://api.quirna.com` | Point at a self-hosted API. |
+
+**On the key.** It lives in your agent client's config file, which is often in
+a dotfile and sometimes in a repo. Treat it as a deployment credential: give
+each agent its own System rather than sharing one, scope it in the Console to
+the kinds it may request, and rotate it there if the file gets somewhere it
+should not be. A System key can only *ask* — it can never approve anything.
+
+## The tools
+
+### `request_approval`
+
+Creates the request and waits for a human.
+
+| Argument | Required | |
+| --- | --- | --- |
+| `kind` | yes | The class of action, e.g. `database_migration`. Selects the policy. |
+| `message` | yes | One imperative line, shown as the headline on the phone. |
+| `identifiers` | no | Flat string key/values an approver needs: amounts, table names, hosts. |
+| `environment` | no | `production`, `staging`, … |
+| `tier` | no | `routine`, `elevated`, `critical`. Can only raise the policy's floor. |
+
+Notably absent: who approves, how many are needed, how long it stays open.
+Those are the organization's to decide in the Console, once, for every caller —
+an agent that could pick its own approvers would not be a control.
+
+### `check_approval`
+
+Takes an `approval_id` and waits for that existing request. Use it when
+`request_approval` came back still pending; calling `request_approval` again
+would put the same action in front of a second human.
+
+## What the agent gets back
+
+**Anything that is not `APPROVED` opens with `NOT AUTHORIZED`**, followed by
+why, and by an explicit instruction not to perform the action. The structured
+result carries `authorized: true | false` for code that parses instead of
+reading.
+
+Asking and getting an answer is a successful tool call, whatever the answer
+was — a denial is the product working, not a failure. `isError` is reserved for
+the cases where the tool could not run at all and nothing was learned: Quirna
+unreachable, a key rejected, the call aborted. So an agent can tell "a human
+said no" from "the approval system is down", which are opposite situations, and
+nothing invites it to retry a denial into a second person's hands.
+
+### When nobody answers
+
+An agent running unattended at 3am will hit this: the request expires and the
+action is never authorized. That is the correct outcome, not a bug to design
+around. If your agent needs to run without anyone awake, the answer is a policy
+whose condition does not require a human for that case — not a longer timeout.
+
+Two timeouts are in play, and they are not the same:
+
+- **`QUIRNA_WAIT_MS`** (default 90s) is how long a *tool call* waits before
+  returning the approval id so the agent can resume. It exists because agent
+  clients kill long tool calls. The request stays live.
+- **The policy's expiry** (set in the Console) is how long the *request* stays
+  open. Only this one can time a request out.
+
+## Links
+
+- [quirna.com](https://quirna.com) — what it is
+- [console.quirna.com](https://console.quirna.com) — policies, groups, systems
+- [`@quirna/sdk`](https://www.npmjs.com/package/@quirna/sdk) — for calling
+  Quirna from your own code instead
+
+MIT © Quirna

package/dist/bin.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+// src/bin.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Quirna } from "@quirna/sdk";
+
+// src/config.ts
+var DEFAULT_WAIT_MS = 90000;
+var DEFAULT_REQUESTER_ID = "mcp";
+var DEFAULT_REQUESTER_NAME = "AI agent";
+
+class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+function trimmed(env, name) {
+  const value = env[name]?.trim();
+  return value ? value : undefined;
+}
+function readConfig(env) {
+  const apiKey = trimmed(env, "QUIRNA_API_KEY");
+  if (!apiKey) {
+    throw new ConfigError("QUIRNA_API_KEY is not set. Register a System in the Quirna Console " + "(Users → Systems) and put its key in this server's env block.");
+  }
+  const rawWait = trimmed(env, "QUIRNA_WAIT_MS");
+  let waitMs = DEFAULT_WAIT_MS;
+  if (rawWait !== undefined) {
+    const parsed = Number(rawWait);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      throw new ConfigError(`QUIRNA_WAIT_MS must be a positive number of milliseconds, got ${rawWait}`);
+    }
+    waitMs = parsed;
+  }
+  return {
+    apiKey,
+    baseUrl: trimmed(env, "QUIRNA_BASE_URL"),
+    requesterId: trimmed(env, "QUIRNA_REQUESTER_ID") ?? DEFAULT_REQUESTER_ID,
+    requesterName: trimmed(env, "QUIRNA_REQUESTER_NAME") ?? DEFAULT_REQUESTER_NAME,
+    environment: trimmed(env, "QUIRNA_ENVIRONMENT"),
+    waitMs
+  };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  QuirnaError,
+  TIERS as TIERS2
+} from "@quirna/sdk";
+import { z as z2 } from "zod";
+
+// src/outcome.ts
+import {
+  APPROVAL_STATUSES,
+  TIERS
+} from "@quirna/sdk";
+import { z } from "zod";
+var OUTPUT_SCHEMA = {
+  approval_id: z.string().describe("The Quirna id for this request."),
+  status: z.enum([...APPROVAL_STATUSES]),
+  authorized: z.boolean().describe("True only when the action may proceed. The one field worth branching on."),
+  kind: z.string(),
+  message: z.string(),
+  tier: z.enum([...TIERS]),
+  environment: z.string().nullable(),
+  auto_approved: z.boolean().describe("True when a Policy condition did not match and no human was asked."),
+  decided_by: z.string().nullable().describe("User id of the decider, not a name (ZUR-68)."),
+  decided_at: z.string().nullable(),
+  approved_count: z.number(),
+  policy: z.string().describe("Name of the Policy that governed this request."),
+  timeout_at: z.string().describe("When the request expires if still undecided.")
+};
+function structured(approval, authorized) {
+  return {
+    approval_id: approval.id,
+    status: approval.status,
+    authorized,
+    kind: approval.kind,
+    message: approval.message,
+    tier: approval.tier,
+    environment: approval.environment,
+    auto_approved: approval.auto_approved ?? false,
+    decided_by: approval.decided_by,
+    decided_at: approval.decided_at,
+    approved_count: approval.approved_count,
+    policy: approval.policy.name,
+    timeout_at: approval.timeout_at
+  };
+}
+function result(approval, authorized, text) {
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: structured(approval, authorized),
+    isError: false
+  };
+}
+var DO_NOT_PROCEED = "Do NOT perform the action. Report this outcome to the user instead of working around it.";
+function describe(approval) {
+  switch (approval.status) {
+    case "approved": {
+      if (approval.auto_approved) {
+        return result(approval, true, `APPROVED automatically (${approval.id}). The "${approval.policy.name}" policy's ` + "condition did not match this request, so no human was asked. You may proceed.");
+      }
+      const when = approval.decided_at ? ` at ${approval.decided_at}` : "";
+      return result(approval, true, `APPROVED (${approval.id}). Authorized by an approver${when} under the ` + `"${approval.policy.name}" policy. You may proceed with: ${approval.message}`);
+    }
+    case "rejected":
+      return result(approval, false, `NOT AUTHORIZED — REJECTED (${approval.id}). A human explicitly denied this. ` + DO_NOT_PROCEED);
+    case "timed_out":
+      return result(approval, false, `NOT AUTHORIZED — TIMED OUT (${approval.id}). Nobody decided before the request ` + `expired at ${approval.timeout_at}. ${DO_NOT_PROCEED}`);
+    case "cancelled":
+      return result(approval, false, `NOT AUTHORIZED — CANCELLED (${approval.id}). The request was withdrawn before ` + `anyone decided it. ${DO_NOT_PROCEED}`);
+    case "pending":
+      return result(approval, false, `NOT AUTHORIZED YET — STILL PENDING (${approval.id}). The request is live and ` + `waiting on a human; it expires at ${approval.timeout_at}. ${DO_NOT_PROCEED} ` + `To pick the answer back up, call check_approval with approval_id "${approval.id}" — ` + "never request_approval again, which would ask a second person to approve the same thing.");
+  }
+}
+
+// src/server.ts
+var TIER_VALUES = [...TIERS2];
+var SERVER_NAME = "quirna";
+var SERVER_VERSION = "0.1.0";
+var REQUEST_DESCRIPTION = [
+  "Ask a human to authorize an action before you take it, and wait for their answer.",
+  "",
+  "Call this BEFORE doing anything that is irreversible, destructive, spends money,",
+  "touches production, affects other people, or goes beyond what the user explicitly",
+  "asked for. Describe the action you are about to take, then act only if the result",
+  "says APPROVED.",
+  "",
+  "A nominated approver decides on their phone under your organization's policy — you",
+  "do not choose who approves or how many are needed. The call blocks while they",
+  "decide. If they have not answered by the time it returns, you get the approval id",
+  "and resume with check_approval; the request stays live either way."
+].join(`
+`);
+var CHECK_DESCRIPTION = [
+  "Look up an approval request you already created and wait for its outcome.",
+  "",
+  "Use this when a previous request_approval call came back NOT DECIDED YET. Never",
+  "call request_approval again for the same action — that asks a second human to",
+  "approve something already in front of the first one."
+].join(`
+`);
+function createServer(config, client) {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+    instructions: "Quirna puts a human in front of risky actions. Before taking an action that " + "is irreversible, destructive, costly, or outside what the user asked for, call " + "request_approval and proceed only on APPROVED."
+  });
+  server.registerTool("request_approval", {
+    title: "Request human approval",
+    description: REQUEST_DESCRIPTION,
+    inputSchema: {
+      kind: z2.string().min(1).describe('What class of action this is, in snake_case — for example "database_migration", ' + `"refund", "deploy". The organization's policy for this kind decides who is ` + "asked and whether a human is needed at all."),
+      message: z2.string().min(1).describe("One imperative line naming the action, shown as the headline on the approver's " + 'phone: "Drop table users_v1 on production". Write it so someone who cannot see ' + "your session can judge it."),
+      identifiers: z2.record(z2.string(), z2.string()).optional().describe("The specifics an approver needs, as flat string key/value pairs: amounts, table " + 'names, account ids, hostnames. For example {"table": "users_v1", "rows": "48213"}. ' + "Policy conditions are evaluated against these."),
+      environment: z2.string().optional().describe('Deployment label, for example "production" or "staging".'),
+      tier: z2.enum(TIER_VALUES).optional().describe("Raise the risk tier shown to the approver. The policy sets the floor; this can " + "only raise it, never lower it.")
+    },
+    outputSchema: OUTPUT_SCHEMA,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  }, async (args, extra) => {
+    const input = {
+      kind: args.kind,
+      message: args.message,
+      identifiers: args.identifiers ?? {},
+      requester_id: config.requesterId,
+      requester_name: config.requesterName,
+      ...args.environment ?? config.environment ? { environment: args.environment ?? config.environment } : {},
+      ...args.tier ? { tier: args.tier } : {}
+    };
+    return run(async () => {
+      const created = await client.create(input, { signal: extra.signal });
+      if (created.status !== "pending")
+        return describe(created);
+      return describe(await settle(client, created.id, config.waitMs, extra.signal));
+    });
+  });
+  server.registerTool("check_approval", {
+    title: "Check a pending approval",
+    description: CHECK_DESCRIPTION,
+    inputSchema: {
+      approval_id: z2.string().min(1).describe('The id from an earlier request_approval result, such as "apr_7x2k9m".')
+    },
+    outputSchema: OUTPUT_SCHEMA,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  }, async (args, extra) => run(async () => describe(await settle(client, args.approval_id, config.waitMs, extra.signal))));
+  return server;
+}
+async function settle(client, id, waitMs, signal) {
+  try {
+    return await client.wait(id, { timeoutMs: waitMs, signal });
+  } catch (err) {
+    if (err instanceof QuirnaError && err.code === "wait_timeout") {
+      return client.get(id, { signal });
+    }
+    throw err;
+  }
+}
+async function run(body) {
+  try {
+    return await body();
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: failureText(err) }],
+      structuredContent: {},
+      isError: true
+    };
+  }
+}
+function failureText(err) {
+  const prefix = "NOT AUTHORIZED —";
+  const suffix = "Do NOT perform the action; tell the user Quirna could not answer.";
+  if (err instanceof QuirnaError) {
+    if (err.code === "aborted") {
+      return `${prefix} the approval request was cancelled before it was decided. ${suffix}`;
+    }
+    const hint = err.status === 401 ? " Check QUIRNA_API_KEY: the System key was rejected." : err.status === 403 ? " This System is not allowed to request that kind; an Org admin sets the list in the Console under Users → Systems." : "";
+    return `${prefix} Quirna returned ${err.status}: ${err.message}.${hint} ${suffix}`;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return `${prefix} could not reach Quirna: ${message}. ${suffix}`;
+}
+
+// src/bin.ts
+async function main() {
+  const config = readConfig(process.env);
+  const client = new Quirna({
+    apiKey: config.apiKey,
+    ...config.baseUrl ? { baseUrl: config.baseUrl } : {},
+    timeoutMs: 30000
+  });
+  const server = createServer(config, client);
+  await server.connect(new StdioServerTransport);
+  process.stderr.write(`quirna-mcp: ready (waiting up to ${Math.round(config.waitMs / 1000)}s per approval)
+`);
+}
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(err instanceof ConfigError ? `quirna-mcp: ${message}
+` : `quirna-mcp: failed to start: ${message}
+`);
+  process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Every environment variable this server reads, in one place.
+ *
+ * An MCP server is configured by a block of JSON in someone else's agent
+ * client, so env vars are the whole configuration surface — there is no
+ * flag to pass and no file of ours to edit. Each one below is therefore
+ * documented as if it were a public API, because it is.
+ */
+export type ServerConfig = {
+    apiKey: string;
+    baseUrl?: string;
+    /** Who the Console shows as having asked. One System key per agent, ideally. */
+    requesterId: string;
+    requesterName: string;
+    /** Applied when a tool call does not name one. Empty means the org default. */
+    environment?: string;
+    /**
+     * How long a tool call blocks waiting for a human before reporting back
+     * that the request is still pending.
+     *
+     * Deliberately short by default. The limit that matters is not ours — it
+     * is the agent client's own tool-call timeout, which is measured in tens
+     * of seconds and, when it fires, kills the call without telling the model
+     * anything. Coming back first with an approval id the model can resume
+     * from is strictly better than being killed holding it.
+     */
+    waitMs: number;
+};
+export declare const DEFAULT_WAIT_MS = 90000;
+export declare const DEFAULT_REQUESTER_ID = "mcp";
+export declare const DEFAULT_REQUESTER_NAME = "AI agent";
+/** Thrown for a configuration problem, which is always the operator's to fix. */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export type Env = Record<string, string | undefined>;
+/**
+ * Read the configuration, or throw a `ConfigError` naming the variable and
+ * where to get its value.
+ *
+ * The error text matters more here than anywhere else in the package: it is
+ * printed to stderr by an agent client that shows the user, at best, a red
+ * line saying the server failed to start.
+ */
+export declare function readConfig(env: Env): ServerConfig;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The library surface, for embedding the Quirna tools in a server of your
+ * own. Running it as a standalone MCP server needs none of this — that is
+ * `bin.ts`, published as the `quirna-mcp` executable.
+ */
+export { ConfigError, DEFAULT_REQUESTER_ID, DEFAULT_REQUESTER_NAME, DEFAULT_WAIT_MS, type Env, readConfig, type ServerConfig, } from "./config.js";
+export { describe, type ToolResult } from "./outcome.js";
+export { type ApprovalsClient, createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";

package/dist/index.js

@@ -0,0 +1,234 @@
+// src/config.ts
+var DEFAULT_WAIT_MS = 90000;
+var DEFAULT_REQUESTER_ID = "mcp";
+var DEFAULT_REQUESTER_NAME = "AI agent";
+
+class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+function trimmed(env, name) {
+  const value = env[name]?.trim();
+  return value ? value : undefined;
+}
+function readConfig(env) {
+  const apiKey = trimmed(env, "QUIRNA_API_KEY");
+  if (!apiKey) {
+    throw new ConfigError("QUIRNA_API_KEY is not set. Register a System in the Quirna Console " + "(Users → Systems) and put its key in this server's env block.");
+  }
+  const rawWait = trimmed(env, "QUIRNA_WAIT_MS");
+  let waitMs = DEFAULT_WAIT_MS;
+  if (rawWait !== undefined) {
+    const parsed = Number(rawWait);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      throw new ConfigError(`QUIRNA_WAIT_MS must be a positive number of milliseconds, got ${rawWait}`);
+    }
+    waitMs = parsed;
+  }
+  return {
+    apiKey,
+    baseUrl: trimmed(env, "QUIRNA_BASE_URL"),
+    requesterId: trimmed(env, "QUIRNA_REQUESTER_ID") ?? DEFAULT_REQUESTER_ID,
+    requesterName: trimmed(env, "QUIRNA_REQUESTER_NAME") ?? DEFAULT_REQUESTER_NAME,
+    environment: trimmed(env, "QUIRNA_ENVIRONMENT"),
+    waitMs
+  };
+}
+// src/outcome.ts
+import {
+  APPROVAL_STATUSES,
+  TIERS
+} from "@quirna/sdk";
+import { z } from "zod";
+var OUTPUT_SCHEMA = {
+  approval_id: z.string().describe("The Quirna id for this request."),
+  status: z.enum([...APPROVAL_STATUSES]),
+  authorized: z.boolean().describe("True only when the action may proceed. The one field worth branching on."),
+  kind: z.string(),
+  message: z.string(),
+  tier: z.enum([...TIERS]),
+  environment: z.string().nullable(),
+  auto_approved: z.boolean().describe("True when a Policy condition did not match and no human was asked."),
+  decided_by: z.string().nullable().describe("User id of the decider, not a name (ZUR-68)."),
+  decided_at: z.string().nullable(),
+  approved_count: z.number(),
+  policy: z.string().describe("Name of the Policy that governed this request."),
+  timeout_at: z.string().describe("When the request expires if still undecided.")
+};
+function structured(approval, authorized) {
+  return {
+    approval_id: approval.id,
+    status: approval.status,
+    authorized,
+    kind: approval.kind,
+    message: approval.message,
+    tier: approval.tier,
+    environment: approval.environment,
+    auto_approved: approval.auto_approved ?? false,
+    decided_by: approval.decided_by,
+    decided_at: approval.decided_at,
+    approved_count: approval.approved_count,
+    policy: approval.policy.name,
+    timeout_at: approval.timeout_at
+  };
+}
+function result(approval, authorized, text) {
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: structured(approval, authorized),
+    isError: false
+  };
+}
+var DO_NOT_PROCEED = "Do NOT perform the action. Report this outcome to the user instead of working around it.";
+function describe(approval) {
+  switch (approval.status) {
+    case "approved": {
+      if (approval.auto_approved) {
+        return result(approval, true, `APPROVED automatically (${approval.id}). The "${approval.policy.name}" policy's ` + "condition did not match this request, so no human was asked. You may proceed.");
+      }
+      const when = approval.decided_at ? ` at ${approval.decided_at}` : "";
+      return result(approval, true, `APPROVED (${approval.id}). Authorized by an approver${when} under the ` + `"${approval.policy.name}" policy. You may proceed with: ${approval.message}`);
+    }
+    case "rejected":
+      return result(approval, false, `NOT AUTHORIZED — REJECTED (${approval.id}). A human explicitly denied this. ` + DO_NOT_PROCEED);
+    case "timed_out":
+      return result(approval, false, `NOT AUTHORIZED — TIMED OUT (${approval.id}). Nobody decided before the request ` + `expired at ${approval.timeout_at}. ${DO_NOT_PROCEED}`);
+    case "cancelled":
+      return result(approval, false, `NOT AUTHORIZED — CANCELLED (${approval.id}). The request was withdrawn before ` + `anyone decided it. ${DO_NOT_PROCEED}`);
+    case "pending":
+      return result(approval, false, `NOT AUTHORIZED YET — STILL PENDING (${approval.id}). The request is live and ` + `waiting on a human; it expires at ${approval.timeout_at}. ${DO_NOT_PROCEED} ` + `To pick the answer back up, call check_approval with approval_id "${approval.id}" — ` + "never request_approval again, which would ask a second person to approve the same thing.");
+  }
+}
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  QuirnaError,
+  TIERS as TIERS2
+} from "@quirna/sdk";
+import { z as z2 } from "zod";
+var TIER_VALUES = [...TIERS2];
+var SERVER_NAME = "quirna";
+var SERVER_VERSION = "0.1.0";
+var REQUEST_DESCRIPTION = [
+  "Ask a human to authorize an action before you take it, and wait for their answer.",
+  "",
+  "Call this BEFORE doing anything that is irreversible, destructive, spends money,",
+  "touches production, affects other people, or goes beyond what the user explicitly",
+  "asked for. Describe the action you are about to take, then act only if the result",
+  "says APPROVED.",
+  "",
+  "A nominated approver decides on their phone under your organization's policy — you",
+  "do not choose who approves or how many are needed. The call blocks while they",
+  "decide. If they have not answered by the time it returns, you get the approval id",
+  "and resume with check_approval; the request stays live either way."
+].join(`
+`);
+var CHECK_DESCRIPTION = [
+  "Look up an approval request you already created and wait for its outcome.",
+  "",
+  "Use this when a previous request_approval call came back NOT DECIDED YET. Never",
+  "call request_approval again for the same action — that asks a second human to",
+  "approve something already in front of the first one."
+].join(`
+`);
+function createServer(config, client) {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+    instructions: "Quirna puts a human in front of risky actions. Before taking an action that " + "is irreversible, destructive, costly, or outside what the user asked for, call " + "request_approval and proceed only on APPROVED."
+  });
+  server.registerTool("request_approval", {
+    title: "Request human approval",
+    description: REQUEST_DESCRIPTION,
+    inputSchema: {
+      kind: z2.string().min(1).describe('What class of action this is, in snake_case — for example "database_migration", ' + `"refund", "deploy". The organization's policy for this kind decides who is ` + "asked and whether a human is needed at all."),
+      message: z2.string().min(1).describe("One imperative line naming the action, shown as the headline on the approver's " + 'phone: "Drop table users_v1 on production". Write it so someone who cannot see ' + "your session can judge it."),
+      identifiers: z2.record(z2.string(), z2.string()).optional().describe("The specifics an approver needs, as flat string key/value pairs: amounts, table " + 'names, account ids, hostnames. For example {"table": "users_v1", "rows": "48213"}. ' + "Policy conditions are evaluated against these."),
+      environment: z2.string().optional().describe('Deployment label, for example "production" or "staging".'),
+      tier: z2.enum(TIER_VALUES).optional().describe("Raise the risk tier shown to the approver. The policy sets the floor; this can " + "only raise it, never lower it.")
+    },
+    outputSchema: OUTPUT_SCHEMA,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  }, async (args, extra) => {
+    const input = {
+      kind: args.kind,
+      message: args.message,
+      identifiers: args.identifiers ?? {},
+      requester_id: config.requesterId,
+      requester_name: config.requesterName,
+      ...args.environment ?? config.environment ? { environment: args.environment ?? config.environment } : {},
+      ...args.tier ? { tier: args.tier } : {}
+    };
+    return run(async () => {
+      const created = await client.create(input, { signal: extra.signal });
+      if (created.status !== "pending")
+        return describe(created);
+      return describe(await settle(client, created.id, config.waitMs, extra.signal));
+    });
+  });
+  server.registerTool("check_approval", {
+    title: "Check a pending approval",
+    description: CHECK_DESCRIPTION,
+    inputSchema: {
+      approval_id: z2.string().min(1).describe('The id from an earlier request_approval result, such as "apr_7x2k9m".')
+    },
+    outputSchema: OUTPUT_SCHEMA,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  }, async (args, extra) => run(async () => describe(await settle(client, args.approval_id, config.waitMs, extra.signal))));
+  return server;
+}
+async function settle(client, id, waitMs, signal) {
+  try {
+    return await client.wait(id, { timeoutMs: waitMs, signal });
+  } catch (err) {
+    if (err instanceof QuirnaError && err.code === "wait_timeout") {
+      return client.get(id, { signal });
+    }
+    throw err;
+  }
+}
+async function run(body) {
+  try {
+    return await body();
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: failureText(err) }],
+      structuredContent: {},
+      isError: true
+    };
+  }
+}
+function failureText(err) {
+  const prefix = "NOT AUTHORIZED —";
+  const suffix = "Do NOT perform the action; tell the user Quirna could not answer.";
+  if (err instanceof QuirnaError) {
+    if (err.code === "aborted") {
+      return `${prefix} the approval request was cancelled before it was decided. ${suffix}`;
+    }
+    const hint = err.status === 401 ? " Check QUIRNA_API_KEY: the System key was rejected." : err.status === 403 ? " This System is not allowed to request that kind; an Org admin sets the list in the Console under Users → Systems." : "";
+    return `${prefix} Quirna returned ${err.status}: ${err.message}.${hint} ${suffix}`;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return `${prefix} could not reach Quirna: ${message}. ${suffix}`;
+}
+export {
+  ConfigError,
+  DEFAULT_REQUESTER_ID,
+  DEFAULT_REQUESTER_NAME,
+  DEFAULT_WAIT_MS,
+  SERVER_NAME,
+  SERVER_VERSION,
+  createServer,
+  describe,
+  readConfig
+};

package/dist/outcome.d.ts

@@ -0,0 +1,95 @@
+import { type Approval } from "@quirna/sdk";
+import { z } from "zod";
+/**
+ * Turning an Approval into what the model reads.
+ *
+ * This module is the safety surface of the package. Everything else moves
+ * bytes; this decides what an agent believes it is allowed to do next, and
+ * the only reader is a language model that will act on the text.
+ *
+ * One rule governs all of it: **`isError` means the tool could not run, never
+ * that the answer was no.** Every outcome described here — approved, rejected,
+ * timed out, cancelled, still pending — is a successful call, because in all
+ * of them we asked and got an answer. Only `server.ts`'s catch sets
+ * `isError: true`, for the cases where we never learned anything: the API
+ * unreachable, a key rejected, the call aborted.
+ *
+ * Marking a rejection as an error was tried and is wrong in a way worth
+ * recording, because it looks safer than it is:
+ *
+ *  - It contradicts `idempotentHint: false` on `request_approval`. That flag
+ *    exists because retrying the call asks a *second* human to approve the
+ *    same action — and `isError` is exactly the signal that makes an agent
+ *    retry. The two together tell a client to do the one thing the tool must
+ *    never do.
+ *  - It collapses "Ana said no" and "the API is down" into one bit. Those are
+ *    opposites — an authoritative answer versus knowing nothing — and the
+ *    agent would have to read the text to tell them apart, which was the whole
+ *    justification for not trusting the text.
+ *
+ * What does the work instead is the text, and its order: a model reads the
+ * front of a tool result most reliably, so every unauthorized outcome opens
+ * with `NOT AUTHORIZED` before anything else. Fail-closed is unchanged — no
+ * path other than `approved` reads as permission — and `structuredContent`
+ * carries `authorized` for anything parsing rather than reading.
+ */
+export type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+    isError: boolean;
+};
+/**
+ * The declared shape of `structuredContent`, shared by both tools.
+ *
+ * Declaring it is what turns the JSON half from something a client may render
+ * if it feels like it into a contract it can type against — worth having for a
+ * package whose job is to live inside someone else's client.
+ *
+ * It comes with a sharp edge: when a tool declares an output schema, the MCP
+ * SDK validates the result on **every call** and throws `McpError` if the
+ * shape does not match. A drift between this and `structured()` would turn an
+ * approval a human already answered into a protocol error the model reads as
+ * an opaque failure — the one outcome this package must never produce.
+ *
+ * So the drift is made impossible rather than merely tested for: `structured()`
+ * is typed as `z.infer` of this schema, which makes a mismatch a compile error
+ * instead of a runtime one. A test over every status covers what types cannot,
+ * namely that the values really satisfy it. (The error path is safe either
+ * way — the SDK skips validation when `isError` is set.)
+ */
+export declare const OUTPUT_SCHEMA: {
+    approval_id: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        approved: "approved";
+        rejected: "rejected";
+        timed_out: "timed_out";
+        cancelled: "cancelled";
+    }>;
+    authorized: z.ZodBoolean;
+    kind: z.ZodString;
+    message: z.ZodString;
+    tier: z.ZodEnum<{
+        routine: "routine";
+        elevated: "elevated";
+        critical: "critical";
+    }>;
+    environment: z.ZodNullable<z.ZodString>;
+    auto_approved: z.ZodBoolean;
+    decided_by: z.ZodNullable<z.ZodString>;
+    decided_at: z.ZodNullable<z.ZodString>;
+    approved_count: z.ZodNumber;
+    policy: z.ZodString;
+    timeout_at: z.ZodString;
+};
+/**
+ * The outcome of a settled — or still-pending — Approval Request.
+ *
+ * `pending` reaches here only because *we* stopped waiting, never because the
+ * request is over: the human can still decide on their phone, and the id in
+ * the text is how the agent picks the answer back up.
+ */
+export declare function describe(approval: Approval): ToolResult;

package/dist/server.d.ts

@@ -0,0 +1,36 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Approval, type CreateApprovalInput } from "@quirna/sdk";
+import type { ServerConfig } from "./config.js";
+/**
+ * The two tools, and nothing else.
+ *
+ * ZUR-56 asked for a single tool — create the request and wait — on the
+ * grounds that the Kind and the Condition already live in the org's Policy,
+ * so there is nothing to configure per agent. That reasoning holds and is why
+ * neither tool takes a quorum, an approver or a timeout: the org decides those
+ * in the Console, once, for every caller.
+ *
+ * `check_approval` is the one addition, and it exists because of the case the
+ * ticket left open: an agent client kills a tool call long before a human
+ * finishes deciding. Without a way to name an existing request, an agent that
+ * came back from a cut-off call could only call `request_approval` again —
+ * asking a second human to approve the same action, which is worse than any
+ * amount of API surface.
+ */
+/** The slice of `@quirna/sdk`'s client this server uses. Narrow so tests can fake it. */
+export type ApprovalsClient = {
+    create(input: CreateApprovalInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<Approval>;
+    get(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Approval>;
+    wait(id: string, options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+        signal?: AbortSignal;
+    }): Promise<Approval>;
+};
+export declare const SERVER_NAME = "quirna";
+export declare const SERVER_VERSION = "0.1.0";
+export declare function createServer(config: ServerConfig, client: ApprovalsClient): McpServer;

package/package.json

@@ -1,7 +1,59 @@
 {
   "name": "@quirna/mcp",
-  "version": "0.0.0",
-  "description": "Placeholder so the package exists and a trusted publisher can be configured. See 0.1.0 and later.",
+  "version": "0.1.0",
+  "description": "Ask a human before your agent acts. Quirna's Model Context Protocol server.",
   "license": "MIT",
-  "private": false
+  "homepage": "https://quirna.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quirna/quirna-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "approval",
+    "human-in-the-loop",
+    "agent-authorization",
+    "quirna"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "quirna-mcp": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "prebuild": "if [ -d ../sdk ]; then cd ../sdk && bun run build; fi",
+    "build": "rm -rf dist && bun build ./src/bin.ts ./src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@quirna/sdk": "^0.1.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bugs": {
+    "url": "https://github.com/quirna/quirna-mcp/issues"
+  }
 }