@forgemeshlabs/anomaly-mcp 0.1.1 → 0.2.0

package/README.md

@@ -1,17 +1,15 @@
 # Anomaly Tracker MCP
 
-Blockchain event sequence anomaly detection for MCP clients and x402-powered agents.
+Blockchain event sequence anomaly detection for AI agents. Detects unusual financial event patterns across Ethereum, Base, and Arbitrum using NASA-derived sequence mining. Returns a story label and anomaly score, not just a number.
 
-This MCP server gives AI agents access to the ForgeMesh Anomaly Tracker API, which detects unusual financial event sequences before they look obvious on a chart. Powered by NASA-derived sequence mining methods. Returns a human-readable story label and anomaly score (0-100), not just a number.
+This MCP server gives AI agents access to the ForgeMesh Anomaly Tracker API via 5 tools — chain-wide anomaly scanning, single-token analysis, whale alerts, model health, and API status.
 
-This package is a thin client around the hosted API:
-
-`https://anomaly.forgemesh.io`
-
-Architecture:
+Thin client architecture:
 
 `Agent/MCP client -> this MCP server -> ForgeMesh Anomaly Tracker API`
 
+Hosted API: `https://anomaly.forgemesh.io`
+
 ## Install
 
 ```bash
@@ -44,36 +42,49 @@ npx -y @forgemeshlabs/anomaly-mcp
 
 | Tool | Description | Cost |
 | --- | --- | --- |
-| `get_api_status` | API health check | Free |
-| `get_discovery_metadata` | Fetch llms.txt, openapi.json, or x402.json | Free |
-| `inspect_x402_challenge` | Inspect x402 payment challenge without settling | Free |
-| `detect_sequence_anomaly` | Score a blockchain event window for sequence anomalies | $0.05 USDC |
-| `get_model_status` | SequenceMiner model health and training stats per chain | $0.01 USDC |
+| `health_check` | API health and uptime | Free |
+| `anomaly_scan` | Chain-wide sequence anomaly scan — scores event windows for unusual patterns | $0.05 USDC |
+| `token_scan` | Single-token anomaly scan — scores transfer patterns for one token | $0.03 USDC |
+| `whale_alerts` | Recent whale movements, CEX flows, bridge activity, stablecoin mints/burns | $0.02 USDC |
+| `model_status` | SequenceMiner model health and training stats per chain | $0.01 USDC |
+
+### anomaly_scan
+
+Scan a blockchain for sequence anomalies across all monitored addresses.
+
+- **chain**: `ethereum`, `base`, or `arbitrum` (default: ethereum)
+- **window**: `1h`, `4h`, `24h`, or `168h` (default: 24h)
+
+Returns: `sequence_score` (0-100), `story` (human label), `novelty`, `peak_window`, `possible_failure_modes`
+
+### token_scan
+
+Anomaly scan for a single token's recent transfer patterns.
+
+- **token** (required): Contract address (`0x...`) or symbol — `usdt`, `usdc`, `weth`, `wbtc`, `link`, `uni`, `aave`, `steth`, `pepe`, `dai`, `cbeth`, `arb`
+- **chain**: `ethereum`, `base`, or `arbitrum` (default: ethereum)
+- **window**: `1h`, `4h`, `24h`, or `168h` (default: 24h)
+
+Returns: `sequence_score`, `story`, `novelty`, `peak_window`, `transfers` (recent transfer events with source/direction)
 
-## Anomaly Detection
+### whale_alerts
 
-The `detect_sequence_anomaly` tool accepts:
+Recent whale movements from 12+ monitored addresses: Binance, Coinbase, Kraken, OKX, Bybit, Arbitrum/Optimism/Polygon bridges, Tether Treasury, Circle.
 
-- **domain**: Event domain (`financial` is currently live)
-- **chain**: `ethereum`, `base`, or `arbitrum`
-- **window**: Lookback period: `1h`, `4h`, `24h`, or `168h`
+- **chain**: `ethereum`, `base`, or `arbitrum` (default: ethereum)
+- **hours**: 1-168 (default: 4)
 
-Returns:
-- **sequence_score**: 0 (normal) to 100 (highly anomalous)
-- **story**: Human-readable label like "Supply Expansion", "Exchange Drain", "Normal Activity"
-- **novelty**: `low`, `medium`, `high`, or `extreme`
-- **peak_window**: The most anomalous symbol sequence found
-- **possible_failure_modes**: What could go wrong if this pattern continues
+Returns: `alerts` array with `symbol`, `source`, `amount_eth`/`amount_usd`, `timestamp`
 
 ## Symbol Alphabet
 
-The financial domain tracks 16 event types across whale wallets, exchanges, bridges, and stablecoin issuers:
+The financial domain tracks 16 event types:
 
 `WHALE_BUY`, `WHALE_SELL`, `CEX_INFLOW`, `CEX_OUTFLOW`, `BRIDGE_IN`, `BRIDGE_OUT`, `DEX_SWAP`, `DEX_LIQUIDITY_ADD`, `DEX_LIQUIDITY_REMOVE`, `STABLECOIN_MINT`, `STABLECOIN_REDEEM`, `STABLECOIN_BURN`, `TOKEN_MINT`, `TOKEN_BURN`, `FUNDING_SPIKE`, `LIQUIDATION`
 
 ## Payment
 
-Paid endpoints use x402 protocol. Agents pay per call in USDC on Base mainnet. No API key needed.
+Paid tools use x402 protocol. Agents pay per call in USDC on Base mainnet. No API key needed.
 
 By default, paid endpoints return x402 challenge metadata (pricing, network, wallet) without settling. To settle payments, configure a wallet private key in your agent's x402 client.
 

package/dist/index.js

@@ -5,7 +5,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { callTool, tools } from "./tools.js";
 const server = new Server({
     name: "anomaly-mcp",
-    version: "0.1.1"
+    version: "0.2.0"
 }, {
     capabilities: {
         tools: {}

package/dist/tools.d.ts

@@ -4,11 +4,11 @@ export declare const tools: ({
     inputSchema: {
         type: "object";
         properties: {
-            file?: undefined;
-            endpoint?: undefined;
-            domain?: undefined;
             chain?: undefined;
             window?: undefined;
+            token?: undefined;
+            hours?: undefined;
+            address?: undefined;
         };
         required?: undefined;
     };
@@ -18,17 +18,21 @@ export declare const tools: ({
     inputSchema: {
         type: "object";
         properties: {
-            file: {
+            chain: {
                 type: string;
                 enum: string[];
                 description: string;
             };
-            endpoint?: undefined;
-            domain?: undefined;
-            chain?: undefined;
-            window?: undefined;
+            window: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            token?: undefined;
+            hours?: undefined;
+            address?: undefined;
         };
-        required: string[];
+        required?: undefined;
     };
 } | {
     name: string;
@@ -36,15 +40,22 @@ export declare const tools: ({
     inputSchema: {
         type: "object";
         properties: {
-            endpoint: {
+            token: {
+                type: string;
+                description: string;
+            };
+            chain: {
                 type: string;
                 enum: string[];
                 description: string;
             };
-            file?: undefined;
-            domain?: undefined;
-            chain?: undefined;
-            window?: undefined;
+            window: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            hours?: undefined;
+            address?: undefined;
         };
         required: string[];
     };
@@ -54,11 +65,31 @@ export declare const tools: ({
     inputSchema: {
         type: "object";
         properties: {
-            domain: {
+            chain: {
                 type: string;
                 enum: string[];
                 description: string;
             };
+            hours: {
+                type: string;
+                description: string;
+            };
+            window?: undefined;
+            token?: undefined;
+            address?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            address: {
+                type: string;
+                description: string;
+            };
             chain: {
                 type: string;
                 enum: string[];
@@ -69,10 +100,10 @@ export declare const tools: ({
                 enum: string[];
                 description: string;
             };
-            file?: undefined;
-            endpoint?: undefined;
+            token?: undefined;
+            hours?: undefined;
         };
-        required?: undefined;
+        required: string[];
     };
 })[];
 export declare function callTool(name: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools.js

@@ -1,67 +1,98 @@
 const API_BASE = process.env.ANOMALY_API_BASE || "https://anomaly.forgemesh.io";
 export const tools = [
     {
-        name: "get_api_status",
-        description: "Check ForgeMesh Anomaly Tracker API health.",
+        name: "health_check",
+        description: "Check ForgeMesh Anomaly Tracker API health and uptime.",
         inputSchema: { type: "object", properties: {} }
     },
     {
-        name: "get_discovery_metadata",
-        description: "Fetch agent discovery files: llms.txt, openapi.json, or .well-known/x402.json.",
+        name: "anomaly_scan",
+        description: "Scan a blockchain for sequence anomalies — unusual patterns of whale movements, exchange flows, bridge activity, and stablecoin mints/burns. Returns a story label, anomaly score (0-100), novelty level, and the peak anomalous symbol window. Costs $0.05 USDC on Base mainnet.",
         inputSchema: {
             type: "object",
             properties: {
-                file: {
+                chain: {
+                    type: "string",
+                    enum: ["ethereum", "base", "arbitrum"],
+                    description: "Blockchain to analyze (default: ethereum)"
+                },
+                window: {
                     type: "string",
-                    enum: ["llms.txt", "openapi.json", "x402.json"],
-                    description: "Which discovery file to fetch"
+                    enum: ["1h", "4h", "24h", "168h"],
+                    description: "Lookback window (default: 24h)"
                 }
-            },
-            required: ["file"]
+            }
         }
     },
     {
-        name: "inspect_x402_challenge",
-        description: "Inspect the x402 payment challenge for a paid endpoint without settling. Returns pricing, network, wallet, and Bazaar metadata.",
+        name: "token_scan",
+        description: "Anomaly scan for a single token — scores recent transfer patterns for unusual activity (large CEX flows, whale accumulation, token mints/burns). Pass a contract address or well-known symbol. Costs $0.03 USDC on Base mainnet.",
         inputSchema: {
             type: "object",
             properties: {
-                endpoint: {
+                token: {
+                    type: "string",
+                    description: "Token contract address (0x...) or symbol: usdt, usdc, weth, wbtc, link, uni, aave, steth, pepe, dai, cbeth, arb"
+                },
+                chain: {
+                    type: "string",
+                    enum: ["ethereum", "base", "arbitrum"],
+                    description: "Blockchain to analyze (default: ethereum)"
+                },
+                window: {
                     type: "string",
-                    enum: ["sequence-anomaly", "status"],
-                    description: "Which paid endpoint to inspect"
+                    enum: ["1h", "4h", "24h", "168h"],
+                    description: "Lookback window (default: 24h)"
                 }
             },
-            required: ["endpoint"]
+            required: ["token"]
         }
     },
     {
-        name: "detect_sequence_anomaly",
-        description: "Score a blockchain event window for sequence anomalies. Returns a story label, anomaly score (0-100), novelty level, and the peak anomalous symbol window. Costs $0.05 USDC on Base mainnet.",
+        name: "whale_alerts",
+        description: "Get recent whale movements, CEX inflows/outflows, bridge activity, and stablecoin mints/burns from monitored addresses (Binance, Coinbase, Kraken, OKX, Bybit, major bridges, Tether, Circle). Costs $0.02 USDC on Base mainnet.",
         inputSchema: {
             type: "object",
             properties: {
-                domain: {
+                chain: {
                     type: "string",
-                    enum: ["financial"],
-                    description: "Event domain. Currently only 'financial' is live."
+                    enum: ["ethereum", "base", "arbitrum"],
+                    description: "Blockchain to monitor (default: ethereum)"
+                },
+                hours: {
+                    type: "integer",
+                    description: "Lookback window in hours, 1-168 (default: 4)"
+                }
+            }
+        }
+    },
+    {
+        name: "address_scan",
+        description: "Scan any wallet address for anomalous transaction patterns. Classifies each transaction by checking counterparties against known CEX wallets, bridges, and stablecoin issuers. Costs $0.03 USDC on Base mainnet.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                address: {
+                    type: "string",
+                    description: "Wallet address to scan (0x...)"
                 },
                 chain: {
                     type: "string",
                     enum: ["ethereum", "base", "arbitrum"],
-                    description: "Blockchain to analyze (default: ethereum)"
+                    description: "Blockchain to scan (default: ethereum)"
                 },
                 window: {
                     type: "string",
                     enum: ["1h", "4h", "24h", "168h"],
                     description: "Lookback window (default: 24h)"
                 }
-            }
+            },
+            required: ["address"]
         }
     },
     {
-        name: "get_model_status",
-        description: "Get SequenceMiner model health and training stats per chain. Costs $0.01 USDC on Base mainnet.",
+        name: "model_status",
+        description: "Get SequenceMiner model health and training stats per chain — training sequence count and last retrain time. Costs $0.01 USDC on Base mainnet.",
         inputSchema: {
             type: "object",
             properties: {}
@@ -75,7 +106,7 @@ async function apiGet(path) {
         let decoded = null;
         if (challenge) {
             try {
-                decoded = JSON.parse(Buffer.from(challenge, "base64").toString());
+                decoded = JSON.parse(atob(challenge));
             }
             catch { }
         }
@@ -98,7 +129,7 @@ async function apiPost(path, body) {
         let decoded = null;
         if (challenge) {
             try {
-                decoded = JSON.parse(Buffer.from(challenge, "base64").toString());
+                decoded = JSON.parse(atob(challenge));
             }
             catch { }
         }
@@ -112,41 +143,32 @@ async function apiPost(path, body) {
 }
 export async function callTool(name, args) {
     switch (name) {
-        case "get_api_status":
+        case "health_check":
             return apiGet("/health");
-        case "get_discovery_metadata": {
-            const file = args.file;
-            const pathMap = {
-                "llms.txt": "/llms.txt",
-                "openapi.json": "/openapi.json",
-                "x402.json": "/.well-known/x402.json"
-            };
-            const path = pathMap[file];
-            if (!path)
-                return { error: "Unknown file. Use: llms.txt, openapi.json, or x402.json" };
-            if (file === "llms.txt") {
-                const res = await fetch(`${API_BASE}${path}`);
-                return { content: await res.text() };
-            }
-            return apiGet(path);
-        }
-        case "inspect_x402_challenge": {
-            const ep = args.endpoint;
-            if (ep === "sequence-anomaly") {
-                return apiPost("/api/sequence-anomaly", { domain: "financial", chain: "ethereum", window: "24h" });
-            }
-            if (ep === "status") {
-                return apiGet("/api/sequence-anomaly/status");
-            }
-            return { error: "Unknown endpoint. Use: sequence-anomaly or status" };
-        }
-        case "detect_sequence_anomaly":
+        case "anomaly_scan":
             return apiPost("/api/sequence-anomaly", {
-                domain: args.domain || "financial",
+                domain: "financial",
+                chain: args.chain || "ethereum",
+                window: args.window || "24h"
+            });
+        case "token_scan":
+            return apiPost("/api/token-scan", {
+                token: args.token,
+                chain: args.chain || "ethereum",
+                window: args.window || "24h"
+            });
+        case "whale_alerts": {
+            const chain = args.chain || "ethereum";
+            const hours = args.hours || 4;
+            return apiGet(`/api/whale-alerts?chain=${chain}&hours=${hours}`);
+        }
+        case "address_scan":
+            return apiPost("/api/address-scan", {
+                address: args.address,
                 chain: args.chain || "ethereum",
                 window: args.window || "24h"
             });
-        case "get_model_status":
+        case "model_status":
             return apiGet("/api/sequence-anomaly/status");
         default:
             return { error: `Unknown tool: ${name}` };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgemeshlabs/anomaly-mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "mcpName": "io.github.forgemeshlabs/anomaly-mcp",
   "description": "Blockchain event sequence anomaly detection MCP server. Detects unusual financial event patterns via x402 micropayments.",
   "type": "module",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/forgemeshlabs/anomaly-mcp",
     "source": "github"
   },
-  "version": "0.1.1",
+  "version": "0.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@forgemeshlabs/anomaly-mcp",
-      "version": "0.1.1",
+      "version": "0.2.0",
       "transport": {
         "type": "stdio"
       },