phoenix-mcp-server 1.0.0 → 1.1.0

package/README.md

@@ -1,53 +1,53 @@
-# Phoenix Zero MCP Server
-
-Model Context Protocol server exposing L2 network health telemetry to AI agents.
-
-## Tool: `preflight_network_health`
-
-Determine whether an L2 network is currently suitable for transaction execution using kernel-level network telemetry.
-
-**Parameters:**
-- `chain` (optional) — one of: base, arbitrum, optimism, zksync, scroll, mantle, linea, blast, mode, taiko, polygon_zkevm, casper
-- `metric` — `health_check` (free) | `rtt_ns` (x402 $0.01) | `revert_ratio` (x402 $0.01)
-
-**Returns:** `PASS`, `DEGRADED`, or `FAIL` with evidence (uptime, staleness, sampling interval).
-
-## Setup
-
-```bash
-npm install
-npm run build
-```
-
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "phoenix-zero": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
-    }
-  }
-}
-```
-
-### Test with Inspector
-
-```bash
-npx @modelcontextprotocol/inspector node dist/index.js
-```
-
-## Data Source
-
-Live production oracle at `rtt.phoenix-ai.work`:
-- 12 L2 chains monitored every 2 seconds
-- eBPF XDP kernel-level probes
-- BLAKE3 + Ed25519 integrity on every measurement
-- x402 micropayment for premium data ($0.01/query)
-
-## License
-
-MIT
+# Phoenix Zero MCP Server
+
+Model Context Protocol server exposing L2 network health telemetry to AI agents.
+
+## Tool: `preflight_network_health`
+
+Determine whether an L2 network is currently suitable for transaction execution using kernel-level network telemetry.
+
+**Parameters:**
+- `chain` (optional) — one of: base, arbitrum, optimism, zksync, scroll, mantle, linea, blast, mode, taiko, polygon_zkevm, casper
+- `metric` — `health_check` (free) | `rtt_ns` (x402 $0.01) | `revert_ratio` (x402 $0.01)
+
+**Returns:** `PASS`, `DEGRADED`, or `FAIL` with evidence (uptime, staleness, sampling interval).
+
+## Setup
+
+```bash
+npm install
+npm run build
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "phoenix-zero": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+### Test with Inspector
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## Data Source
+
+Live production oracle at `rtt.phoenix-ai.work`:
+- 12 L2 chains monitored every 2 seconds
+- eBPF XDP kernel-level probes
+- BLAKE3 + Ed25519 integrity on every measurement
+- x402 micropayment for premium data ($0.01/query)
+
+## License
+
+MIT

package/dist/index.js

@@ -27,6 +27,16 @@ async function fetchHealth() {
     }
     return res.json();
 }
+async function fetchDemoSafe(chain) {
+    const url = chain
+        ? `${PHOENIX_BASE}/api/v1/demo/safe?chain=${chain}`
+        : `${PHOENIX_BASE}/api/v1/demo/safe`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Demo endpoint returned ${res.status}`);
+    }
+    return res.json();
+}
 async function fetchChainHealth(chain) {
     const res = await fetch(`${PHOENIX_BASE}/api/v1/chains/${chain}`);
     if (res.status === 402)
@@ -37,7 +47,37 @@ async function fetchChainHealth(chain) {
 }
 const server = new McpServer({
     name: "phoenix-zero",
-    version: "1.0.0",
+    version: "1.1.0",
+});
+server.tool("check_safety_free", `FREE safety check for L2 networks — no payment required (100 calls/IP/day). Returns safe/unsafe verdict with reason code. Use this first to sample data before committing to paid x402 endpoints. Prevents $5-$15 gas loss on failed transactions during sequencer stalls.`, {
+    chain: z
+        .enum(CHAINS)
+        .optional()
+        .describe("L2 chain to check. Defaults to Base if omitted."),
+}, async ({ chain }) => {
+    try {
+        const data = await fetchDemoSafe(chain);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: message, source: PHOENIX_BASE }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
 });
 server.tool("preflight_network_health", `Determine whether an L2 network is currently suitable for transaction execution using kernel-level network telemetry. Returns PASS, DEGRADED, or FAIL with RTT, packet-loss and timestamp evidence. Covers 12 L2 chains (Base, Arbitrum, Optimism, zkSync, Scroll, Mantle, Linea, Blast, Mode, Taiko, Polygon zkEVM, Casper). Data sourced from eBPF XDP probes with 2-second sampling interval, signed with BLAKE3+Ed25519.`, {
     chain: z
@@ -97,12 +137,13 @@ server.tool("preflight_network_health", `Determine whether an L2 network is curr
                         price: "$0.01 USDC",
                         payment_protocol: "x402 (HTTP 402 micropayment)",
                         endpoint: premiumEndpoint,
+                        preflight_endpoint: `${PHOENIX_BASE}/api/v1/preflight`,
+                        preflight_note: "POST /api/v1/preflight with {chain} body returns deterministic PASS/DEGRADED/FAIL with evidence_id proving exact network state at decision time.",
                         payment_rails: [
                             { network: "Base mainnet (eip155:8453)", asset: "USDC" },
                             { network: "Hedera testnet", asset: "native HBAR" },
                         ],
-                        how_to_pay: "Send GET request to the endpoint. Server returns 402 with X-PAYMENT header containing payment challenge. Complete x402 payment flow to receive full telemetry.",
-                        discovery: `${PHOENIX_BASE}/.well-known/x402`,
+                        how_to_pay: "Send request to the endpoint. Server returns 402 with payment-required header containing x402 challenge. Complete payment flow to receive data.",
                     }, null, 2),
                 },
             ],

