payflowagent-mcp 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# PayFlowAgent MCP-Server
+
+Bindet den PayFlowAgent-Dienst (Token-Intelligence fuer nad.fun auf Monad) als
+**MCP-Server** in KI-Agenten ein — Cursor, Claude Desktop oder eigene Agenten.
+
+Warum: Je niedriger die Integrationshuerde, desto eher kommt der naechste bezahlte
+Call. Ein Agent fuegt einmal diesen Server hinzu und kann danach Token bewerten —
+die bezahlten Tools begleichen den Preis automatisch in USDC via **x402**.
+
+## Tools
+
+| Tool            | Preis        | Beschreibung |
+|-----------------|--------------|--------------|
+| `score_token`   | kostenlos    | 0–100 Score, `riskLevel`, `action` (rate-limitiert). |
+| `decide_token`  | bezahlt (x402) | Voller Report: Faktoren, Graduation, Momentum. |
+| `token_summary` | bezahlt (x402) | Graduation-Fortschritt + Momentum (guenstiger Einstieg). |
+| `screen_tokens` | bezahlt (x402) | Gerankte Liste vorgescorter neuer Token. |
+
+## Konfiguration (Env)
+
+| Variable                 | Default                       | Zweck |
+|--------------------------|-------------------------------|-------|
+| `PAYFLOWAGENT_API_BASE`  | `https://payflowagent.net`    | Basis-URL des Dienstes. |
+| `X402_BUYER_PRIVATE_KEY` | —                             | Private Key einer **dedizierten** Zahler-Wallet (Base, USDC). Ohne Key laufen nur kostenlose Tools. |
+| `X402_BUYER_RPC`         | `https://mainnet.base.org`    | Zahlungs-RPC (optional). |
+
+> Sicherheit: Nutze eine separate Wallet nur fuer diese Zahlungen, niemals die
+> Empfangs-Wallet oder eine Wallet mit grossem Guthaben. Der Key wird ausschliesslich
+> aus der Env gelesen.
+
+## Einbinden in Cursor
+
+`~/.cursor/mcp.json` (oder Projekt-`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "payflowagent": {
+      "command": "npx",
+      "args": ["-y", "payflowagent-mcp"],
+      "env": {
+        "X402_BUYER_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## Einbinden in Claude Desktop
+
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "payflowagent": {
+      "command": "npx",
+      "args": ["-y", "payflowagent-mcp"],
+      "env": { "X402_BUYER_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+> Ohne installiertes Paket lädt `npx -y payflowagent-mcp` es automatisch von npm.
+> Für lokale Entwicklung statt der npm-Version: `["-y", "tsx", "<absoluter Pfad>/apps/mcp/src/index.ts"]`.
+
+## Lokal starten / testen
+
+```bash
+pnpm --filter payflowagent-mcp start       # stdio-Server (aus dem Quellcode)
+pnpm --filter payflowagent-mcp typecheck
+pnpm --filter payflowagent-mcp build       # dist/ erzeugen (wie beim Publish)
+```
+
+## Veröffentlichen (npm)
+
+Einmalig vorbereiten und publishen (benötigt deinen npm-Account):
+
+```bash
+npm login                                  # einmalig
+cd apps/mcp
+npm publish --access public                # baut via prepack automatisch dist/
+```
+
+Nach dem Publish funktioniert überall: `npx -y payflowagent-mcp`.
+
+### Offizielle MCP-Registry (optional)
+
+`server.json` liegt bei. Mit dem offiziellen Publisher:
+
+```bash
+# Publisher installieren: siehe https://github.com/modelcontextprotocol/registry
+mcp-publisher login                        # Namespace net.payflowagent/* via DNS-TXT verifizieren
+mcp-publisher publish                      # nutzt apps/mcp/server.json
+```
+
+Viele Verzeichnisse (Glama, mcp.so, PulseMCP) indexieren npm zusätzlich automatisch
+anhand der `mcp*`-Keywords.
+
+Der Server kommuniziert ueber **stdio** (stdout ist dem MCP-Protokoll vorbehalten;
+Statusmeldungen gehen nach stderr).
+
+## Hinweis
+
+Ohne `X402_BUYER_PRIVATE_KEY` liefern die bezahlten Tools eine klare Meldung, wie
+man Zahlungen aktiviert — `score_token` funktioniert immer kostenlos zum Ausprobieren.

package/dist/index.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * PayFlowAgent MCP-Server (stdio).
+ *
+ * Zweck (Leitfrage "dient es den Zahlungseingaengen?"):
+ *   Verteilt den Dienst genau dort, wo zahlende KI-Agenten leben (Cursor, Claude
+ *   Desktop, eigene Agenten). Ein Agent bindet diesen MCP-Server ein und kann
+ *   ohne Integrationsaufwand Token-Scores abrufen - die bezahlten Tools loesen
+ *   per x402 automatisch eine USDC-Zahlung an die Empfangs-Wallet aus.
+ *
+ * Tools:
+ *   - score_token   (kostenlos): 0-100 Score, riskLevel, action fuer einen Token.
+ *   - decide_token  (bezahlt):   voller Report inkl. Faktoren/Graduation/Momentum.
+ *   - token_summary (bezahlt):   Graduation + Momentum (guenstiger Einstieg).
+ *   - screen_tokens (bezahlt):   gerankte Liste vorgescorter neuer Token.
+ *
+ * Konfiguration (Env):
+ *   PAYFLOWAGENT_API_BASE   Basis-URL des Dienstes (Default https://payflowagent.net)
+ *   X402_BUYER_PRIVATE_KEY  Private Key einer dedizierten Zahler-Wallet (Base, USDC).
+ *                           Ohne Key funktionieren nur die kostenlosen Tools.
+ *   X402_BUYER_RPC          Optionaler Zahlungs-RPC (Default https://mainnet.base.org)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createPayer, payFetch } from "./x402.js";
+const API_BASE = (process.env.PAYFLOWAGENT_API_BASE ?? "https://payflowagent.net").replace(/\/+$/, "");
+const payer = createPayer(process.env.X402_BUYER_PRIVATE_KEY, process.env.X402_BUYER_RPC);
+const TOKEN = z
+    .string()
+    .regex(/^0x[0-9a-fA-F]{40}$/, "nad.fun Token-Adresse auf Monad (0x..., 42 Hex-Zeichen)");
+const ok = (data, meta) => ({
+    content: [{ type: "text", text: JSON.stringify(meta ? { ...meta, data } : data, null, 2) }],
+});
+const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+/** Wandelt ein PayResult in ein MCP-Tool-Ergebnis (mit hilfreichen Fehlern). */
+function present(label, r) {
+    if (r.ok) {
+        return ok(r.data, r.paid ? { paid: true, tx: r.tx ?? null, price: "USDC via x402" } : undefined);
+    }
+    if (r.status === 402 && r.error === "payment_required_no_key") {
+        return err(`${label} ist kostenpflichtig (x402, USDC). Es ist keine Zahler-Wallet konfiguriert.\n` +
+            `Setze die Umgebungsvariable X402_BUYER_PRIVATE_KEY (dedizierte Wallet mit USDC auf Base) ` +
+            `und starte den MCP-Server neu. Fuer einen kostenlosen Test nutze stattdessen das Tool "score_token".`);
+    }
+    if (r.status === 429) {
+        return err(`${label}: Rate-Limit erreicht (kostenloser Endpunkt). Bitte spaeter erneut versuchen.`);
+    }
+    if (r.error?.startsWith("payment_failed")) {
+        return err(`${label}: Zahlung fehlgeschlagen. Haeufige Ursache: zu wenig USDC/ETH (Gas) in der Zahler-Wallet. Detail: ${r.error}`);
+    }
+    const detail = typeof r.data === "object" ? JSON.stringify(r.data) : String(r.data ?? "");
+    return err(`${label}: HTTP ${r.status}. ${detail}`);
+}
+const server = new McpServer({ name: "payflowagent", version: "0.1.0" });
+server.registerTool("score_token", {
+    title: "Token-Score (kostenlos)",
+    description: "Kostenloser, rate-limitierter Score (0-100) inkl. riskLevel und action fuer einen nad.fun-Token auf Monad. " +
+        "Ideal zum Pruefen vor einem bezahlten Aufruf.",
+    inputSchema: { token: TOKEN },
+}, async ({ token }) => present("score_token", await payFetch(`${API_BASE}/v1/lite?token=${token}`, null)));
+server.registerTool("decide_token", {
+    title: "Voller Report (bezahlt, x402)",
+    description: "Bezahlt (USDC via x402). Entscheidungsfertiger Report fuer einen nad.fun-Token: Score, riskLevel, action, " +
+        "erklaerende Faktoren, Graduation-Fortschritt und 5-Minuten-Momentum.",
+    inputSchema: { token: TOKEN },
+}, async ({ token }) => present("decide_token", await payFetch(`${API_BASE}/v1/decide?token=${token}`, payer)));
+server.registerTool("token_summary", {
+    title: "Graduation + Momentum (bezahlt, x402)",
+    description: "Bezahlt (USDC via x402). Guenstiger Einstieg: Graduation-Fortschritt (Bonding-Curve %) + Momentum-" +
+        "Zusammenfassung fuer einen nad.fun-Token.",
+    inputSchema: { token: TOKEN },
+}, async ({ token }) => present("token_summary", await payFetch(`${API_BASE}/v1/token/${token}/summary`, payer)));
+server.registerTool("screen_tokens", {
+    title: "Screening: gerankte Token-Liste (bezahlt, x402)",
+    description: "Bezahlt (USDC via x402). Gerankte Liste vorgescorter, frischer nad.fun-Token (score, riskLevel, action, " +
+        "Graduation, Holder). Ideal fuer Screener/Trading-Agenten, die regelmaessig nach Chancen suchen.",
+    inputSchema: {
+        limit: z.number().int().min(1).max(25).optional().describe("Max. Anzahl Token (1-25, Default 10)"),
+        minScore: z.number().int().min(0).max(100).optional().describe("Nur Token mit Score >= minScore (0-100)"),
+    },
+}, async ({ limit, minScore }) => {
+    const qs = new URLSearchParams();
+    if (limit != null)
+        qs.set("limit", String(limit));
+    if (minScore != null)
+        qs.set("minScore", String(minScore));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return present("screen_tokens", await payFetch(`${API_BASE}/v1/screen${suffix}`, payer));
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Hinweis auf stderr (stdout ist dem MCP-Protokoll vorbehalten).
+    console.error(`[payflowagent-mcp] verbunden. API=${API_BASE} · Zahlungen=${payer ? `aktiv (${payer.address})` : "deaktiviert (kein X402_BUYER_PRIVATE_KEY)"}`);
+}
+main().catch((e) => {
+    console.error(`[payflowagent-mcp] Start fehlgeschlagen: ${e?.message ?? String(e)}`);
+    process.exit(1);
+});

package/dist/x402.js

@@ -0,0 +1,78 @@
+/**
+ * x402-Zahlungs-Helper fuer den MCP-Server.
+ *
+ * Zweck (Leitfrage "dient es den Zahlungseingaengen?"):
+ *   Macht aus einem normalen fetch einen bezahlenden fetch. Bezahlte Routen
+ *   (HTTP 402) werden - falls ein Buyer-Key gesetzt ist - automatisch in USDC
+ *   beglichen und erneut aufgerufen. Damit kann jeder KI-Agent, der diesen
+ *   MCP-Server einbindet, ohne Zusatzcode bezahlte Calls ausloesen.
+ *
+ * Sicherheit: Der Private Key kommt NUR aus der Env (X402_BUYER_PRIVATE_KEY),
+ * niemals aus Argumenten/Logs. Es muss eine dedizierte Zahler-Wallet sein.
+ */
+import { privateKeyToAccount } from "viem/accounts";
+import { x402Client, x402HTTPClient } from "@x402/core/client";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+/** Default-Zahlungs-RPC (Base Mainnet). Per X402_BUYER_RPC ueberschreibbar. */
+const DEFAULT_RPC = "https://mainnet.base.org";
+/**
+ * Baut einen Payer aus dem Buyer-Key. Gibt null zurueck, wenn kein gueltiger
+ * Key vorhanden ist (dann funktionieren nur die kostenlosen Tools).
+ */
+export function createPayer(privateKey, rpcUrl) {
+    const key = privateKey?.trim();
+    if (!key || !/^0x[0-9a-fA-F]{64}$/.test(key))
+        return null;
+    const account = privateKeyToAccount(key);
+    const core = new x402Client();
+    registerExactEvmScheme(core, { signer: account, schemeOptions: { rpcUrl: rpcUrl?.trim() || DEFAULT_RPC } });
+    return { address: account.address, http: new x402HTTPClient(core) };
+}
+/**
+ * Fuehrt einen GET aus. Bei 402 wird - sofern ein Payer vorhanden ist -
+ * automatisch bezahlt und erneut aufgerufen.
+ */
+export async function payFetch(url, payer) {
+    const r1 = await fetch(url, { headers: { accept: "application/json" } });
+    // Kein Bezahlfall (200, 400, 429, ...) -> direkt zurueck.
+    if (r1.status !== 402) {
+        const data = await r1.json().catch(() => undefined);
+        return { ok: r1.ok, status: r1.status, data, paid: false };
+    }
+    const body1 = await r1.json().catch(() => undefined);
+    if (!payer) {
+        return {
+            ok: false,
+            status: 402,
+            data: body1,
+            paid: false,
+            error: "payment_required_no_key",
+        };
+    }
+    // 402 -> Zahlung signieren und erneut aufrufen.
+    try {
+        const required = payer.http.getPaymentRequiredResponse((n) => r1.headers.get(n), body1);
+        const payload = await payer.http.createPaymentPayload(required);
+        const payHeaders = payer.http.encodePaymentSignatureHeader(payload);
+        const r2 = await fetch(url, { headers: { accept: "application/json", ...payHeaders } });
+        const data = await r2.json().catch(() => undefined);
+        let tx;
+        try {
+            const settle = payer.http.getPaymentSettleResponse((n) => r2.headers.get(n));
+            tx = settle?.transaction;
+        }
+        catch {
+            /* Settlement-Header optional */
+        }
+        return { ok: r2.ok, status: r2.status, data, paid: r2.ok, tx };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            status: 402,
+            data: body1,
+            paid: false,
+            error: `payment_failed: ${e?.message ?? String(e)}`,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "payflowagent-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for PayFlowAgent — free & pay-per-call (x402/USDC) risk & momentum scores for nad.fun tokens on Monad.",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "mcp-server",
+    "x402",
+    "monad",
+    "nad.fun",
+    "crypto",
+    "token",
+    "agent",
+    "ai"
+  ],
+  "homepage": "https://payflowagent.net",
+  "bugs": {
+    "url": "https://payflowagent.net"
+  },
+  "license": "MIT",
+  "author": "PayFlowAgent",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "payflowagent-mcp": "dist/index.js"
+  },
+  "mcpName": "net.payflowagent/mcp",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "echo \"no tests yet\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@x402/core": "^2.17.0",
+    "@x402/evm": "^2.17.0",
+    "viem": "^2.21.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}