@nullclear/mcp 1.0.0 → 1.1.2

package/README.md

@@ -1,28 +1,34 @@
-# @nullclear/mcp
-
-Model Context Protocol (MCP) server enabling autonomous AI agents (Claude Desktop, Cursor, Gemini, OpenAI Agents) to safely transact over HTTP 402 with NullClear deferred escrow and reputation scoring.
-
-## Exposed Tools
-
-1. `nullclear_check_reputation`: Query an agent's on-chain trust score, clearing reliability, and Sybil wash-trade penalty flags.
-2. `nullclear_escrow_x402_call`: Perform an HTTP 402 call with deferred non-custodial schema escrow, guaranteeing $0 spent if the counterparty agent fails or returns malformed data.
-3. `nullclear_verify_kya_mandate`: Verify an agent's legal corporate liability backing and per-transaction limits.
-
-## Configuration
-
-Add to your MCP client config (e.g., `claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "nullclear": {
-      "command": "node",
-      "args": ["/path/to/nullclear/packages/mcp-server/dist/index.js"],
-      "env": {
-        "ARBITER_URL": "https://arbiter.nullclear.dev",
-        "BUYER_PRIVATE_KEY": "0x..."
-      }
-    }
-  }
-}
-```
+# @nullclear/mcp
+
+<!-- mcp-name: io.github.Nullclear-Protocol/nullclear -->
+
+[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/nullclear-protocol/nullclear)
+[![NullClear Arbiter MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/Nullclear-Protocol/nullclear/badges/score.svg)](https://glama.ai/mcp/servers/Nullclear-Protocol/nullclear)
+[![NullClear Arbiter MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/Nullclear-Protocol/nullclear/badges/card.svg)](https://glama.ai/mcp/servers/Nullclear-Protocol/nullclear)
+
+Model Context Protocol (MCP) server enabling autonomous AI agents (Claude Desktop, Cursor, Gemini, OpenAI Agents) to safely transact over HTTP 402 with NullClear deferred escrow and reputation scoring.
+
+## Exposed Tools
+
+1. `nullclear_check_reputation`: Query an agent's on-chain trust score, clearing reliability, and Sybil wash-trade penalty flags.
+2. `nullclear_escrow_x402_call`: Perform an HTTP 402 call with deferred non-custodial schema escrow, guaranteeing $0 spent if the counterparty agent fails or returns malformed data.
+3. `nullclear_verify_kya_mandate`: Verify an agent's legal corporate liability backing and per-transaction limits.
+
+## Configuration
+
+Add to your MCP client config (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "nullclear": {
+      "command": "node",
+      "args": ["/path/to/nullclear/packages/mcp-server/dist/index.js"],
+      "env": {
+        "ARBITER_URL": "https://arbiter.nullclear.dev",
+        "BUYER_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```

package/dist/index.js

@@ -5,20 +5,27 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { NullClearClient, createNullClearFetch, NullClearEscrowAbortedError } from "@nullclear/x402-arbiter";
-var ARBITER_URL = process.env.ARBITER_URL || "https://arbiter.nullclear.dev";
-var DEFAULT_BUYER_KEY = process.env.BUYER_PRIVATE_KEY || "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d";
+var ARBITER_URL = process.env.ARBITER_URL || "https://api.nullclear.dev";
+var SANDBOX_TEST_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+var DEFAULT_BUYER_KEY = process.env.BUYER_PRIVATE_KEY || SANDBOX_TEST_KEY;
 var client = new NullClearClient({ arbiterUrl: ARBITER_URL });
 var server = new Server(
   {
     name: "nullclear-mcp-server",
-    version: "1.0.0"
+    version: "1.1.2"
   },
   {
     capabilities: {
-      tools: {}
+      tools: {},
+      prompts: {},
+      resources: {}
     }
   }
 );
@@ -28,13 +35,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       {
         name: "nullclear_check_reputation",
         description: "Inspect an AI agent's trust score (0-100), clearing reliability, Sybil wash-trade penalty flags, and corporate KYA backing on Base",
+        annotations: {
+          title: "Inspect AI Agent Trust & Sybil Score",
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: true
+        },
         inputSchema: {
           type: "object",
           required: ["agentId"],
           properties: {
             agentId: {
               type: "string",
-              description: "The ERC-8004 agent token ID or registered identifier"
+              description: "The ERC-8004 agent token ID or registered identifier (e.g. '124595')"
             },
             chainId: {
               type: "number",
@@ -46,7 +60,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "nullclear_escrow_x402_call",
-        description: "Execute an x402-gated HTTP API call through NullClear deferred schema escrow. The arbiter guarantees payment is only settled if upstream returns valid data matching your schema contract. If the seller hallucinates or crashes, $0 is spent.",
+        description: "Execute an x402-gated HTTP API call through NullClear deferred schema escrow. The arbiter guarantees payment is only settled if upstream returns valid data matching your schema contract. If the seller hallucinates or crashes, $0 is spent. Users can test immediately against https://api.nullclear.dev/v1/sandbox/market-feed (or fail over from https://api.nullclear.dev/v1/sandbox/hallucinating-seller to https://api.nullclear.dev/v1/sandbox/market-feed) with zero wallet setup.",
+        annotations: {
+          title: "Execute Escrowed x402 Call with Invariants",
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: false,
+          openWorldHint: true
+        },
         inputSchema: {
           type: "object",
           required: ["targetUrl"],
@@ -78,6 +99,55 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: "object",
               description: "JSON Schema draft-07 contract that response must strictly satisfy"
             },
+            invariants: {
+              type: "array",
+              description: "Deep value invariants (numeric bounds, regex, forbidden substrings, timestamp freshness)",
+              items: {
+                type: "object",
+                required: ["path"],
+                properties: {
+                  path: { type: "string", description: "Dot-notation property path" },
+                  gt: { type: "number" },
+                  gte: { type: "number" },
+                  lt: { type: "number" },
+                  lte: { type: "number" },
+                  eq: {},
+                  neq: {},
+                  minLength: { type: "number" },
+                  maxLength: { type: "number" },
+                  pattern: { type: "string" },
+                  notContains: { type: "array", items: { type: "string" } },
+                  maxStalenessSeconds: { type: "number" }
+                }
+              }
+            },
+            rejectRefusals: {
+              type: "boolean",
+              description: "Reject canonical LLM refusal strings (default: true)",
+              default: true
+            },
+            fallbacks: {
+              type: "array",
+              description: "Ordered fallback candidates for autonomous multi-seller failover routing (max 3)",
+              items: {
+                type: "object",
+                required: ["targetUrl", "paymentSignatureHeader"],
+                properties: {
+                  targetUrl: { type: "string" },
+                  sellerAgentId: { type: "string" },
+                  paymentSignatureHeader: { type: "string" },
+                  headers: { type: "object" }
+                }
+              }
+            },
+            spendPolicy: {
+              type: "object",
+              description: "Outbound spend firewall limits (maxPerCallAtomic, maxDailyWalletAtomic)",
+              properties: {
+                maxPerCallAtomic: { type: "string", description: "Max atomic USDC spend allowed per call" },
+                maxDailyWalletAtomic: { type: "string", description: "Max rolling daily atomic USDC spend allowed" }
+              }
+            },
             buyerPrivateKey: {
               type: "string",
               description: "Optional buyer private key (defaults to BUYER_PRIVATE_KEY environment variable)"
@@ -88,6 +158,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       {
         name: "nullclear_verify_kya_mandate",
         description: "Verify an agent's Know Your Agent (KYA) corporate liability mandate, active validity, and whether a proposed transaction amount is within corporate limits",
+        annotations: {
+          title: "Verify Corporate KYA Mandate & Limits",
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: true
+        },
         inputSchema: {
           type: "object",
           required: ["agentId", "transactionAmountUsd"],
@@ -111,6 +188,175 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     ]
   };
 });
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return {
+    prompts: [
+      {
+        name: "safe-x402-payment",
+        description: "Generate safety invariants and schema-escrow directives for an autonomous agent paying an upstream x402 seller.",
+        arguments: [
+          {
+            name: "targetUrl",
+            description: "Upstream API endpoint demanding x402 payment",
+            required: true
+          },
+          {
+            name: "sellerAgentId",
+            description: "Seller's ERC-8004 agent token ID to verify reputation",
+            required: false
+          },
+          {
+            name: "maxSpendAtomic",
+            description: "Maximum atomic USDC units authorized (default: 10000 = $0.01 USDC)",
+            required: false
+          }
+        ]
+      },
+      {
+        name: "audit-erc8004-agent",
+        description: "Conduct an end-to-end trust audit on an ERC-8004 agent on Base including Sybil risk and corporate KYA backing.",
+        arguments: [
+          {
+            name: "agentId",
+            description: "ERC-8004 agent token ID (e.g. '124595')",
+            required: true
+          },
+          {
+            name: "chainId",
+            description: "Base chain ID (default: 8453)",
+            required: false
+          }
+        ]
+      }
+    ]
+  };
+});
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const { name, arguments: promptArgs } = request.params;
+  if (name === "safe-x402-payment") {
+    const targetUrl = promptArgs?.targetUrl || "https://api.nullclear.dev/v1/sandbox/market-feed";
+    const sellerAgentId = promptArgs?.sellerAgentId || "unknown";
+    const maxSpendAtomic = promptArgs?.maxSpendAtomic || "10000";
+    return {
+      description: "Safe x402 Escrow Clearing Directive",
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are preparing to execute an autonomous payment to an x402 service at ${targetUrl}.
+
+Mandatory Safety Rules:
+1. NEVER send unconditional payments directly to unverified endpoints.
+2. Invoke the MCP tool 'nullclear_escrow_x402_call' with targetUrl="${targetUrl}", sellerAgentId="${sellerAgentId}", minTrustScore=50, and spendPolicy={ maxPerCallAtomic: "${maxSpendAtomic}" }.
+3. Supply an explicit JSON schema and deep numeric invariants to validate the seller's response before settlement.
+4. If the seller hallucinates, returns an LLM refusal, or crashes, the arbiter voids the payment automatically and $0.00 is charged.`
+          }
+        }
+      ]
+    };
+  }
+  if (name === "audit-erc8004-agent") {
+    const agentId = promptArgs?.agentId || "124595";
+    const chainId = promptArgs?.chainId || "8453";
+    return {
+      description: "ERC-8004 Agent Trust & Sybil Audit",
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Perform a comprehensive security audit of ERC-8004 agent #${agentId} on chain ${chainId}.
+1. Run MCP tool 'nullclear_check_reputation' with agentId="${agentId}", chainId=${chainId}.
+2. Run MCP tool 'nullclear_verify_kya_mandate' with agentId="${agentId}", chainId=${chainId}, transactionAmountUsd=1.0.
+3. Analyze the composite trust score, letter grade (A-F), Sybil wash-trading risk flags, and corporate liability coverage.
+4. Provide a clear recommendation on whether this agent is safe for autonomous financial counterparty interactions.`
+          }
+        }
+      ]
+    };
+  }
+  throw new Error(`Unknown prompt: ${name}`);
+});
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: "nullclear://stats/live",
+        name: "NullClear Live Protocol Telemetry",
+        mimeType: "application/json",
+        description: "Live protocol metrics: total clearings, verified settlements, voided hallucinations, and indexed agents"
+      },
+      {
+        uri: "nullclear://docs/quickstart",
+        name: "NullClear Quickstart Guide",
+        mimeType: "text/markdown",
+        description: "Zero-loss x402 deferred schema escrow guide for autonomous AI agents on Base Mainnet"
+      }
+    ]
+  };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+  if (uri === "nullclear://stats/live") {
+    try {
+      const res = await fetch(`${ARBITER_URL}/v1/stats`);
+      const data = await res.json();
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify(data, null, 2)
+          }
+        ]
+      };
+    } catch {
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify({
+              totalClearings: 0,
+              validSettlements: 0,
+              voidedHallucinations: 0,
+              totalAgentsIndexed: 1,
+              status: "active"
+            }, null, 2)
+          }
+        ]
+      };
+    }
+  }
+  if (uri === "nullclear://docs/quickstart") {
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: `# NullClear Arbiter Quickstart
+
+NullClear is the autonomous deferred clearing and reputation protocol for AI agent commerce on Base Mainnet.
+
+### Core Philosophy
+Never sign away funds unconditionally. Using EIP-3009 signed authorizations and deterministic JSON schema validation, NullClear holds seller payments in deferred escrow and only settles if output adheres 100% to your contract.
+
+### Primary MCP Tools
+- \`nullclear_escrow_x402_call\`: Execute deferred schema escrow with numeric bounds and LLM refusal guards.
+- \`nullclear_check_reputation\`: Check an ERC-8004 agent's Sybil trust score (0-100) and wash-trading flags.
+- \`nullclear_verify_kya_mandate\`: Verify an agent's corporate entity backing and spending limits.
+
+### Test Sandbox
+- Market Feed (Success): \`https://api.nullclear.dev/v1/sandbox/market-feed\` ($0.01 USDC)
+- Hallucinating Seller (Fails & Voids): \`https://api.nullclear.dev/v1/sandbox/hallucinating-seller\`
+`
+        }
+      ]
+    };
+  }
+  throw new Error(`Resource not found: ${uri}`);
+});
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   try {
@@ -148,6 +394,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const minTrustScore = args?.minTrustScore ? Number(args.minTrustScore) : 50;
       const requiredFields = args?.requiredFields || void 0;
       const jsonSchema = args?.jsonSchema || void 0;
+      const invariants = args?.invariants || void 0;
+      const rejectRefusals = args?.rejectRefusals !== void 0 ? Boolean(args.rejectRefusals) : true;
+      const fallbacks = args?.fallbacks || void 0;
+      const spendPolicy = args?.spendPolicy || void 0;
       const buyerPrivateKey = args?.buyerPrivateKey || DEFAULT_BUYER_KEY;
       const nullclearFetch = createNullClearFetch({
         accountOrPrivateKey: buyerPrivateKey,
@@ -162,7 +412,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             sellerAgentId,
             minTrustScore,
             schema: jsonSchema,
-            requiredFields
+            requiredFields,
+            invariants,
+            rejectRefusals,
+            fallbacks,
+            spendPolicy
           }
         });
         const responseText = await response.text();

package/package.json

@@ -1,9 +1,25 @@
 {
   "name": "@nullclear/mcp",
-  "version": "1.0.0",
+  "version": "1.1.2",
+  "mcpName": "io.github.Nullclear-Protocol/nullclear",
   "description": "Model Context Protocol server for autonomous agents using NullClear",
   "license": "MIT",
+  "author": "NullClear Protocol <contact@nullclear.dev>",
   "homepage": "https://nullclear.dev",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "erc-8004",
+    "agent-payments",
+    "escrow",
+    "reputation",
+    "base",
+    "smithery"
+  ],
+  "bugs": {
+    "url": "https://github.com/Nullclear-Protocol/nullclear/issues"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/Nullclear-Protocol/nullclear.git"
@@ -23,8 +39,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.6.1",
-    "@nullclear/shared": "1.0.0",
-    "@nullclear/x402-arbiter": "1.0.0",
+    "@nullclear/shared": "1.1.2",
+    "@nullclear/x402-arbiter": "1.1.2",
     "viem": "^2.23.0",
     "zod": "^3.24.2"
   },