@forgemeshlabs/anomaly-mcp 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeMesh Labs
+
+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

@@ -0,0 +1,95 @@
+# Anomaly Tracker MCP
+
+Blockchain event sequence anomaly detection for MCP clients and x402-powered agents.
+
+This MCP server gives AI agents access to the ForgeMesh Anomaly Tracker API, which converts blockchain event streams into symbol sequences and scores them for anomalies using NASA ARC-16053-1 SequenceMiner. Returns a human-readable story label and anomaly score (0-100), not just a number.
+
+This package is a thin client around the hosted API:
+
+`https://anomaly.forgemesh.io`
+
+Architecture:
+
+`Agent/MCP client -> this MCP server -> ForgeMesh Anomaly Tracker API`
+
+## Install
+
+```bash
+npm install -g @forgemeshlabs/anomaly-mcp
+```
+
+Or run directly:
+
+```bash
+npx -y @forgemeshlabs/anomaly-mcp
+```
+
+## Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "anomaly-tracker": {
+      "command": "npx",
+      "args": ["-y", "@forgemeshlabs/anomaly-mcp"],
+      "env": {
+        "ANOMALY_API_BASE": "https://anomaly.forgemesh.io"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| 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 |
+
+## Anomaly Detection
+
+The `detect_sequence_anomaly` tool accepts:
+
+- **domain**: Event domain (`financial` is currently live)
+- **chain**: `ethereum`, `base`, or `arbitrum`
+- **window**: Lookback period: `1h`, `4h`, `24h`, or `168h`
+
+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
+
+## Symbol Alphabet
+
+The financial domain tracks 16 event types across whale wallets, exchanges, bridges, and stablecoin issuers:
+
+`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.
+
+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.
+
+## Environment Variables
+
+| Variable | Description | Default |
+| --- | --- | --- |
+| `ANOMALY_API_BASE` | Hosted API base URL | `https://anomaly.forgemesh.io` |
+
+## Links
+
+- Hosted API: https://anomaly.forgemesh.io
+- ForgeMesh: https://forgemesh.io
+- npm: https://www.npmjs.com/package/@forgemeshlabs/anomaly-mcp
+- GitHub: https://github.com/forgemeshlabs/anomaly-mcp
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+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 { callTool, tools } from "./tools.js";
+const server = new Server({
+    name: "anomaly-mcp",
+    version: "0.1.0"
+}, {
+    capabilities: {
+        tools: {}
+    }
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const result = await callTool(request.params.name, isObject(request.params.arguments) ? request.params.arguments : {});
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/tools.d.ts

@@ -0,0 +1,78 @@
+export declare const tools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            file?: undefined;
+            endpoint?: undefined;
+            domain?: undefined;
+            chain?: undefined;
+            window?: undefined;
+        };
+        required?: undefined;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            file: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            endpoint?: undefined;
+            domain?: undefined;
+            chain?: undefined;
+            window?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            endpoint: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            file?: undefined;
+            domain?: undefined;
+            chain?: undefined;
+            window?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            domain: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            chain: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            window: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            file?: undefined;
+            endpoint?: undefined;
+        };
+        required?: undefined;
+    };
+})[];
+export declare function callTool(name: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools.js

@@ -0,0 +1,154 @@
+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.",
+        inputSchema: { type: "object", properties: {} }
+    },
+    {
+        name: "get_discovery_metadata",
+        description: "Fetch agent discovery files: llms.txt, openapi.json, or .well-known/x402.json.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: {
+                    type: "string",
+                    enum: ["llms.txt", "openapi.json", "x402.json"],
+                    description: "Which discovery file to fetch"
+                }
+            },
+            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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                endpoint: {
+                    type: "string",
+                    enum: ["sequence-anomaly", "status"],
+                    description: "Which paid endpoint to inspect"
+                }
+            },
+            required: ["endpoint"]
+        }
+    },
+    {
+        name: "detect_sequence_anomaly",
+        description: "Score a blockchain event window for sequence anomalies using NASA ARC-16053-1 SequenceMiner. 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: {
+                domain: {
+                    type: "string",
+                    enum: ["financial"],
+                    description: "Event domain. Currently only 'financial' is live."
+                },
+                chain: {
+                    type: "string",
+                    enum: ["ethereum", "base", "arbitrum"],
+                    description: "Blockchain to analyze (default: ethereum)"
+                },
+                window: {
+                    type: "string",
+                    enum: ["1h", "4h", "24h", "168h"],
+                    description: "Lookback window (default: 24h)"
+                }
+            }
+        }
+    },
+    {
+        name: "get_model_status",
+        description: "Get SequenceMiner model health and training stats per chain. Costs $0.01 USDC on Base mainnet.",
+        inputSchema: {
+            type: "object",
+            properties: {}
+        }
+    }
+];
+async function apiGet(path) {
+    const res = await fetch(`${API_BASE}${path}`);
+    if (res.status === 402) {
+        const challenge = res.headers.get("payment-required");
+        let decoded = null;
+        if (challenge) {
+            try {
+                decoded = JSON.parse(Buffer.from(challenge, "base64").toString());
+            }
+            catch { }
+        }
+        return {
+            x402_status: 402,
+            message: "Payment required — this endpoint costs USDC on Base mainnet via x402 protocol.",
+            challenge: decoded
+        };
+    }
+    return res.json();
+}
+async function apiPost(path, body) {
+    const res = await fetch(`${API_BASE}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body)
+    });
+    if (res.status === 402) {
+        const challenge = res.headers.get("payment-required");
+        let decoded = null;
+        if (challenge) {
+            try {
+                decoded = JSON.parse(Buffer.from(challenge, "base64").toString());
+            }
+            catch { }
+        }
+        return {
+            x402_status: 402,
+            message: "Payment required — this endpoint costs USDC on Base mainnet via x402 protocol.",
+            challenge: decoded
+        };
+    }
+    return res.json();
+}
+export async function callTool(name, args) {
+    switch (name) {
+        case "get_api_status":
+            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":
+            return apiPost("/api/sequence-anomaly", {
+                domain: args.domain || "financial",
+                chain: args.chain || "ethereum",
+                window: args.window || "24h"
+            });
+        case "get_model_status":
+            return apiGet("/api/sequence-anomaly/status");
+        default:
+            return { error: `Unknown tool: ${name}` };
+    }
+}

package/examples/claude-desktop-config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "anomaly-tracker": {
+      "command": "npx",
+      "args": ["-y", "@forgemeshlabs/anomaly-mcp"],
+      "env": {
+        "ANOMALY_API_BASE": "https://anomaly.forgemesh.io"
+      }
+    }
+  }
+}

package/glama.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": [
+    "clawdbotworker"
+  ]
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@forgemeshlabs/anomaly-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.forgemeshlabs/anomaly-mcp",
+  "description": "Blockchain event sequence anomaly detection MCP server. Scores event streams using NASA ARC-16053-1 SequenceMiner via x402 micropayments.",
+  "type": "module",
+  "bin": {
+    "anomaly-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md",
+    "glama.json",
+    "server.json",
+    "smithery.yaml",
+    "docs",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "agent-payments",
+    "anomaly-detection",
+    "sequence-mining",
+    "blockchain",
+    "ethereum",
+    "base",
+    "arbitrum",
+    "forgemesh",
+    "usdc",
+    "nasa",
+    "sequenceminer"
+  ],
+  "author": "forgemeshlabs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgemeshlabs/anomaly-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/forgemeshlabs/anomaly-mcp/issues"
+  },
+  "homepage": "https://github.com/forgemeshlabs/anomaly-mcp#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  }
+}

package/server.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.forgemeshlabs/anomaly-mcp",
+  "description": "Blockchain event sequence anomaly detection using NASA ARC-16053-1 SequenceMiner. Scores event streams and returns story labels via x402 micropayments.",
+  "repository": {
+    "url": "https://github.com/forgemeshlabs/anomaly-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@forgemeshlabs/anomaly-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "ANOMALY_API_BASE",
+          "description": "Optional hosted API base URL override. Defaults to https://anomaly.forgemesh.io.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}

package/smithery.yaml

@@ -0,0 +1,18 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      apiBase:
+        type: string
+        description: Optional hosted API base URL override. Defaults to https://anomaly.forgemesh.io.
+  commandFunction: |-
+    (config) => ({
+      command: 'npx',
+      args: ['-y', '@forgemeshlabs/anomaly-mcp'],
+      env: {
+        ANOMALY_API_BASE: config.apiBase || 'https://anomaly.forgemesh.io'
+      }
+    })
+  exampleConfig:
+    apiBase: 'https://anomaly.forgemesh.io'