aegis-x402-mcp 1.0.2 → 1.0.4

package/README.md

@@ -33,8 +33,8 @@
    Tools like `aegis_token_preview` and `aegis_recent_audits` work instantly out-of-the-box with zero configuration or keys.
 
 2. **Tier 2 — Prepaid Credit Token (Recommended for Humans):**
-   Top up in 1-click at [https://aegis-audit-x402.project-easy-x.workers.dev/pay](https://aegis-audit-x402.project-easy-x.workers.dev/pay) to get a credit token `ck_...`.
-   Add `AEGIS_CREDIT_TOKEN` in your config. No wallet, no signing, zero friction.
+   Top up in 1-click at [https://aegis-audit-x402.project-easy-x.workers.dev/pay](https://aegis-audit-x402.project-easy-x.workers.dev/pay) to get a signed 24-hour credit token `aegis_credit_...`.
+   Add `AEGIS_CREDIT_TOKEN` in your config. No local wallet key or per-call signing required.
 
 3. **Tier 3 — Autonomous Agentic Wallet (For Autonomous Trading Bots & Power Users):**
    Add `AEGIS_PRIVATE_KEY` in your config.
@@ -59,7 +59,7 @@ Add this configuration to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "aegis-x402-mcp"],
       "env": {
-        "AEGIS_CREDIT_TOKEN": "ck_your_credit_token_or_leave_empty_for_free_tier"
+        "AEGIS_CREDIT_TOKEN": "aegis_credit_your_token_or_leave_empty_for_free_tier"
       }
     }
   }
@@ -77,7 +77,7 @@ Create or update `.cursor/mcp.json` in your project root:
       "command": "npx",
       "args": ["-y", "aegis-x402-mcp"],
       "env": {
-        "AEGIS_CREDIT_TOKEN": "ck_your_credit_token"
+        "AEGIS_CREDIT_TOKEN": "aegis_credit_your_token"
       }
     }
   }
@@ -106,8 +106,10 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 | Variable | Description |
 |---|---|
 | `AEGIS_GATEWAY_URL` | Gateway URL (defaults to `https://aegis-audit-x402.project-easy-x.workers.dev`). |
-| `AEGIS_API_KEY` | Optional developer API key to bypass per-call x402 signing. |
-| `X402_PAYMENT_HEADER` | Pre-signed EIP-3009 payment header or authorization token. |
+| `AEGIS_CREDIT_TOKEN` | Tier-bound 24h prepaid credit token generated from `/pay` or prior `X-Aegis-Credit-Token` settlement headers. |
+| `AEGIS_PRIVATE_KEY` | Optional local EVM private key (`0x...`) used in-process to sign EIP-3009 USDC authorizations on Base without keys ever leaving your machine. |
+| `AEGIS_API_KEY` | Alias for `AEGIS_CREDIT_TOKEN` / prepaid enterprise API key. |
+| `X402_PAYMENT_HEADER` | Pre-signed base64 EIP-3009 payment header or authorization token. |
 
 ---
 

package/dist/index.d.ts

@@ -1,2 +1,17 @@
 #!/usr/bin/env node
-export {};
+export declare const ALLOWED_PAYTO: string;
+export declare const BASE_USDC: string;
+export declare function parseChainIdFromNetwork(network?: string): number;
+/**
+ * Signs EIP-3009 TransferWithAuthorization locally inside the user's MCP process.
+ * Keys never leave the local machine.
+ * Protected by strict recipient allowlist guard: only signs toward official Aegis address.
+ */
+export declare function signEip3009Payment(privateKeyHex: string, accepts: any, resource?: any): Promise<string>;
+/**
+ * 3-Tier Execution Pipeline:
+ * Tier 1: Zero-config free tools execute immediately.
+ * Tier 2: Prepaid credit token (AEGIS_CREDIT_TOKEN / AEGIS_API_KEY) in env.
+ * Tier 3: Local wallet signing (AEGIS_PRIVATE_KEY) in env -> signs 402 challenge and retries seamlessly.
+ */
+export declare function fetchFromAegis(endpoint: string, options?: RequestInit): Promise<any>;

