ratchet-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Full text: https://www.apache.org/licenses/LICENSE-2.0.txt

package/README.md

@@ -0,0 +1,71 @@
+# ratchet-mcp
+
+MCP server for [Ratchet](https://ratchetgate.com) — an effect gate for AI agents.
+
+Agents retry. LLM control flow is non-deterministic, network calls fail ambiguously, and processes
+die mid-action, so the same logical action gets attempted zero, one, or several times and nothing
+knows which. Ratchet is a gate you ask **before** acting, and it answers durably.
+
+## Setup
+
+Get a key at <https://ratchetgate.com/console> (free, no card), then:
+
+```json
+{
+  "mcpServers": {
+    "ratchet": {
+      "command": "npx",
+      "args": ["-y", "ratchet-mcp"],
+      "env": { "RATCHET_API_KEY": "rk_live_..." }
+    }
+  }
+}
+```
+
+Put the key in `env`, never in `args` — arguments are visible in process listings.
+
+Works with Claude Desktop, Claude Code, Cursor, and any MCP client that spawns a stdio server.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `ratchet_begin_effect` | Ask permission before a side effect. Returns `execute`, `duplicate`, `in_flight`, `blocked`, `approval_required`, or `denied` |
+| `ratchet_report_effect` | Report the outcome after acting |
+| `ratchet_check_effect` | Ask "did I already do this?" without reserving anything |
+| `ratchet_resolve_effect` | Settle an effect whose outcome was unknown, after verifying |
+| `ratchet_list_effects` | Review recent effects; filter by `indeterminate` to find unresolved work |
+| `ratchet_get_policy` | Read the retry and budget policy for an effect type |
+| `ratchet_usage` | Plan, allowance, credit balance, and today's spend |
+
+Only `execute` authorises the model to act. Every other decision returns a `next_step` beginning
+with `STOP`.
+
+## The part that matters
+
+If your agent dies between "go" and "done", Ratchet does **not** quietly let the next caller retry.
+The lease expires, the effect becomes `indeterminate` — a known unknown — and your configured
+policy for that effect type decides what happens: block (the default), retry, or verify first.
+
+Exactly-once delivery is not achievable and is not claimed. What is guaranteed is at-most-once
+initiation, a recorded outcome that later callers replay, and an explicit state for the case most
+systems bury.
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `RATCHET_API_KEY` | *(required)* | Your scoped API key |
+| `RATCHET_BASE_URL` | `https://ratchetgate.com` | Point at your own instance |
+| `RATCHET_TIMEOUT_MS` | `15000` | Request timeout |
+
+This package holds no database connection and no server secret — only your key, which is scoped
+and revocable. It is a thin bridge to the HTTP API, with zero dependencies.
+
+If the gate is unreachable it returns a JSON-RPC error rather than crashing, so your agent can
+apply its fail-open or fail-closed policy. Decide which **before** integrating:
+<https://ratchetgate.com/docs>
+
+## License
+
+Apache-2.0

package/bin/ratchet-mcp.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Ratchet MCP server (stdio transport).
+ *
+ * A thin bridge: it reads line-delimited JSON-RPC on stdin, forwards each
+ * message to a Ratchet instance's /mcp endpoint over HTTPS, and writes the
+ * reply to stdout.
+ *
+ * Deliberately holds no database connection and no server secret. The only
+ * credential is the caller's own API key, which is scoped and revocable. An
+ * MCP server that required its users to hold the service's database
+ * credentials would be a much larger thing to trust than the service itself.
+ *
+ * Zero dependencies — Node built-ins only.
+ *
+ *   RATCHET_API_KEY=rk_live_... npx ratchet-mcp
+ */
+import { createInterface } from 'node:readline';
+
+const BASE = (process.env.RATCHET_BASE_URL ?? 'https://ratchetgate.com').replace(/\/+$/, '');
+const KEY = process.env.RATCHET_API_KEY;
+const TIMEOUT_MS = Number.parseInt(process.env.RATCHET_TIMEOUT_MS ?? '15000', 10);
+
+// stdout carries the protocol and nothing else; a stray log line there
+// corrupts the stream and the client fails in confusing ways.
+const log = (m) => process.stderr.write(`[ratchet-mcp] ${m}\n`);
+const send = (o) => process.stdout.write(`${JSON.stringify(o)}\n`);
+
+if (!KEY) {
+  log('RATCHET_API_KEY is not set.');
+  log('Add it to the "env" block of your MCP client config — not "args", which');
+  log('is visible in process listings. Get a key at ' + BASE + '/console');
+  process.exit(1);
+}
+
+const rpcError = (id, code, message, data) => ({
+  jsonrpc: '2.0', id: id ?? null,
+  error: { code, message, ...(data ? { data } : {}) },
+});
+
+async function forward(msg) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`${BASE}/mcp`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${KEY}`,
+        'content-type': 'application/json',
+        accept: 'application/json',
+      },
+      body: JSON.stringify(msg),
+      signal: controller.signal,
+    });
+
+    // A notification is answered with 202 and no body, by design.
+    if (res.status === 202) return null;
+
+    const text = await res.text();
+    if (!text) return null;
+
+    try {
+      return JSON.parse(text);
+    } catch {
+      return rpcError(msg.id, -32603, `Ratchet returned a non-JSON response (HTTP ${res.status})`);
+    }
+  } catch (err) {
+    // Surface transport failures as JSON-RPC errors rather than dying: the
+    // client can then tell its model the gate is unreachable, which is a
+    // decision it needs to make rather than a crash it cannot see.
+    const aborted = err?.name === 'AbortError';
+    return rpcError(msg.id, -32001,
+      aborted ? `Ratchet did not respond within ${TIMEOUT_MS}ms` : `Cannot reach Ratchet at ${BASE}`,
+      { hint: 'If your agent cannot reach the gate, apply your configured fail-open or '
+            + 'fail-closed policy. See ' + BASE + '/docs' });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+log(`bridging stdio → ${BASE}/mcp`);
+
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+for await (const line of rl) {
+  const trimmed = line.trim();
+  if (!trimmed) continue;
+
+  let msg;
+  try {
+    msg = JSON.parse(trimmed);
+  } catch {
+    send(rpcError(null, -32700, 'Parse error'));
+    continue;
+  }
+
+  try {
+    const reply = await forward(msg);
+    if (reply) send(reply);
+  } catch (err) {
+    log(`unexpected: ${err?.message ?? err}`);
+    send(rpcError(msg?.id, -32603, 'Internal error in the stdio bridge'));
+  }
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "ratchet-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Ratchet — the effect gate for AI agents. Ask before you act, so the same side effect happens at most once.",
+  "type": "module",
+  "bin": { "ratchet-mcp": "bin/ratchet-mcp.mjs" },
+  "files": ["bin", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp", "model-context-protocol", "ai-agents", "idempotency",
+    "at-most-once", "side-effects", "agent-infrastructure", "reliability"
+  ],
+  "repository": { "type": "git", "url": "git+https://github.com/thearchitect0x-glitch/ratchet.git", "directory": "packages/ratchet-mcp" },
+  "homepage": "https://ratchetgate.com",
+  "publishConfig": { "access": "public" }
+}