m2m-sentinel-sdk 1.1.0 → 1.1.1

package/LICENSE

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

@@ -1,71 +1,61 @@
-# M2M Sentinel SDKs
-
-Base URL: `https://m2msentinel.vercel.app`.
-
-M2M Sentinel reports selected static bytecode capabilities, common proxy
-structures, evidence quality, and sourced Base market observations. It does not
-classify a contract as safe, malicious, or exploitable. Transaction middleware
-therefore requires a caller-defined policy and has no built-in allow threshold.
-
-## Support status
-
-Supported here: JavaScript/Node (`index.js`), TypeScript source, Python source,
-and the MCP stdio server. Other language folders are community previews and
-must be checked against `/openapi.json` before production use.
-
-## Install this source build
-
-```bash
-node -e "const { M2MSentinelClient } = require('./public/sdk')"
-python -m pip install ./public/sdk/python
-```
-
-Registry publishing is intentionally separate from the production API.
-The repository does not claim that these source-installable packages are available from every language registry.
-
-## Authentication and x402
-
-Send API keys only in `x-api-key` (or `Authorization: Bearer`). Query-string
-credentials are rejected. Payable routes also support x402 v2. An unpaid call
-returns a base64 `PAYMENT-REQUIRED` challenge when the facilitator is ready; a
-successful settlement returns `PAYMENT-RESPONSE`.
-
-## Public routes
-
-- `GET /v1/status`
-- `GET /v1/stats` (public counter-free privacy envelope; exact aggregate
-  commercial counters are operator-only)
-- `GET /v1/plans`
-- `GET /v1/demo/audit/:address` for the published sample allowlist
-- free-key and subscription onboarding routes
-
-The JavaScript, TypeScript, and Python clients expose multi-period
-purchase/renewal and wallet recovery without requiring callers to hand-build
-requests:
-
-```js
-await client.createSubscriptionIntent('GROWTH', wallet, {
-  durationDays: 90,
-  renewExistingKey: true,
-  apiKey: existingPaidKey
-});
-const challenge = await client.createRecoveryChallenge(wallet, { txHash });
-await client.claimRecoveredKey(challenge.intent.id, walletSignature);
-```
-
-`getPublicStats()` returns the counter-free privacy envelope. Operator-only
-detail has a deliberately separate `getOperatorAggregateStats(days, token)`
-method and sends the operator token only as `Authorization: Bearer`. This is
-for private server/operator tooling only: never embed or bundle the operator
-token in browser, mobile, SDK-distribution, or customer code.
-
-## Protected routes
-
-- `GET /v1/audit/:address`
-- `GET /v1/security/score/:address` (legacy URL; returns a capability coverage index)
-- Base gas, DEX, token-price, and large-transfer observation routes
-- key self-service routes
-
-All live-data responses preserve provenance. Capability responses include
-`notASafetyGuarantee: true`, a limitations array, `capabilityRating`, and an
-evidence-grade flag. Do not replace `UNVERIFIED` or `null` with a default.
+# M2M Sentinel SDK
+
+Official multi-language client libraries for M2M Sentinel — the pre-transaction capability evidence layer for Base agents.
+
+[![npm version](https://img.shields.io/npm/v/m2m-sentinel-sdk.svg)](https://www.npmjs.com/package/m2m-sentinel-sdk)
+[![PyPI version](https://img.shields.io/pypi/v/m2m-sentinel.svg)](https://pypi.org/project/m2m-sentinel/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+M2M Sentinel provides proxy-aware contract capability observations, implementation slot resolution, gas metrics, DEX liquidity telemetry, and whale signals for autonomous agents operating on Base.
+
+## Installation
+
+### JavaScript / TypeScript (Node.js)
+```bash
+npm install m2m-sentinel-sdk
+```
+
+### Python
+```bash
+pip install m2m-sentinel
+```
+
+## Quick Start
+
+### Node.js / TypeScript
+```javascript
+const { M2MSentinelClient } = require('m2m-sentinel-sdk');
+
+const client = new M2MSentinelClient({
+  apiKey: process.env.M2M_SENTINEL_API_KEY
+});
+
+async function main() {
+  const audit = await client.auditContract('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913');
+  console.log('Contract Type:', audit.data.bytecodeAnalysis.contractType);
+  console.log('Proxy Detected:', audit.data.proxyDetection.isProxy);
+  console.log('Capabilities:', audit.data.bytecodeAnalysis.detectedCapabilities);
+}
+
+main().catch(console.error);
+```
+
+### Python
+```python
+from m2m_sentinel import M2MSentinelClient
+
+client = M2MSentinelClient(api_key="your_api_key")
+audit = client.audit_contract("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
+print("Contract Type:", audit["data"]["bytecodeAnalysis"]["contractType"])
+```
+
+## Model Context Protocol (MCP) Server
+
+M2M Sentinel includes a full Model Context Protocol (MCP) server supporting stdio and HTTP/SSE streams.
+
+```bash
+node mcp_server.js
+```
+
+## License
+MIT License. Copyright (c) 2026 M2M Sentinel.

package/agent_adapter.js

@@ -1,30 +1,202 @@
-// UNSUPPORTED / COMMUNITY PREVIEW — not covered by the supported-SDK guarantee; verify against /openapi.json before production use.
+'use strict';
 
-const { M2MSentinelClient } = require('./index.js');
+/**
+ * Coinbase AgentKit Action Provider for M2M Sentinel.
+ *
+ * Exposes pre-transaction contract bytecode capability inspection, proxy resolution,
+ * and market observations to autonomous Base agents using @coinbase/agentkit.
+ */
 
-class M2MSentinelAgentTool {
+const https = require('https');
+const http = require('http');
+
+const DEFAULT_BASE_URL = process.env.M2M_SENTINEL_BASE_URL || 'https://api.m2msentinel.com';
+const DEFAULT_TIMEOUT_MS = Number(process.env.M2M_SENTINEL_TIMEOUT_MS || 30000);
+
+class M2MSentinelActionProvider {
   constructor(options = {}) {
-    this.name = 'm2m_sentinel_capability_analysis';
-    this.description = 'Reports selected static bytecode capabilities, common proxy structures, provenance, and limitations for Base contracts.';
-    this.client = new M2MSentinelClient({
-      apiKey: options.apiKey || process.env.M2M_SENTINEL_API_KEY,
-      baseUrl: options.baseUrl
+    this.name = 'm2m_sentinel';
+    this.actionProviderName = 'm2m_sentinel';
+    this.baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+    this.apiKey = options.apiKey || process.env.M2M_SENTINEL_API_KEY || '';
+    this.timeoutMs = Number(options.timeoutMs || DEFAULT_TIMEOUT_MS);
+  }
+
+  supportsNetwork(network) {
+    if (!network) return true;
+    const chainId = String(network.chainId || network.networkId || '');
+    const protocolFamily = String(network.protocolFamily || 'evm').toLowerCase();
+    return protocolFamily === 'evm' && (
+      chainId === '8453' ||
+      chainId === 'base' ||
+      chainId === 'base-mainnet' ||
+      chainId === 'base-sepolia' ||
+      chainId === '84532'
+    );
+  }
+
+  async _queryApi(endpointPath, options = {}) {
+    const url = new URL(endpointPath, this.baseUrl);
+    const isHttps = url.protocol === 'https:';
+    const transport = isHttps ? https : http;
+
+    const headers = {
+      Accept: 'application/json',
+      'User-Agent': 'M2MSentinel-AgentKit/1.1.1',
+      ...options.headers
+    };
+    if (this.apiKey && !headers['x-api-key']) {
+      headers['x-api-key'] = this.apiKey;
+    }
+
+    return new Promise((resolve, reject) => {
+      const req = transport.request(url, {
+        method: 'GET',
+        headers,
+        timeout: this.timeoutMs
+      }, (res) => {
+        let data = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          let body = null;
+          if (data) {
+            try { body = JSON.parse(data); } catch (_) { body = { raw: data }; }
+          }
+          resolve({
+            statusCode: res.statusCode,
+            ok: res.statusCode >= 200 && res.statusCode < 300,
+            body
+          });
+        });
+      });
+
+      req.on('timeout', () => req.destroy(new Error('M2M Sentinel request timed out')));
+      req.on('error', reject);
+      req.end();
     });
   }
 
-  async _call(address) {
-    try {
-      return await this.client.auditContract(address);
-    } catch (err) {
-      return {
-        error: err.name || 'M2MSentinelError',
-        message: err.message,
-        status: err.status,
-        paymentRequired: err.paymentRequired || null,
-        retryAfter: err.retryAfter || null
-      };
+  async auditContract(args) {
+    const address = String(args.address || args.contractAddress || '').trim();
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+      return JSON.stringify({
+        status: 'ERROR',
+        error: 'INVALID_ADDRESS',
+        message: 'A valid 40-hex 0x-prefixed Base contract address is required.'
+      });
+    }
+
+    const res = await this._queryApi(`/v1/audit/${encodeURIComponent(address)}`);
+    if (!res.ok) {
+      return JSON.stringify({
+        status: 'ERROR',
+        statusCode: res.statusCode,
+        error: res.body && res.body.error ? res.body.error : 'API_ERROR',
+        message: res.body && res.body.message ? res.body.message : 'Contract audit query failed',
+        notASafetyGuarantee: true
+      });
     }
+
+    return JSON.stringify({
+      status: 'SUCCESS',
+      data: res.body,
+      notASafetyGuarantee: true,
+      observationSummary: `Contract ${address}: Type=${res.body.bytecodeAnalysis?.contractType || 'UNKNOWN'}, isProxy=${Boolean(res.body.proxyDetection?.isProxy)}`
+    });
+  }
+
+  async getGasMetrics() {
+    const res = await this._queryApi('/v1/gas/fees');
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: 'Failed to retrieve gas fees' });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  async getTokenPrice(args) {
+    const symbol = String(args.symbol || args.tokenSymbol || '').trim().toUpperCase();
+    if (!symbol) {
+      return JSON.stringify({ status: 'ERROR', message: 'Token symbol is required (e.g. USDC, WETH)' });
+    }
+    const res = await this._queryApi(`/v1/token/price/${encodeURIComponent(symbol)}`);
+    if (!res.ok) {
+      return JSON.stringify({ status: 'ERROR', statusCode: res.statusCode, message: `Failed to retrieve price for ${symbol}` });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  async getServiceStatus() {
+    const res = await this._queryApi('/v1/status');
+    if (!res.ok) {
+      return JSON.stringify({ status: 'UNAVAILABLE', statusCode: res.statusCode });
+    }
+    return JSON.stringify(res.body);
+  }
+
+  getActions(_walletProvider) {
+    return [
+      {
+        name: 'm2m_audit_contract',
+        description: 'Inspect Base target contract bytecode capability observations, proxy implementation slots, and limitations before executing transactions. Returns factual evidence, not a safety guarantee.',
+        schema: {
+          type: 'object',
+          properties: {
+            address: {
+              type: 'string',
+              description: 'Target Base contract address (0x-prefixed 40-hex)'
+            }
+          },
+          required: ['address']
+        },
+        invoke: (args) => this.auditContract(args)
+      },
+      {
+        name: 'm2m_get_gas_metrics',
+        description: 'Get real-time Base network gas execution metrics and recommendations before submitting on-chain transactions.',
+        schema: {
+          type: 'object',
+          properties: {}
+        },
+        invoke: () => this.getGasMetrics()
+      },
+      {
+        name: 'm2m_get_token_price',
+        description: 'Observe real-time Base DEX token price for slippage check and valuation.',
+        schema: {
+          type: 'object',
+          properties: {
+            symbol: {
+              type: 'string',
+              description: 'Token symbol on Base (e.g. USDC, WETH)'
+            }
+          },
+          required: ['symbol']
+        },
+        invoke: (args) => this.getTokenPrice(args)
+      },
+      {
+        name: 'm2m_get_service_status',
+        description: 'Check operational status of M2M Sentinel upstream verification rails.',
+        schema: {
+          type: 'object',
+          properties: {}
+        },
+        invoke: () => this.getServiceStatus()
+      }
+    ];
   }
 }
 
-module.exports = { M2MSentinelAgentTool };
+function m2mSentinelActionProvider(options = {}) {
+  return new M2MSentinelActionProvider(options);
+}
+
+// Backward compatibility alias
+class M2MSentinelAgentTool extends M2MSentinelActionProvider {}
+
+module.exports = {
+  M2MSentinelActionProvider,
+  m2mSentinelActionProvider,
+  M2MSentinelAgentTool
+};

package/index.js

@@ -1,4 +1,4 @@
-const DEFAULT_BASE_URL = 'https://m2msentinel.vercel.app';
+const DEFAULT_BASE_URL = 'https://api.m2msentinel.com';
 const DEFAULT_TIMEOUT_MS = 30000;
 
 class M2MSentinelError extends Error {
@@ -171,6 +171,8 @@ function createViemSentinelInterceptor(apiKey, baseUrl, policy) {
   };
 }
 
+const { M2MSentinelActionProvider, m2mSentinelActionProvider } = require('./agent_adapter.js');
+
 module.exports = {
   M2MSentinelClient,
   M2MSentinelError,
@@ -179,5 +181,7 @@ module.exports = {
   DataSourceUnavailableError,
   enforceCallerPolicy,
   createEthersSentinelMiddleware,
-  createViemSentinelInterceptor
+  createViemSentinelInterceptor,
+  M2MSentinelActionProvider,
+  m2mSentinelActionProvider
 };

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "m2m-sentinel-sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "JavaScript client for M2M Sentinel Base bytecode capability, proxy and market observations",
   "main": "index.js",
   "types": "index.d.ts",
+  "bin": {
+    "m2m-sentinel-mcp": "./mcp_server.js",
+    "m2m-sentinel": "./mcp_server.js"
+  },
   "license": "MIT",
-  "homepage": "https://m2msentinel.vercel.app",
+  "homepage": "https://m2msentinel.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/M2M-Sentinel/m2m-sentinel-sdk.git"
+  },
   "bugs": {
-    "url": "https://m2msentinel.vercel.app/docs.html"
+    "url": "https://m2msentinel.com/docs.html"
   },
   "keywords": [
     "web3",