package/dist/index.js

@@ -9,14 +9,18 @@ const GATEWAY_URL = process.env.AEGIS_GATEWAY_URL || 'https://aegis-audit-x402.p
 const API_KEY = process.env.AEGIS_API_KEY || process.env.AEGIS_CREDIT_TOKEN || '';
 const PRIVATE_KEY = process.env.AEGIS_PRIVATE_KEY || '';
 const PAYMENT_HEADER = process.env.X402_PAYMENT_HEADER || '';
-const ALLOWED_PAYTO = '0x111ef680B6EFdd859FbEc473b907aCe95F0D1acB'.toLowerCase();
-const BASE_USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'.toLowerCase();
+export const ALLOWED_PAYTO = '0x111ef680B6EFdd859FbEc473b907aCe95F0D1acB'.toLowerCase();
+export const BASE_USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'.toLowerCase();
+export function parseChainIdFromNetwork(network) {
+    const match = String(network || '').match(/^eip155:(\d+)$/);
+    return match ? Number(match[1]) : 8453;
+}
 /**
  * Signs EIP-3009 TransferWithAuthorization locally inside the user's MCP process.
  * Keys never leave the local machine.
  * Protected by strict recipient allowlist guard: only signs toward official Aegis address.
  */
-async function signEip3009Payment(privateKeyHex, accepts, resource) {
+export async function signEip3009Payment(privateKeyHex, accepts, resource) {
     const cleanKey = privateKeyHex.trim().startsWith('0x')
         ? privateKeyHex.trim()
         : `0x${privateKeyHex.trim()}`;
@@ -33,10 +37,11 @@ async function signEip3009Payment(privateKeyHex, accepts, resource) {
     const fromChecksum = getAddress(account.address);
     const toChecksum = getAddress(accepts.payTo || accepts.recipient);
     const assetChecksum = getAddress(accepts.asset || BASE_USDC);
+    const chainId = parseChainIdFromNetwork(accepts.network);
     const domain = {
         name: accepts.extra?.name || 'USD Coin',
         version: accepts.extra?.version || '2',
-        chainId: 8453,
+        chainId,
         verifyingContract: assetChecksum,
     };
     const types = {
@@ -89,7 +94,7 @@ async function signEip3009Payment(privateKeyHex, accepts, resource) {
  * Tier 2: Prepaid credit token (AEGIS_CREDIT_TOKEN / AEGIS_API_KEY) in env.
  * Tier 3: Local wallet signing (AEGIS_PRIVATE_KEY) in env -> signs 402 challenge and retries seamlessly.
  */
-async function fetchFromAegis(endpoint, options = {}) {
+export async function fetchFromAegis(endpoint, options = {}) {
     const url = `${GATEWAY_URL}${endpoint}`;
     const headers = {
         'Accept': 'application/json',
@@ -120,9 +125,22 @@ async function fetchFromAegis(endpoint, options = {}) {
                 if (retryRes.ok) {
                     return retryRes.json();
                 }
+                const retryBody = await retryRes.json().catch(async () => ({ raw: await retryRes.text().catch(() => '') }));
+                return {
+                    status: 'UPSTREAM_ERROR',
+                    statusCode: retryRes.status,
+                    charged: false,
+                    message: retryBody?.message || retryBody?.error || retryRes.statusText || 'Payment retry failed',
+                    details: retryBody,
+                };
             }
             catch (signErr) {
-                console.error('[aegis-mcp] Local EIP-3009 signing failed:', signErr?.message);
+                return {
+                    status: 'UPSTREAM_ERROR',
+                    statusCode: 500,
+                    charged: false,
+                    message: `Local EIP-3009 signing failed: ${signErr?.message || String(signErr)}`,
+                };
             }
         }
         // Friendly, structured notification for the LLM without crashing
@@ -132,8 +150,8 @@ async function fetchFromAegis(endpoint, options = {}) {
             statusCode: 402,
             price,
             payTo: accepts?.recipient || accepts?.payTo || ALLOWED_PAYTO,
-            network: 'eip155:8453 (Base Mainnet)',
-            message: `[AEGIS x402 PAYMENT REQUIRED] This tool costs ${price} on Base Mainnet.`,
+            network: `${accepts?.network || 'eip155:8453'}`,
+            message: `[AEGIS x402 PAYMENT REQUIRED] This tool costs ${price} on Base.`,
             setupInstructions: {
                 optionA_prepaidCredits: 'Top up in 1-click at https://aegis-audit-x402.project-easy-x.workers.dev/pay and add AEGIS_CREDIT_TOKEN in your MCP settings (zero signing required).',
                 optionB_agenticWallet: 'Add AEGIS_PRIVATE_KEY in your MCP config; the local process will sign EIP-3009 gasless settlements on-demand without keys ever leaving your machine.',
@@ -141,11 +159,21 @@ async function fetchFromAegis(endpoint, options = {}) {
             paymentDetails: paymentReq,
         };
     }
+    if (!res.ok) {
+        const errBody = await res.json().catch(async () => ({ raw: await res.text().catch(() => '') }));
+        return {
+            status: 'UPSTREAM_ERROR',
+            statusCode: res.status,
+            charged: false,
+            message: errBody?.message || errBody?.error || res.statusText || 'Aegis gateway request failed',
+            details: errBody,
+        };
+    }
     return res.json();
 }
 const server = new Server({
     name: 'aegis-x402-mcp',
-    version: '1.0.2',
+    version: '1.0.4',
 }, {
     capabilities: {
         tools: {},
@@ -270,6 +298,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ['url'],
                 },
             },
+            {
+                name: 'aegis_grounded_chat',
+                description: 'USE WHEN: Running OpenAI-compatible LLM reasoning grounded in live Base/Ethereum/Solana on-chain security telemetry ($0.005 USDC on Base).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        prompt: {
+                            type: 'string',
+                            description: 'Security or DeFi analysis question to run with live on-chain token context',
+                        },
+                        model: {
+                            type: 'string',
+                            description: 'Optional model identifier (defaults to aegis-llama-3.3-70b-grounded)',
+                        },
+                    },
+                    required: ['prompt'],
+                },
+            },
             {
                 name: 'aegis_recent_audits',
                 description: 'USE WHEN: Monitoring the real-time stream of recently scanned tokens on Base, Ethereum, and Solana (FREE).',
@@ -336,6 +382,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
             };
         }
+        if (name === 'aegis_grounded_chat') {
+            const prompt = String(args?.prompt || 'Analyze Base USDC safety.');
+            const model = String(args?.model || 'aegis-llama-3.3-70b-grounded');
+            const data = await fetchFromAegis('/v1/chat/completions', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ model, messages: [{ role: 'user', content: prompt }] }),
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+            };
+        }
         if (name === 'aegis_recent_audits') {
             const data = await fetchFromAegis('/api/v1/recent');
             return {
@@ -355,7 +413,9 @@ async function run() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-run().catch((error) => {
-    console.error('Fatal error running aegis-x402-mcp server:', error);
-    process.exit(1);
-});
+if (process.env.AEGIS_MCP_TEST !== '1') {
+    run().catch((error) => {
+        console.error('Fatal error running aegis-x402-mcp server:', error);
+        process.exit(1);
+    });
+}

package/dist/test.js

@@ -1,10 +1,177 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-test('aegis-x402-mcp package configuration', () => {
-    assert.ok(true, 'Test harness operates correctly');
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { verifyTypedData, getAddress } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+process.env.AEGIS_MCP_TEST = '1';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+test('official payTo allowlist enforces official Aegis receiver address', async () => {
+    const { ALLOWED_PAYTO, BASE_USDC } = await import('./index.js');
+    assert.equal(ALLOWED_PAYTO, '0x111ef680b6efdd859fbec473b907ace95f0d1acb');
+    assert.equal(BASE_USDC, '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913');
 });
-test('official payTo allowlist contains official Aegis node', () => {
-    const officialPayTo = '0x111ef680B6EFdd859FbEc473b907aCe95F0D1acB'.toLowerCase();
-    assert.equal(officialPayTo.length, 42);
-    assert.ok(officialPayTo.startsWith('0x111ef'));
+test('signEip3009Payment refuses rogue payTo recipient via SECURITY_RECIPIENT_GUARD', async () => {
+    const { signEip3009Payment } = await import('./index.js');
+    const testPk = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+    await assert.rejects(async () => signEip3009Payment(testPk, {
+        scheme: 'exact',
+        network: 'eip155:8453',
+        amount: '200000',
+        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        payTo: '0x000000000000000000000000000000000000dEaD',
+    }), /SECURITY_RECIPIENT_GUARD/);
+});
+test('signEip3009Payment builds valid x402 v2 EIP-3009 authorization recoverable via EIP-712', async () => {
+    const { signEip3009Payment } = await import('./index.js');
+    const testPk = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+    const expectedAccount = privateKeyToAccount(testPk);
+    const accepts = {
+        scheme: 'exact',
+        network: 'eip155:8453',
+        amount: '200000',
+        asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        payTo: '0x111ef680B6EFdd859FbEc473b907aCe95F0D1acB',
+        maxTimeoutSeconds: 300,
+        extra: { name: 'USD Coin', version: '2' },
+    };
+    const b64 = await signEip3009Payment(testPk, accepts, {
+        url: 'https://aegis-audit-x402.project-easy-x.workers.dev/api/v1/preflight/bundle',
+    });
+    const decoded = JSON.parse(Buffer.from(b64, 'base64').toString('utf-8'));
+    assert.equal(decoded.x402Version, 2);
+    assert.ok(decoded.payload.authorization, 'authorization block must exist');
+    assert.ok(decoded.payload.signature, 'EIP-712 signature must exist');
+    assert.equal(decoded.accepted.payTo, '0x111ef680B6EFdd859FbEc473b907aCe95F0D1acB');
+    assert.equal(decoded.payload.authorization.value, '200000');
+    const auth = decoded.payload.authorization;
+    const isValid = await verifyTypedData({
+        address: expectedAccount.address,
+        domain: {
+            name: 'USD Coin',
+            version: '2',
+            chainId: 8453,
+            verifyingContract: getAddress(accepts.asset),
+        },
+        types: {
+            TransferWithAuthorization: [
+                { name: 'from', type: 'address' },
+                { name: 'to', type: 'address' },
+                { name: 'value', type: 'uint256' },
+                { name: 'validAfter', type: 'uint256' },
+                { name: 'validBefore', type: 'uint256' },
+                { name: 'nonce', type: 'bytes32' },
+            ],
+        },
+        primaryType: 'TransferWithAuthorization',
+        message: {
+            from: getAddress(auth.from),
+            to: getAddress(auth.to),
+            value: BigInt(auth.value),
+            validAfter: BigInt(auth.validAfter),
+            validBefore: BigInt(auth.validBefore),
+            nonce: auth.nonce,
+        },
+        signature: decoded.payload.signature,
+    });
+    assert.equal(isValid, true, 'EIP-712 TransferWithAuthorization signature must verify cleanly');
+});
+test('MCP stdio handshake (SDK 1.32.2) initializes cleanly and exposes all 7 tools', async () => {
+    const serverPath = join(__dirname, 'index.js');
+    const env = { ...process.env };
+    delete env.AEGIS_MCP_TEST;
+    const child = spawn(process.execPath, [serverPath], {
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const responses = [];
+    let buffer = '';
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error('MCP stdio handshake timed out'));
+        }, 6000);
+        child.stdout.on('data', (chunk) => {
+            buffer += chunk.toString('utf-8');
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const msg = JSON.parse(trimmed);
+                    responses.push(msg);
+                    if (msg.id === 1) {
+                        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+                        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }) + '\n');
+                    }
+                    else if (msg.id === 2) {
+                        clearTimeout(timer);
+                        child.kill();
+                        resolve();
+                    }
+                }
+                catch {
+                    // ignore non-JSON lines
+                }
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.stdin.write(JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2025-06-18',
+                capabilities: {},
+                clientInfo: { name: 'aegis-ci-test', version: '1.0.4' },
+            },
+        }) + '\n');
+    });
+    const initRes = responses.find((r) => r.id === 1);
+    assert.ok(initRes?.result?.serverInfo, 'initialize must return serverInfo');
+    assert.equal(initRes.result.serverInfo.name, 'aegis-x402-mcp');
+    assert.equal(initRes.result.serverInfo.version, '1.0.4');
+    const listRes = responses.find((r) => r.id === 2);
+    const tools = listRes?.result?.tools || [];
+    assert.equal(tools.length, 8, 'Must expose all 8 Aegis MCP tools');
+    const names = tools.map((t) => t.name);
+    assert.ok(names.includes('aegis_preflight_bundle'));
+    assert.ok(names.includes('aegis_priority_audit'));
+    assert.ok(names.includes('aegis_token_audit'));
+    assert.ok(names.includes('aegis_token_preview'));
+    assert.ok(names.includes('aegis_wallet_kya'));
+    assert.ok(names.includes('aegis_web_scrape'));
+    assert.ok(names.includes('aegis_grounded_chat'));
+    assert.ok(names.includes('aegis_recent_audits'));
+});
+test('parseChainIdFromNetwork resolves mainnet, sepolia, and safe fallback', async () => {
+    const { parseChainIdFromNetwork } = await import('./index.js');
+    assert.equal(parseChainIdFromNetwork('eip155:8453'), 8453);
+    assert.equal(parseChainIdFromNetwork('eip155:84532'), 84532);
+    assert.equal(parseChainIdFromNetwork('solana:mainnet'), 8453);
+    assert.equal(parseChainIdFromNetwork(undefined), 8453);
+});
+test('fetchFromAegis returns structured UPSTREAM_ERROR on non-OK HTTP responses instead of throwing on res.json', async () => {
+    const { fetchFromAegis } = await import('./index.js');
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async () => new Response(JSON.stringify({ error: 'UPSTREAM_502_ABORTED_BEFORE_CHARGE' }), {
+        status: 502,
+        headers: { 'Content-Type': 'application/json' },
+    }));
+    try {
+        const out = await fetchFromAegis('/api/v1/token/audit');
+        assert.equal(out.status, 'UPSTREAM_ERROR');
+        assert.equal(out.statusCode, 502);
+        assert.equal(out.charged, false);
+    }
+    finally {
+        globalThis.fetch = origFetch;
+    }
 });

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "aegis-x402-mcp",
-  "version": "1.0.2",
-  "description": "Model Context Protocol (MCP) server for AegisAudit x402 Security Intelligence, PreFlight Bundles, KYA, and Grounded AI on Base",
+  "mcpName": "io.github.Goatincrypto/aegis-x402-mcp",
+  "version": "1.0.4",
+  "description": "MCP server for AegisAudit x402 token security, honeypot simulation, KYA, and PreFlight clearance",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -10,7 +11,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "server.json"
   ],
   "scripts": {
     "build": "tsc",
@@ -40,7 +42,7 @@
   "author": "Antigravity Autonomous Systems",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "viem": "^2.21.0"
   },
   "devDependencies": {

package/server.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.Goatincrypto/aegis-x402-mcp",
+  "description": "On-chain token security, honeypot simulation, KYA wallet trust, and x402 PreFlight audits on Base.",
+  "repository": {
+    "url": "https://github.com/Goatincrypto/aegis-x402-mcp",
+    "source": "github"
+  },
+  "version": "1.0.3",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "aegis-x402-mcp",
+      "version": "1.0.3",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "AEGIS_CREDIT_TOKEN",
+          "description": "Optional prepaid credit token from /pay for zero-wallet Tier-2 MCP access",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": true
+        },
+        {
+          "name": "AEGIS_PRIVATE_KEY",
+          "description": "Optional EVM private key for local gasless EIP-3009 x402 USDC settlement on Base",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": true
+        }
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://aegis-audit-x402.project-easy-x.workers.dev/mcp"
+    }
+  ]
+}