@shicodiez/crypto-regime-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shicodiez
+
+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,3 +1,199 @@
-# Temporary Holding Version
+# @shicodiez/crypto-regime-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Puente **MCP stdio** para [`signal-api`](https://signal-api.shicoars.workers.dev).
+Conecta Claude Desktop, Claude Code o Cursor al endpoint remoto
+`/mcp` y paga automáticamente las tools x402 con una wallet EVM local.
+
+> **No es Signal Messenger.** `signal-api` es el nombre del servicio de señales
+> cripto; este paquete no tiene relación con Signal Messenger ni con su app de
+> mensajería.
+
+- Tools gratis: `list_assets`, `get_catalog`.
+- Tools de pago: `get_signal` (0,01 USDC), `get_trend` (0,005 USDC),
+  `get_regime` (0,005 USDC).
+- Red por defecto: **Base mainnet** (`eip155:8453`), USDC.
+- Límite de gasto por sesión: `MAX_SPEND_USDC` (por defecto **1 USDC**).
+
+> **No publiques la clave privada.** Usa una wallet **dedicada**, con poco saldo,
+> solo para este puente. La clave se guarda en la configuración de Claude/Cursor
+> en texto plano y el puente la usa para firmar pagos x402.
+
+## Instalación
+
+El paquete aún **no está publicado en npm**. Para probarlo:
+
+```powershell
+cd mcp-bridge
+npm install
+node src/index.js
+```
+
+Para usarlo como comando local:
+
+```powershell
+npm link
+crypto-regime-mcp
+```
+
+La idea es publicarlo más adelante como `@shicodiez/crypto-regime-mcp`; entonces
+valdrá `npx -y @shicodiez/crypto-regime-mcp`.
+
+## Variables de entorno
+
+| Variable | Obligatoria | Default | Descripción |
+|---|---|---|---|
+| `EVM_PRIVATE_KEY` | Sí | — | Clave privada `0x...` de la wallet dedicada. Nunca la commitees. |
+| `MAX_SPEND_USDC` | No | `1` | Gasto máximo acumulado por sesión, en USDC. |
+| `SIGNAL_API_MCP_URL` | No | `https://signal-api.shicoars.workers.dev/mcp` | Endpoint MCP remoto. |
+| `NETWORK` | No | `eip155:8453` | Red x402. Usa `eip155:84532` para testnet. |
+
+El límite `MAX_SPEND_USDC` se aplica **antes** de cada pago: si el pago haría
+superar el acumulado, se bloquea y la tool devuelve error. Se asume USDC de 6
+decimales (el activo de signal-api). El contador es conservador: si un settlement
+falla después de autorizar, el importe sigue contado en la sesión.
+
+## Claude Desktop
+
+Edita:
+
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "crypto-regime": {
+      "command": "npx",
+      "args": ["-y", "@shicodiez/crypto-regime-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x...",
+        "MAX_SPEND_USDC": "1"
+      }
+    }
+  }
+}
+```
+
+Si aún no está publicado, apunta al script local:
+
+```json
+{
+  "mcpServers": {
+    "crypto-regime": {
+      "command": "node",
+      "args": ["C:\\Users\\TU_USUARIO\\signal-bot\\mcp-bridge\\src\\index.js"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x...",
+        "MAX_SPEND_USDC": "1"
+      }
+    }
+  }
+}
+```
+
+Reinicia Claude Desktop después de guardar.
+
+## Claude Code
+
+Con el paquete publicado:
+
+```powershell
+claude mcp add crypto-regime `
+  --env EVM_PRIVATE_KEY=0x... `
+  --env MAX_SPEND_USDC=1 `
+  -- npx -y @shicodiez/crypto-regime-mcp
+```
+
+Con el script local:
+
+```powershell
+claude mcp add crypto-regime `
+  --env EVM_PRIVATE_KEY=0x... `
+  --env MAX_SPEND_USDC=1 `
+  -- node C:\Users\TU_USUARIO\signal-bot\mcp-bridge\src\index.js
+```
+
+Comprueba con `claude mcp list` y `claude mcp get crypto-regime`.
+
+## Cursor
+
+Crea `.cursor/mcp.json` en el proyecto (o usa la configuración global de Cursor):
+
+```json
+{
+  "mcpServers": {
+    "crypto-regime": {
+      "command": "npx",
+      "args": ["-y", "@shicodiez/crypto-regime-mcp"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x...",
+        "MAX_SPEND_USDC": "1"
+      }
+    }
+  }
+}
+```
+
+Para el script local, cambia `command` por `node` y `args` por la ruta absoluta
+de `src/index.js`. Recarga la ventana de MCP de Cursor.
+
+## Cómo funciona
+
+El puente:
+
+1. Abre el `/mcp` remoto con `StreamableHTTPClientTransport`.
+2. Lo envuelve con **`createx402MCPClient`** y `ExactEvmScheme` de `@x402/evm`.
+3. Expone un servidor MCP **stdio** con `ListTools`/`CallTool` que reenvía al
+   cliente remoto.
+4. Cuando una tool devuelve `PaymentRequired` (x402 v2), el cliente firma el
+   pago con `EVM_PRIVATE_KEY`, lo reintenta con `_meta["x402/payment"]` y
+   devuelve el resultado junto con `_meta["x402/payment-response"]`.
+
+El servidor remoto verifica y liquida con su facilitator; el puente solo firma
+el pago. No hay custodia de fondos.
+
+## Probar con MCP Inspector (stdio)
+
+```powershell
+cd mcp-bridge
+npm install
+$env:EVM_PRIVATE_KEY = "0x..."   # no lo imprimas
+$env:MAX_SPEND_USDC = "1"
+
+npx @modelcontextprotocol/inspector@latest --cli `
+  --transport stdio `
+  --method tools/list `
+  --format json `
+  -- node C:\Users\TU_USUARIO\signal-bot\mcp-bridge\src\index.js
+```
+
+También puedes arrancar la UI web de Inspector sin `--cli` y elegir
+`Standalone` → `stdio` → comando `node`, argumento `src/index.js`.
+
+Para probar una tool gratis:
+
+```powershell
+npx @modelcontextprotocol/inspector@latest --cli `
+  --transport stdio `
+  --method tools/call `
+  --tool-name list_assets `
+  --format json `
+  -- node C:\Users\TU_USUARIO\signal-bot\mcp-bridge\src\index.js
+```
+
+Las tools de pago requieren saldo USDC en la wallet y consumen
+`MAX_SPEND_USDC`. Para testnet usa `NETWORK=eip155:84532` y un endpoint local
+`SIGNAL_API_MCP_URL=http://localhost:8787/mcp`.
+
+## Seguridad
+
+- Usa una wallet **exclusiva** para este puente y mantén solo el saldo que estás
+  dispuesto a gastar.
+- No pongas la clave en el repositorio, en `README.md`, en capturas ni en logs.
+- `MAX_SPEND_USDC` reduce el daño de un agente descontrolado, pero no sustituye
+  a una wallet con poco saldo.
+- El puente no puede retirar fondos: solo firma autorizaciones x402 del importe
+  que pide el servidor, sujeto al límite.
+- Si ves un `payment blocked`, revisa `MAX_SPEND_USDC` y el acumulado de la
+  sesión; reinicia el cliente MCP para empezar una sesión nueva.

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@shicodiez/crypto-regime-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Stdio MCP bridge for crypto trend/regime tools with automatic x402 payments.",
+  "type": "module",
+  "bin": {
+    "crypto-regime-mcp": "src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "x402",
+    "crypto",
+    "trend",
+    "regime",
+    "volatility",
+    "base",
+    "usdc"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Shicodiez/signal-bot.git",
+    "directory": "mcp-bridge"
+  },
+  "homepage": "https://signal-api.shicoars.workers.dev",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@x402/core": "2.30.0",
+    "@x402/evm": "2.30.0",
+    "@x402/mcp": "2.30.0",
+    "viem": "^2.57.16"
+  }
+}

