m2m-sentinel-sdk 1.2.3 → 1.2.7

package/mcp_server.js

@@ -5,75 +5,131 @@ const https = require('https');
 const http = require('http');
 const readline = require('readline');
 
+const pkg = require('./package.json');
+
 let BASE_URL = process.env.M2M_SENTINEL_BASE_URL || 'https://api.m2msentinel.com';
 let API_KEY = process.env.M2M_SENTINEL_API_KEY || '';
 const TIMEOUT_MS = Number(process.env.M2M_SENTINEL_TIMEOUT_MS || 30000);
-const VERSION = '1.2.3';
+const VERSION = pkg.version;
+
+const SERVER_INSTRUCTIONS =
+  'M2M Sentinel MCP server provides factual, read-only observations on Base Mainnet (chainId 8453).\n\n' +
+  '• Canonical Tools: The six m2m_* tool names (m2m_audit_contract, m2m_get_gas_metrics, m2m_get_token_price, m2m_get_dex_liquidity, m2m_get_whale_signals, m2m_get_service_status) are canonical.\n' +
+  '• Backwards Compatibility: Legacy tool names (audit_contract, get_capability_score, get_gas_fees, get_dex_metrics, get_token_price, get_whale_signals) are not advertised in tools/list but remain compatibility-callable.\n' +
+  '• Upstream Behavior: m2m_get_dex_liquidity returns aggregate tracked pool liquidity metrics without pair query filtering; m2m_get_whale_signals returns recent high-value transfer events (up to 50) without query limit filtering.\n' +
+  '• Access and Errors: The stdio wrapper reads M2M_SENTINEL_API_KEY when set. Protected upstream calls may return structured 401, 402, 429, or 503 responses; x402 payment metadata is surfaced, but this wrapper does not sign payments.\n' +
+  '• Observational Scope: All operations are factual, read-only observations. The server does not custody private keys, sign transactions, or execute on-chain state changes.\n' +
+  '• Limitation: Outputs reflect observed bytecode patterns and telemetry and are not safety, economic, or exploitability guarantees.';
 
 const TOOLS = [
   {
     name: 'm2m_audit_contract',
-    description: 'Return selected static bytecode capability observations, common proxy resolution, limitations, and provenance for a Base contract. This is factual capability observation, not a safety or exploitability guarantee.',
-    inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'Base contract address (0x...)' } }, required: ['address'] }
+    description: 'Inspect static bytecode capabilities (e.g. mint, pause, freeze, upgradeability slots), common proxy target resolution, and coverage index for a single Base contract address. Factual capability observation only, not a safety or exploitability guarantee. Distinguishable from m2m_get_service_status (infrastructure status) and legacy score-only endpoints.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        address: {
+          type: 'string',
+          description: 'Base contract address (0x-prefixed 40-hex string, chainId 8453) to inspect.'
+        }
+      },
+      required: ['address']
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_gas_metrics',
-    description: 'Return sourced Base gas fee metrics and execution recommendations.',
-    inputSchema: { type: 'object', properties: {} }
+    description: 'Fetch current Base gas price in wei/gwei with RPC provenance for the upstream observation. Read-only telemetry; does not inspect contract code, return token/DEX pricing, or authorize or submit transactions.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_token_price',
-    description: 'Return sourced Base DEX token price observation for allowlisted assets (e.g. USDC, WETH).',
-    inputSchema: { type: 'object', properties: { symbol: { type: 'string', description: 'Token symbol (USDC, WETH)' } }, required: ['symbol'] }
+    description: 'Fetch the median Base DEX spot price in USD across up to five deepest indexed pools, with contract address, decimals, and pool provenance for one allowlisted token symbol (e.g. USDC, WETH, AERO). Does not return historical price series; contrast with m2m_get_dex_liquidity, which returns aggregate pool reserve depth rather than an asset price.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        symbol: {
+          type: 'string',
+          description: 'Allowlisted token symbol on Base (e.g. USDC, WETH, AERO). Lookups are case-insensitive single symbols.'
+        }
+      },
+      required: ['symbol']
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_dex_liquidity',
-    description: 'Return tracked Base DEX pool reserve and liquidity metrics.',
-    inputSchema: { type: 'object', properties: { pair: { type: 'string' } } }
+    description: 'Fetch aggregate pool reserve, depth, and volume metrics across tracked Base DEX liquidity pools. Reports tracked-pool metrics only and does not filter by individual trading pair; contrast with m2m_get_token_price, which observes token spot prices.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_whale_signals',
-    description: 'Return tracked Base whale transfer signals.',
-    inputSchema: { type: 'object', properties: { limit: { type: 'number' } } }
+    description: 'Fetch up to 50 tracked recent high-value ERC-20 transfer signals on Base with transaction hashes, token/sender/receiver addresses, amounts, and valuation provenance. Observes large on-chain transfer events without query parameter limits; does not inspect contract bytecode or query DEX pricing.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   },
   {
     name: 'm2m_get_service_status',
-    description: 'Return real-time operational status of M2M Sentinel upstream RPC and persistence rails.',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  // Backwards compatibility aliases
-  {
-    name: 'audit_contract',
-    description: 'Alias for m2m_audit_contract.',
-    inputSchema: { type: 'object', properties: { address: { type: 'string' } }, required: ['address'] }
-  },
-  {
-    name: 'get_capability_score',
-    description: 'Return the static capability coverage index and provenance for a Base contract. This is not a safety score.',
-    inputSchema: { type: 'object', properties: { address: { type: 'string' } }, required: ['address'] }
-  },
-  {
-    name: 'get_gas_fees',
-    description: 'Alias for m2m_get_gas_metrics.',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'get_dex_metrics',
-    description: 'Alias for m2m_get_dex_liquidity.',
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'get_token_price',
-    description: 'Alias for m2m_get_token_price.',
-    inputSchema: { type: 'object', properties: { symbol: { type: 'string' } }, required: ['symbol'] }
-  },
-  {
-    name: 'get_whale_signals',
-    description: 'Alias for m2m_get_whale_signals.',
-    inputSchema: { type: 'object', properties: {} }
+    description: 'Fetch operational status, upstream Base RPC quorum status, and persistence availability for M2M Sentinel infrastructure. Does not return blockchain or market telemetry.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
   }
 ];
 
