@nullclear/mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nullclear-Protocol
+
+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,28 @@
-# Temporary Holding Version
+# @nullclear/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.d.ts

@@ -0,0 +1,38 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+declare const server: Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;
+
+export { server };

package/dist/index.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} 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 client = new NullClearClient({ arbiterUrl: ARBITER_URL });
+var server = new Server(
+  {
+    name: "nullclear-mcp-server",
+    version: "1.0.0"
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        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",
+        inputSchema: {
+          type: "object",
+          required: ["agentId"],
+          properties: {
+            agentId: {
+              type: "string",
+              description: "The ERC-8004 agent token ID or registered identifier"
+            },
+            chainId: {
+              type: "number",
+              description: "Base chain ID (8453 for Mainnet, 84532 for Sepolia)",
+              default: 8453
+            }
+          }
+        }
+      },
+      {
+        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.",
+        inputSchema: {
+          type: "object",
+          required: ["targetUrl"],
+          properties: {
+            targetUrl: {
+              type: "string",
+              description: "Upstream API endpoint demanding x402 payment"
+            },
+            method: {
+              type: "string",
+              enum: ["GET", "POST", "PUT", "DELETE"],
+              default: "GET"
+            },
+            sellerAgentId: {
+              type: "string",
+              description: "Seller's agent ID for reputation check and Sybil wash-trade gating"
+            },
+            minTrustScore: {
+              type: "number",
+              description: "Minimum acceptable trust score for seller (0-100, default 50)",
+              default: 50
+            },
+            requiredFields: {
+              type: "array",
+              items: { type: "string" },
+              description: "Dot-notation field paths that must exist in response (e.g. ['data.price'])"
+            },
+            jsonSchema: {
+              type: "object",
+              description: "JSON Schema draft-07 contract that response must strictly satisfy"
+            },
+            buyerPrivateKey: {
+              type: "string",
+              description: "Optional buyer private key (defaults to BUYER_PRIVATE_KEY environment variable)"
+            }
+          }
+        }
+      },
+      {
+        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",
+        inputSchema: {
+          type: "object",
+          required: ["agentId", "transactionAmountUsd"],
+          properties: {
+            agentId: {
+              type: "string",
+              description: "The ERC-8004 agent token ID"
+            },
+            chainId: {
+              type: "number",
+              description: "Base chain ID (default 8453)",
+              default: 8453
+            },
+            transactionAmountUsd: {
+              type: "number",
+              description: "Amount in USD intended to spend in the transaction"
+            }
+          }
+        }
+      }
+    ]
+  };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    if (name === "nullclear_check_reputation") {
+      const agentId = String(args?.agentId);
+      const chainId = Number(args?.chainId || 8453);
+      const score = await client.getScore(agentId, chainId);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                status: "success",
+                agentId,
+                chainId,
+                trustScore: score.score,
+                grade: score.grade,
+                sybilFlags: score.sybilFlags,
+                metrics: score.metrics,
+                hasActiveKya: score.metrics.hasActiveKya,
+                arbiterAddress: score.arbiterAddress
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+    if (name === "nullclear_escrow_x402_call") {
+      const targetUrl = String(args?.targetUrl);
+      const method = args?.method || "GET";
+      const sellerAgentId = args?.sellerAgentId ? String(args.sellerAgentId) : void 0;
+      const minTrustScore = args?.minTrustScore ? Number(args.minTrustScore) : 50;
+      const requiredFields = args?.requiredFields || void 0;
+      const jsonSchema = args?.jsonSchema || void 0;
+      const buyerPrivateKey = args?.buyerPrivateKey || DEFAULT_BUYER_KEY;
+      const nullclearFetch = createNullClearFetch({
+        accountOrPrivateKey: buyerPrivateKey,
+        chainId: 8453,
+        arbiterUrl: ARBITER_URL,
+        defaultMinTrustScore: minTrustScore
+      });
+      try {
+        const response = await nullclearFetch(targetUrl, {
+          method,
+          nullclear: {
+            sellerAgentId,
+            minTrustScore,
+            schema: jsonSchema,
+            requiredFields
+          }
+        });
+        const responseText = await response.text();
+        let parsedData;
+        try {
+          parsedData = JSON.parse(responseText);
+        } catch {
+          parsedData = responseText;
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  status: "cleared_and_settled",
+                  message: "Response successfully validated against schema. Payment settled.",
+                  attestation: response.headers.get("X-NullClear-Attestation") || "verified",
+                  data: parsedData
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      } catch (err) {
+        if (err instanceof NullClearEscrowAbortedError) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    status: "escrow_voided_zero_loss",
+                    message: "NullClear escrow voided payment authorization. Exactly $0 spent.",
+                    stage: err.stage,
+                    buyerCharged: err.buyerCharged,
+                    validationErrors: err.validationErrors,
+                    reason: err.reason
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        throw err;
+      }
+    }
+    if (name === "nullclear_verify_kya_mandate") {
+      const agentId = String(args?.agentId);
+      const chainId = Number(args?.chainId || 8453);
+      const transactionAmountUsd = Number(args?.transactionAmountUsd || 0);
+      const mandate = await client.getKya(agentId, chainId);
+      if (!mandate) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                status: "unverified",
+                agentId,
+                chainId,
+                verified: false,
+                reason: "No corporate liability KYA mandate found for this agent."
+              })
+            }
+          ]
+        };
+      }
+      const now = Math.floor(Date.now() / 1e3);
+      const isExpired = mandate.validUntil <= now;
+      const exceedsLimit = transactionAmountUsd > mandate.maxTxLimitUsd;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                status: isExpired || exceedsLimit ? "rejected" : "approved",
+                agentId,
+                chainId,
+                corporateEntity: mandate.corporateEntity,
+                entityRegistrationNumber: mandate.entityRegistrationNumber,
+                jurisdiction: mandate.jurisdiction,
+                maxTxLimitUsd: mandate.maxTxLimitUsd,
+                liabilityCoverageUsd: mandate.liabilityCoverageUsd,
+                isExpired,
+                exceedsLimit,
+                approvedForAmount: !isExpired && !exceedsLimit
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+    throw new Error(`Unknown tool name: ${name}`);
+  } catch (err) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Error executing tool ${name}: ${err.message || String(err)}`
+        }
+      ]
+    };
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+if (process.env.NODE_ENV !== "test") {
+  main().catch((err) => {
+    console.error("Fatal MCP Server Error:", err);
+    process.exit(1);
+  });
+}
+export {
+  server
+};

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@nullclear/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Model Context Protocol server for autonomous agents using NullClear",
+  "license": "MIT",
+  "homepage": "https://nullclear.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nullclear-Protocol/nullclear.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "nullclear-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@nullclear/shared": "1.0.0",
+    "@nullclear/x402-arbiter": "1.0.0",
+    "viem": "^2.23.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "lint": "echo \"@nullclear/mcp clean\""
+  }
 }