package/package.json

@@ -1,50 +1,51 @@
-{
-  "name": "phoenix-mcp-server",
-  "version": "1.0.0",
-  "description": "MCP server for Phoenix Zero L2 health oracle — kernel-level network telemetry for AI agents",
-  "type": "module",
-  "bin": {
-    "phoenix-mcp-server": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "server.json"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "test": "vitest run",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "l2",
-    "sequencer",
-    "health",
-    "oracle",
-    "ebpf",
-    "x402",
-    "phoenix-zero",
-    "preflight",
-    "defi",
-    "agent"
-  ],
-  "author": "Kent <aleksandrkent64@gmail.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kant19801201behax5/x402-health-oracle"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.11.0",
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.14.0",
-    "tsx": "^4.23.1",
-    "typescript": "~5.8.2",
-    "vitest": "^4.1.10"
-  }
-}
+{
+  "name": "phoenix-mcp-server",
+  "mcpName": "io.github.kant19801201behax5/phoenix-mcp-server",
+  "version": "1.1.0",
+  "description": "MCP server for Phoenix Zero L2 health oracle — kernel-level network telemetry for AI agents",
+  "type": "module",
+  "bin": {
+    "phoenix-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "l2",
+    "sequencer",
+    "health",
+    "oracle",
+    "ebpf",
+    "x402",
+    "phoenix-zero",
+    "preflight",
+    "defi",
+    "agent"
+  ],
+  "author": "Kent <aleksandrkent64@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kant19801201behax5/x402-health-oracle"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "tsx": "^4.23.1",
+    "typescript": "~5.8.2",
+    "vitest": "^4.1.10"
+  }
+}

package/server.json

@@ -1,18 +1,26 @@
-{
-  "name": "phoenix-zero",
-  "display_name": "Phoenix Zero — L2 Health Oracle",
-  "description": "Pre-flight network health check for L2 chains using kernel-level eBPF telemetry. Returns PASS/DEGRADED/FAIL with RTT, packet-loss, and timestamp evidence. Covers 12 L2 networks. Premium data via x402 micropayment ($0.01).",
-  "repository": "https://github.com/kant19801201behax5/x402-health-oracle",
-  "homepage": "https://rtt.phoenix-ai.work",
-  "version": "1.0.0",
-  "tools": [
-    {
-      "name": "preflight_network_health",
-      "description": "Determine whether an L2 network is currently suitable for transaction execution using kernel-level network telemetry. Returns PASS, DEGRADED, or FAIL with RTT, packet-loss and timestamp evidence."
-    }
-  ],
-  "prompts": [],
-  "resources": [],
-  "categories": ["defi", "infrastructure", "security"],
-  "tags": ["l2", "sequencer", "health", "oracle", "ebpf", "x402", "preflight", "agent"]
-}
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.kant19801201behax5/phoenix-mcp-server",
+  "title": "Phoenix Zero — L2 Health Oracle",
+  "description": "Pre-flight L2 health check using kernel-level eBPF telemetry. PASS/DEGRADED/FAIL verdict.",
+  "repository": {
+    "url": "https://github.com/kant19801201behax5/x402-health-oracle",
+    "source": "github"
+  },
+  "version": "1.0.1",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "phoenix-mcp-server",
+      "version": "1.0.1",
+      "transport": { "type": "stdio" }
+    }
+  ],
+  "tools": [
+    {
+      "name": "preflight_network_health",
+      "description": "Determine whether an L2 network is suitable for transaction execution using kernel-level telemetry."
+    }
+  ]
+}