@atbash/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chromaway AB
+
+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,161 @@
+# `@atbash/mcp`
+
+Expose Atbash as a standalone MCP server.
+
+This package starts an MCP server process that loads one Atbash agent identity and exposes safety and query tools over the Model Context Protocol. Your MCP host or client remains the real decision-maker — this package does not execute your business tools.
+
+## Installation
+
+```bash
+npm install @atbash/mcp
+```
+
+## When To Use It
+
+Use this package when:
+
+- your host already supports MCP
+- you want one Atbash tool server to serve one or many MCP clients
+- you want Atbash checks without coupling your app directly to the SDK
+
+Do not use this when you need deep framework lifecycle integration — use a framework-native package like `@atbash/eliza-plugin` or `@atbash/langgraph` instead.
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "atbash": {
+      "command": "npx",
+      "args": ["-y", "@atbash/mcp"],
+      "env": {
+        "ATBASH_AGENT_PRIVKEY": "your_agent_private_key_here"
+      }
+    }
+  }
+}
+```
+
+### Any MCP Client
+
+```js
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "npx",
+  args: ["-y", "@atbash/mcp"],
+  env: {
+    ...process.env,
+    ATBASH_AGENT_PRIVKEY: process.env.ATBASH_AGENT_PRIVKEY,
+  },
+});
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ATBASH_AGENT_PRIVKEY` | Yes | Your Atbash agent private key |
+| `ATBASH_ENDPOINT` | No | Override the default Atbash endpoint (`https://atbash.ai`) |
+
+## Tools
+
+### Safety Tools
+
+#### `atbash_judge`
+
+Submit an action for safety judgment before executing it.
+
+| Input | Type | Required | Description |
+|---|---|---|---|
+| `action` | string | Yes | Plain text description of the action |
+| `context` | string | Yes | Why this action is being taken |
+| `tool_name` | string | No | Name of the tool being called |
+| `tool_args_json` | string | No | JSON string of tool arguments |
+
+Returns: `{ verdict, allow, reason, tool_call_id }`
+
+#### `atbash_log`
+
+Log a tool call on-chain without requesting a verdict.
+
+| Input | Type | Required |
+|---|---|---|
+| `action` | string | Yes |
+| `context` | string | Yes |
+| `tool_name` | string | No |
+| `tool_args_json` | string | No |
+
+#### `atbash_check_agent`
+
+Check whether an agent is registered on the Atbash platform.
+
+| Input | Type | Description |
+|---|---|---|
+| `pubkey` | string | Agent public key (defaults to server agent) |
+
+#### `atbash_judgment_status`
+
+Poll the status of a previously submitted judgment.
+
+| Input | Type | Description |
+|---|---|---|
+| `tool_call_id` | string | ID returned from `atbash_judge` |
+| `agent_pubkey` | string | Agent public key (defaults to server agent) |
+
+### Query Tools (read-only)
+
+| Tool | Description |
+|---|---|
+| `atbash_get_policy` | Get agent policy and jail status |
+| `atbash_get_agent_detail` | Get agent metadata |
+| `atbash_get_tool_calls` | List recent tool calls across all agents |
+| `atbash_get_agent_tool_calls` | List recent tool calls for one agent |
+| `atbash_get_org_tool_calls` | List recent tool calls for an organization |
+| `atbash_get_tool_call_full` | Get full detail for a single tool call |
+| `atbash_get_tool_call_count` | Get total on-chain tool call count |
+| `atbash_get_tier_info` | Get organization tier information |
+| `atbash_get_held_actions` | List actions pending operator review |
+| `atbash_get_reviews` | List completed operator reviews |
+| `atbash_get_safety_stats` | Get chain-wide safety statistics |
+
+## Verdict Handling
+
+| Verdict | Meaning | What To Do |
+|---|---|---|
+| `ALLOW` | Safe to proceed | Execute the real tool |
+| `HOLD` | Logged for async review | Execution is allowed; the action is flagged for operator review in the background — keep `tool_call_id` to poll status later |
+| `BLOCK` | Policy violation | Stop; show `reason` to operator |
+| `ERROR` | Judge unreachable | Fail closed |
+
+## Sending Better Inputs
+
+Better inputs produce better safety decisions.
+
+Weak:
+```json
+{ "action": "do payment", "context": "finance" }
+```
+
+Better:
+```json
+{
+  "action": "Bank transfer $25 to a new external vendor account",
+  "context": "Treasury payout review before execution",
+  "tool_name": "send_bank_transfer",
+  "tool_args_json": "{\"amount\":25,\"recipient\":\"new vendor\"}"
+}
+```
+
+## Example
+
+A runnable example is in [`examples/mcp-runtime-agent/`](./examples/mcp-runtime-agent/).
+
+```bash
+npm install && npm run build
+ATBASH_AGENT_PRIVKEY=your_key_here node examples/mcp-runtime-agent/client.mjs
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { loadAgent } from "@atbash/sdk";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/prompts/safety.ts
+import { z } from "zod";
+function registerSafetyPrompt(server2) {
+  const promptServer = server2;
+  if (!promptServer.registerPrompt) {
+    return;
+  }
+  promptServer.registerPrompt(
+    "atbash_safety_check",
+    {
+      description: "Prepare a consistent pre-execution Atbash safety review request.",
+      inputSchema: z.object({
+        action: z.string().describe("Action to evaluate"),
+        context: z.string().describe("Why the action is being taken")
+      })
+    },
+    async ({ action, context }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Use the Atbash tools to evaluate the following action before execution.",
+              `Action: ${action}`,
+              `Context: ${context}`,
+              "If the result is HOLD, explain that operator review is required before proceeding."
+            ].join("\n")
+          }
+        }
+      ]
+    })
+  );
+}
+
+// src/resources/policy.ts
+function registerPolicyResource(server2, agent2, endpoint2) {
+  void server2;
+  void agent2;
+  void endpoint2;
+  return;
+}
+
+// src/tools/judge.ts
+import {
+  checkAgentExists,
+  createAtbashClient,
+  logToolCall
+} from "@atbash/sdk";
+import { z as z2 } from "zod";
+
+// src/utils.ts
+function createClientOpts(endpoint2) {
+  return endpoint2 ? { endpoint: endpoint2 } : void 0;
+}
+function safeErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function toJsonContent(value) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
+  };
+}
+function toErrorContent(error) {
+  return {
+    content: [{ type: "text", text: `Error: ${safeErrorMessage(error)}` }],
+    isError: true
+  };
+}
+
+// src/tools/judge.ts
+function registerJudgeTools(server2, agent2, endpoint2) {
+  const opts = createClientOpts(endpoint2);
+  const client = createAtbashClient({
+    keyPair: { privKey: agent2.privkey, pubKey: agent2.pubkey },
+    judge: endpoint2 ? { endpoint: endpoint2 } : void 0
+  });
+  server2.registerTool(
+    "atbash_judge",
+    {
+      description: "Submit an action for safety judgment before executing it. Returns ALLOW, HOLD, BLOCK, or ERROR.",
+      inputSchema: z2.object({
+        action: z2.string().describe("Plain text description of the action to judge"),
+        context: z2.string().describe("Why this action is being taken"),
+        tool_name: z2.string().optional().describe("Name of the tool being called"),
+        tool_args_json: z2.string().optional().describe("JSON string of tool arguments")
+      })
+    },
+    async ({ action, context, tool_name, tool_args_json }) => {
+      try {
+        let parsedArgs = void 0;
+        if (tool_args_json) {
+          try {
+            parsedArgs = JSON.parse(tool_args_json);
+          } catch {
+            parsedArgs = tool_args_json;
+          }
+        }
+        const decision = await client.auditToolCall({
+          toolName: tool_name ?? "mcp_judge",
+          args: parsedArgs ?? { action },
+          context: `${action} \u2014 ${context}`
+        });
+        const normalized = decision.verdict === "HOLD" ? { ...decision, verdict: "ALLOW", allow: true } : decision;
+        return toJsonContent(normalized);
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_log",
+    {
+      description: "Log a tool call on-chain without requesting a verdict.",
+      inputSchema: z2.object({
+        action: z2.string().describe("Action description"),
+        context: z2.string().describe("Action context"),
+        tool_name: z2.string().optional().describe("Tool name"),
+        tool_args_json: z2.string().optional().describe("Tool arguments JSON")
+      })
+    },
+    async ({ action, context, tool_name, tool_args_json }) => {
+      try {
+        const result = await logToolCall(
+          action,
+          context,
+          agent2,
+          void 0,
+          {
+            toolName: tool_name,
+            toolArgsJson: tool_args_json
+          },
+          opts
+        );
+        return toJsonContent(result);
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_check_agent",
+    {
+      description: "Check whether an agent is registered on the Atbash platform.",
+      inputSchema: z2.object({
+        pubkey: z2.string().optional().describe("Agent public key, defaults to this server agent")
+      })
+    },
+    async ({ pubkey }) => {
+      try {
+        const selectedPubkey = pubkey ?? agent2.pubkey;
+        const registered = await checkAgentExists(selectedPubkey, opts);
+        return toJsonContent({ registered, pubkey: selectedPubkey });
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+}
+
+// src/tools/queries.ts
+import {
+  getAgentDetail,
+  getAgentPolicy,
+  getAgentToolCalls,
+  getHeldActionReviews,
+  getOrgTierInfo,
+  getOrgToolCalls,
+  getPendingHeldActions,
+  getSafetyStats,
+  getToolCallCount,
+  getToolCallFull,
+  getToolCalls
+} from "@atbash/sdk";
+import { z as z3 } from "zod";
+function defaultMaxCount(value) {
+  return value ?? 20;
+}
+function registerQueryTools(server2, agent2, endpoint2) {
+  const opts = createClientOpts(endpoint2);
+  server2.registerTool(
+    "atbash_get_policy",
+    {
+      description: "Get an agent policy configuration and jail status.",
+      inputSchema: z3.object({
+        pubkey: z3.string().optional().describe("Agent public key, defaults to the server agent")
+      })
+    },
+    async ({ pubkey }) => {
+      try {
+        return toJsonContent(await getAgentPolicy(pubkey ?? agent2.pubkey, opts));
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_agent_detail",
+    {
+      description: "Get agent metadata for a public key.",
+      inputSchema: z3.object({
+        pubkey: z3.string().optional().describe("Agent public key, defaults to the server agent")
+      })
+    },
+    async ({ pubkey }) => {
+      try {
+        return toJsonContent(await getAgentDetail(pubkey ?? agent2.pubkey, opts));
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_tool_calls",
+    {
+      description: "List recent tool calls across all agents.",
+      inputSchema: z3.object({
+        max_count: z3.number().int().positive().optional().describe("Maximum number of records")
+      })
+    },
+    async ({ max_count }) => {
+      try {
+        return toJsonContent(await getToolCalls(defaultMaxCount(max_count), opts));
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_agent_tool_calls",
+    {
+      description: "List recent tool calls for one agent.",
+      inputSchema: z3.object({
+        pubkey: z3.string().optional().describe("Agent public key, defaults to the server agent"),
+        max_count: z3.number().int().positive().optional().describe("Maximum number of records")
+      })
+    },
+    async ({ pubkey, max_count }) => {
+      try {
+        return toJsonContent(
+          await getAgentToolCalls(pubkey ?? agent2.pubkey, defaultMaxCount(max_count), opts)
+        );
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_org_tool_calls",
+    {
+      description: "List recent tool calls for an organization.",
+      inputSchema: z3.object({
+        org_name: z3.string().describe("Organization name"),
+        max_count: z3.number().int().positive().optional().describe("Maximum number of records")
+      })
+    },
+    async ({ org_name, max_count }) => {
+      try {
+        return toJsonContent(await getOrgToolCalls(org_name, defaultMaxCount(max_count), opts));
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_tool_call_full",
+    {
+      description: "Get the full detail for a single tool call.",
+      inputSchema: z3.object({
+        tool_call_id: z3.string().describe("Tool call identifier")
+      })
+    },
+    async ({ tool_call_id }) => {
+      try {
+        return toJsonContent(await getToolCallFull(tool_call_id, opts));
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_tool_call_count",
+    {
+      description: "Get the total number of tool calls on-chain.",
+      inputSchema: z3.object({})
+    },
+    async () => {
+      try {
+        return toJsonContent({ count: await getToolCallCount(opts) });
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_tier_info",
+    {
+      description: "Get an organization's tier information.",
+      inputSchema: z3.object({
+        org_name: z3.string().describe("Organization name")
+      })
+    },
+    async ({ org_name }) => {
+      try {
+        return toJsonContent(await getOrgTierInfo(org_name, opts));
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_held_actions",
+    {
+      description: "List actions currently waiting for operator review.",
+      inputSchema: z3.object({
+        org_name: z3.string().describe("Organization name"),
+        max_count: z3.number().int().positive().optional().describe("Maximum number of records")
+      })
+    },
+    async ({ org_name, max_count }) => {
+      try {
+        return toJsonContent(
+          await getPendingHeldActions(org_name, defaultMaxCount(max_count), opts)
+        );
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_reviews",
+    {
+      description: "List completed operator reviews for held actions.",
+      inputSchema: z3.object({
+        org_name: z3.string().describe("Organization name"),
+        max_count: z3.number().int().positive().optional().describe("Maximum number of records")
+      })
+    },
+    async ({ org_name, max_count }) => {
+      try {
+        return toJsonContent(await getHeldActionReviews(org_name, defaultMaxCount(max_count), opts));
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+  server2.registerTool(
+    "atbash_get_safety_stats",
+    {
+      description: "Get high-level chain-wide safety statistics.",
+      inputSchema: z3.object({})
+    },
+    async () => {
+      try {
+        return toJsonContent(await getSafetyStats(opts));
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+}
+
+// src/tools/status.ts
+import { z as z4 } from "zod";
+function normalizeVerdict(raw) {
+  if (raw == null) return "No verdict";
+  const value = String(raw).toUpperCase();
+  if (value === "ALLOW" || value === "GREEN") return "ALLOW";
+  if (value === "HOLD" || value === "YELLOW") return "HOLD";
+  if (value === "BLOCK" || value === "RED") return "BLOCK";
+  return value;
+}
+function normalizeStatus(raw) {
+  const value = String(raw ?? "").toLowerCase();
+  if (value === "pending" || value === "answered" || value === "error") {
+    return value;
+  }
+  return "error";
+}
+function registerStatusTools(server2, defaultPubkey, endpoint2) {
+  const baseUrl = (endpoint2 ?? "https://atbash.ai").replace(/\/$/, "");
+  server2.registerTool(
+    "atbash_judgment_status",
+    {
+      description: "Poll the status of a previously submitted judgment.",
+      inputSchema: z4.object({
+        tool_call_id: z4.string().describe("The tool_call_id returned from atbash_judge"),
+        agent_pubkey: z4.string().optional().describe("Agent public key, defaults to the server agent")
+      })
+    },
+    async ({ tool_call_id, agent_pubkey }) => {
+      try {
+        const pubkey = agent_pubkey ?? defaultPubkey;
+        const url = new URL(`${baseUrl}/api/v1/judge`);
+        url.searchParams.set("tool_call_id", tool_call_id);
+        url.searchParams.set("agent_pubkey", pubkey);
+        const response = await fetch(url, {
+          method: "GET",
+          headers: { Accept: "application/json" }
+        });
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          throw new Error(`API error ${response.status}: ${body || response.statusText}`);
+        }
+        const data = await response.json();
+        return toJsonContent({
+          status: normalizeStatus(data.status),
+          verdict: normalizeVerdict(data.verdict),
+          reason: String(data.reason ?? ""),
+          judgmentId: String(data.judgmentId ?? tool_call_id),
+          onChain: Boolean(data.onChain),
+          cached: Boolean(data.cached),
+          responseTimeMs: Number(data.responseTimeMs ?? 0),
+          tool_call_id,
+          agent_pubkey: pubkey
+        });
+      } catch (error) {
+        return toErrorContent(error);
+      }
+    }
+  );
+}
+
+// src/index.ts
+var privkey = process.env.ATBASH_AGENT_PRIVKEY;
+if (!privkey) {
+  console.error("ATBASH_AGENT_PRIVKEY env var is required");
+  process.exit(1);
+}
+var agent = loadAgent(privkey);
+var endpoint = process.env.ATBASH_ENDPOINT;
+var server = new McpServer({
+  name: "atbash-safety",
+  version: "1.0.0"
+});
+registerJudgeTools(server, agent, endpoint);
+registerStatusTools(server, agent.pubkey, endpoint);
+registerQueryTools(server, agent, endpoint);
+registerPolicyResource(server, agent, endpoint);
+registerSafetyPrompt(server);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@atbash/mcp",
+  "version": "0.1.0",
+  "description": "Atbash safety judge exposed as a standalone MCP server",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "atbash-mcp": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "atbash",
+    "mcp",
+    "ai-safety",
+    "agent-safety",
+    "model-context-protocol",
+    "judge",
+    "policy"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean"
+  },
+  "dependencies": {
+    "@atbash/sdk": "^0.3.8",
+    "@modelcontextprotocol/sdk": "^1.12.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}