@atbash/atbash-mcp 0.0.1

package/LICENSE

@@ -0,0 +1,14 @@
+Atbash CLI — Proprietary Software License
+
+Copyright © 2026 Atbash. All rights reserved.
+
+The full license is available at https://atbash.ai/license
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Atbash.

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,53 @@
+{
+  "name": "@atbash/atbash-mcp",
+  "version": "0.0.1",
+  "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": "SEE LICENSE IN LICENSE",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "example": "npm run build && npm install --prefix examples/mcp-runtime-agent && node examples/mcp-runtime-agent/client.mjs",
+    "prepublishOnly": "npm run build",
+    "publish:prod": "npm publish --tag latest --access public",
+    "publish:dev": "node scripts/publish-dev.mjs"
+  },
+  "dependencies": {
+    "@atbash/sdk": "^0.3.20",
+    "@modelcontextprotocol/sdk": "^1.12.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}