+// Backwards compatibility alias lookup
+const TOOL_ALIASES = Object.freeze({
+  audit_contract: 'm2m_audit_contract',
+  get_capability_score: 'm2m_audit_contract',
+  get_gas_fees: 'm2m_get_gas_metrics',
+  get_dex_metrics: 'm2m_get_dex_liquidity',
+  get_token_price: 'm2m_get_token_price',
+  get_whale_signals: 'm2m_get_whale_signals'
+});
+
 function parseX402Header(value) {
   if (!value) return null;
   try { return JSON.parse(value); } catch (_) {}
@@ -87,8 +143,8 @@ function parseX402Header(value) {
 }
 
 function queryApi(path, customApiKey = null, customBaseUrl = null) {
-  const activeBaseUrl = customBaseUrl || BASE_URL;
-  const activeApiKey = customApiKey !== null ? customApiKey : API_KEY;
+  const activeBaseUrl = customBaseUrl || process.env.M2M_SENTINEL_BASE_URL || BASE_URL;
+  const activeApiKey = customApiKey !== null ? customApiKey : (process.env.M2M_SENTINEL_API_KEY || API_KEY);
 
   return new Promise((resolve, reject) => {
     const url = new URL(path, activeBaseUrl);
@@ -129,12 +185,22 @@ function pathForTool(name, args) {
   const input = args || {};
   switch (name) {
     case 'm2m_audit_contract':
-    case 'audit_contract':
-      if (!input.address) throw new Error('address is required');
-      return '/v1/audit/' + encodeURIComponent(input.address);
-    case 'get_capability_score':
-      if (!input.address) throw new Error('address is required');
-      return '/v1/security/score/' + encodeURIComponent(input.address);
+    case 'audit_contract': {
+      const addr = input.address ? String(input.address).trim() : '';
+      if (!addr) throw new Error('address is required');
+      if (!/^0x[0-9a-fA-F]{40}$/.test(addr)) {
+        throw new Error('A valid 40-hex 0x-prefixed Base contract address is required');
+      }
+      return '/v1/audit/' + encodeURIComponent(addr);
+    }
+    case 'get_capability_score': {
+      const addr = input.address ? String(input.address).trim() : '';
+      if (!addr) throw new Error('address is required');
+      if (!/^0x[0-9a-fA-F]{40}$/.test(addr)) {
+        throw new Error('A valid 40-hex 0x-prefixed Base contract address is required');
+      }
+      return '/v1/security/score/' + encodeURIComponent(addr);
+    }
     case 'm2m_get_gas_metrics':
     case 'get_gas_fees':
       return '/v1/gas/fees';
@@ -142,9 +208,11 @@ function pathForTool(name, args) {
     case 'get_dex_metrics':
       return '/v1/dex/metrics';
     case 'm2m_get_token_price':
-    case 'get_token_price':
-      if (!input.symbol) throw new Error('symbol is required');
-      return '/v1/token/price/' + encodeURIComponent(input.symbol);
+    case 'get_token_price': {
+      const sym = input.symbol ? String(input.symbol).trim().toUpperCase() : '';
+      if (!sym) throw new Error('symbol is required');
+      return '/v1/token/price/' + encodeURIComponent(sym);
+    }
     case 'm2m_get_whale_signals':
     case 'get_whale_signals':
       return '/v1/whales/signals';
@@ -173,24 +241,32 @@ function failure(id, code, message, data) {
   send({ jsonrpc: '2.0', id, error });
 }
 
-async function handleMcpMessage(request) {
+async function handleMcpMessage(request, responder = null) {
+  const replySuccess = responder ? (id, res) => responder({ jsonrpc: '2.0', id, result: res }) : success;
+  const replyFailure = responder ? (id, code, msg, data) => {
+    const error = { code, message: msg };
+    if (data !== undefined) error.data = data;
+    responder({ jsonrpc: '2.0', id, error });
+  } : failure;
+
   if (!request || request.jsonrpc !== '2.0' || typeof request.method !== 'string') {
-    failure(request && request.id !== undefined ? request.id : null, -32600, 'Invalid Request');
+    replyFailure(request && request.id !== undefined ? request.id : null, -32600, 'Invalid Request');
     return;
   }
   if (request.id === undefined || request.id === null) return;
 
   try {
     if (request.method === 'initialize') {
-      success(request.id, {
+      replySuccess(request.id, {
         protocolVersion: request.params && request.params.protocolVersion ? request.params.protocolVersion : '2024-11-05',
         capabilities: { tools: {} },
-        serverInfo: { name: 'm2m-sentinel-mcp', version: VERSION }
+        serverInfo: { name: 'm2m-sentinel-mcp', version: VERSION },
+        instructions: SERVER_INSTRUCTIONS
       });
       return;
     }
     if (request.method === 'tools/list') {
-      success(request.id, { tools: TOOLS });
+      replySuccess(request.id, { tools: TOOLS });
       return;
     }
     if (request.method === 'tools/call') {
@@ -198,7 +274,7 @@ async function handleMcpMessage(request) {
       const path = pathForTool(params.name, params.arguments || {});
       const apiResult = await queryApi(path);
       const isError = !apiResult.ok;
-      success(request.id, {
+      replySuccess(request.id, {
         content: [{ type: 'text', text: typeof apiResult.body === 'object' ? JSON.stringify(apiResult.body, null, 2) : String(apiResult.body) }],
         isError,
         structuredContent: apiResult.body,
@@ -212,9 +288,9 @@ async function handleMcpMessage(request) {
       });
       return;
     }
-    failure(request.id, -32601, 'Method not found');
+    replyFailure(request.id, -32601, 'Method not found');
   } catch (err) {
-    failure(request.id, -32603, err && err.message ? err.message : 'Internal error');
+    replyFailure(request.id, -32603, err && err.message ? err.message : 'Internal error');
   }
 }
 
@@ -250,10 +326,10 @@ USAGE:
 
 COMMANDS:
   audit <address>        Disassemble bytecode, detect capabilities & resolve proxies
-  gas                    Fetch real-time Base Mainnet gas metrics & advice
-  price <symbol>         Fetch DEX liquidity-weighted token price (USDC, WETH, AERO)
-  dex [pair]             Fetch tracked Base liquidity pool metrics
-  whales [limit]         Fetch large ERC-20 transfer signals on Base
+  gas                    Fetch current Base Mainnet gas-price telemetry
+  price <symbol>         Fetch median Base DEX token price from deepest pools (USDC, WETH, AERO)
+  dex                    Fetch aggregate tracked Base liquidity pool metrics
+  whales                 Fetch large ERC-20 transfer signals on Base (up to 50)
   status                 Check live API, RPC quorum, and persistence health
   mcp                    Launch Model Context Protocol stdio JSON-RPC server
 
@@ -419,13 +495,16 @@ async function runCli(args) {
 
     } else if (commandName === 'gas' || commandName === 'fees') {
       console.log('================================================================');
-      console.log('⛽ M2M SENTINEL — BASE GAS METRICS');
+      console.log('⛽ M2M SENTINEL — BASE GAS PRICE TELEMETRY');
       console.log(`Network: Base Mainnet (8453) | Sourced Latency: ${res.latencyMs}ms`);
       console.log('================================================================');
-      console.log(`• Standard Gas Price: ${data.standard || data.gasPriceGwei || '0.005'} gwei`);
-      if (data.fast) console.log(`• Fast Gas Price:     ${data.fast} gwei`);
-      if (data.instant) console.log(`• Instant Gas Price:  ${data.instant} gwei`);
-      if (data.recommendation) console.log(`• Execution Advice:   ${data.recommendation}`);
+      const gasPrice = data && data.gasPrice && typeof data.gasPrice === 'object' ? data.gasPrice : data;
+      const gwei = gasPrice && gasPrice.gwei !== undefined
+        ? gasPrice.gwei
+        : (data && data.gasPriceGwei !== undefined ? data.gasPriceGwei : (data && data.standard));
+      if (gwei !== undefined) console.log(`• Gas Price:          ${gwei} gwei`);
+      if (gasPrice && gasPrice.wei !== undefined) console.log(`• Gas Price:          ${gasPrice.wei} wei`);
+      if (data && data.provenance) console.log(`• RPC Provenance:     ${JSON.stringify(data.provenance)}`);
       console.log('================================================================\n');
 
     } else if (commandName === 'price') {
@@ -473,20 +552,33 @@ async function runCli(args) {
 // Entrypoint: Dual Mode Selection
 // ---------------------------------------------------------------------------
 
-const cliArgs = process.argv.slice(2);
+if (require.main === module) {
+  const cliArgs = process.argv.slice(2);
 
-// If arguments are passed or run in an interactive terminal, invoke CLI
-if (cliArgs.length > 0 || (process.stdin.isTTY && !process.env.M2M_MCP_FORCE)) {
-  if (cliArgs.length === 0) {
-    printHelp();
+  // If arguments are passed or run in an interactive terminal, invoke CLI
+  if (cliArgs.length > 0 || (process.stdin.isTTY && !process.env.M2M_MCP_FORCE)) {
+    if (cliArgs.length === 0) {
+      printHelp();
+    } else {
+      runCli(cliArgs).then((code) => {
+        if (code !== 0 && typeof code === 'number') process.exit(code);
+      });
+    }
   } else {
-    runCli(cliArgs).then((code) => {
-      if (code !== 0 && typeof code === 'number') process.exit(code);
-    });
+    // Piped execution without args -> start MCP stdio server
+    startMcpServer();
   }
-} else {
-  // Piped execution without args -> start MCP stdio server
-  startMcpServer();
 }
 
-module.exports = { TOOLS, pathForTool, parseX402Header, runCli, queryApi };
+module.exports = {
+  TOOLS,
+  TOOL_ALIASES,
+  SERVER_INSTRUCTIONS,
+  pathForTool,
+  parseX402Header,
+  runCli,
+  queryApi,
+  handleMcpMessage,
+  startMcpServer,
+  VERSION
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "m2m-sentinel-sdk",
-  "version": "1.2.3",
+  "version": "1.2.7",
   "mcpName": "io.github.M2M-Sentinel/m2m-sentinel-sdk",
   "publishConfig": {
     "access": "public"
@@ -8,11 +8,17 @@
   "description": "JavaScript client for M2M Sentinel Base bytecode capability, proxy and market observations",
   "main": "index.js",
   "types": "index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
   "bin": {
     "m2m-sentinel-mcp": "./mcp_server.js",
     "m2m-sentinel": "./mcp_server.js",
     "m2msentinel": "./mcp_server.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "license": "MIT",
   "homepage": "https://m2msentinel.com",
   "repository": {
@@ -37,19 +43,29 @@
     "glama",
     "agentkit",
     "coinbase",
-    "smart-contract-audit"
+    "smart-contract-audit",
+    "paymaster",
+    "wallet-send-calls",
+    "sponsored-transaction"
   ],
   "author": "M2M Sentinel",
   "files": [
     "index.js",
     "index.d.ts",
+    "base_account_paymaster_guard.js",
     "m2m_sentinel_sdk.js",
     "agent_adapter.js",
     "x402_signer.js",
     "eliza_plugin.js",
+    "langchain_tool.js",
     "mcp_server.js",
     "smithery.yaml",
     "README.md",
-    "typescript/"
+    "typescript/index.ts",
+    "typescript/x402.ts",
+    "typescript/base_account_paymaster_guard.ts",
+    "typescript/package.json",
+    "typescript/package-lock.json",
+    "typescript/tsconfig.json"
   ]
 }

package/smithery.yaml

@@ -13,7 +13,7 @@ startCommand:
       M2M_SENTINEL_API_KEY:
         type: string
         title: M2M Sentinel API Key
-        description: Optional API key for higher rate limits. Public free tier works without key.
+        description: Optional API key for prepaid access. Protected calls may return structured 401, 402, 429, or 503 responses without authorized access.
         default: ""
 
 configSchema:
@@ -22,6 +22,6 @@ configSchema:
     M2M_SENTINEL_API_KEY:
       type: string
       title: M2M Sentinel API Key
-      description: Optional API key for higher rate limits. Public free tier works without key.
+      description: Optional API key for prepaid access. Protected calls may return structured 401, 402, 429, or 503 responses without authorized access.
       default: ""