package/src/index.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+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 { ExactEvmScheme } from "@x402/evm/exact/client";
+import { createx402MCPClient } from "@x402/mcp";
+import { privateKeyToAccount } from "viem/accounts";
+
+import { createSpendTracker, usdcFromAtomic } from "./spend.js";
+
+const VERSION = "0.1.0";
+const DEFAULT_MCP_URL = "https://signal-api.shicoars.workers.dev/mcp";
+const DEFAULT_NETWORK = "eip155:8453";
+const DEFAULT_MAX_SPEND_USDC = 1;
+
+function log(message) {
+  // stdout is reserved for the MCP stdio protocol.
+  console.error(`[crypto-regime-mcp] ${message}`);
+}
+
+function parseMaxSpend() {
+  const raw = process.env.MAX_SPEND_USDC;
+  if (raw === undefined || raw.trim() === "") {
+    return DEFAULT_MAX_SPEND_USDC;
+  }
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error("MAX_SPEND_USDC must be a non-negative number");
+  }
+  return value;
+}
+
+function getPrivateKey() {
+  const raw = process.env.EVM_PRIVATE_KEY?.trim();
+  if (!raw || !/^0x[0-9a-fA-F]{64}$/.test(raw)) {
+    throw new Error("EVM_PRIVATE_KEY must be a 32-byte hex private key (0x...)");
+  }
+  return raw;
+}
+
+async function main() {
+  const mcpUrl = process.env.SIGNAL_API_MCP_URL ?? DEFAULT_MCP_URL;
+  const network = process.env.NETWORK ?? DEFAULT_NETWORK;
+  const maxSpendUsdc = parseMaxSpend();
+  const account = privateKeyToAccount(getPrivateKey());
+  const tracker = createSpendTracker(maxSpendUsdc);
+
+  const paymentClient = createx402MCPClient({
+    name: "crypto-regime-mcp",
+    version: VERSION,
+    schemes: [
+      {
+        network,
+        client: new ExactEvmScheme(account),
+      },
+    ],
+    spendControls:
+      maxSpendUsdc > 0
+        ? { maxAmountPerPayment: `$${maxSpendUsdc}` }
+        : false,
+    autoPayment: true,
+    onPaymentRequested: async ({ paymentRequired }) => {
+      const accept = paymentRequired.accepts?.[0];
+      if (!accept) {
+        log("payment blocked: no accepts entry");
+        return false;
+      }
+      const amountUsd = usdcFromAtomic(accept.amount);
+      if (amountUsd === null) {
+        log(`payment blocked: invalid amount ${accept.amount}`);
+        return false;
+      }
+      if (!tracker.canSpend(amountUsd)) {
+        log(
+          `payment blocked: $${amountUsd} would exceed MAX_SPEND_USDC=$${maxSpendUsdc} (spent $${tracker.spentUsdc})`,
+        );
+        return false;
+      }
+      tracker.record(amountUsd);
+      log(
+        `authorizing $${amountUsd} on ${accept.network} to ${accept.payTo} (spent $${tracker.spentUsdc}/$${maxSpendUsdc})`,
+      );
+      return true;
+    },
+  });
+
+  const transport = new StreamableHTTPClientTransport(new URL(mcpUrl));
+  await paymentClient.connect(transport);
+
+  const server = new Server(
+    { name: "crypto-regime-mcp", version: VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const result = await paymentClient.listTools();
+    return { tools: result.tools };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      const result = await paymentClient.callTool(name, args ?? {});
+      const meta = { ...(result._meta ?? {}) };
+      if (result.paymentResponse) {
+        meta["x402/payment-response"] = result.paymentResponse;
+      }
+      return {
+        content: result.content,
+        isError: result.isError,
+        structuredContent: result.structuredContent,
+        _meta: Object.keys(meta).length > 0 ? meta : undefined,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      log(`tool ${name} failed: ${message}`);
+      return {
+        content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+        isError: true,
+      };
+    }
+  });
+
+  await server.connect(new StdioServerTransport());
+  log(
+    `connected to ${mcpUrl} as ${account.address}; MAX_SPEND_USDC=$${maxSpendUsdc}`,
+  );
+}
+
+main().catch((error) => {
+  log(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/src/spend.js

@@ -0,0 +1,40 @@
+export function createSpendTracker(maxSpendUsdc) {
+  let spentUsdc = 0;
+  const epsilon = 1e-9;
+
+  return {
+    get maxUsdc() {
+      return maxSpendUsdc;
+    },
+    get spentUsdc() {
+      return spentUsdc;
+    },
+    remainingUsdc() {
+      return Math.max(
+        0,
+        Math.round((maxSpendUsdc - spentUsdc) * 1e6) / 1e6,
+      );
+    },
+    canSpend(amountUsdc) {
+      return (
+        Number.isFinite(amountUsdc) &&
+        amountUsdc >= 0 &&
+        spentUsdc + amountUsdc <= maxSpendUsdc + epsilon
+      );
+    },
+    record(amountUsdc) {
+      if (!Number.isFinite(amountUsdc) || amountUsdc < 0) {
+        throw new Error("amountUsdc must be a non-negative finite number");
+      }
+      spentUsdc = Math.round((spentUsdc + amountUsdc) * 1e6) / 1e6;
+    },
+  };
+}
+
+export function usdcFromAtomic(amount, decimals = 6) {
+  const value = Number(amount);
+  if (!Number.isFinite(value) || value < 0) {
+    return null;
+  }
+  return value / 10 ** decimals;
+}