NostrPulse

🤖 MCP Server for AI Agents (Stripe for AI)

NostrPulse natively exports an industry-standard Model Context Protocol (MCP) server over Stdio JSON-RPC. Any AI client (Claude Desktop, Cursor, Windsurf, LangChain, Vercel AI SDK) can instantly tap into decentralized reputation, machine-to-machine micropayments, and distributed compute without API keys or custodial accounts.

1. Zero-Code Quickstart (Cursor & Claude Desktop)

Paste this configuration directly into your claude_desktop_config.json or .cursor/mcp.json:

{  "mcpServers": {    "nostrpulse": {      "command": "npx",      "args": ["-y", "nostrpulse-mcp"]    }  }}

• Claude Desktop Config File Locations:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Cursor IDE: Save to .cursor/mcp.json in your project root, or add under Cursor Settings > Features > MCP.

2. Interactive Testing via MCP Inspector

Verify tools, examine schemas, and test prompts in the browser via the official Model Context Protocol Inspector:

npx @modelcontextprotocol/inspector npx -y nostrpulse-mcp

3. Core MCP Tools Lookup Table

4. Profiles for Small Language Models (SLMs: 500M – 1.5B)

For edge devices, local SLMs (e.g., Qwen 2.5 0.5B/1.5B via Ollama), or cost-sensitive agent loops, NostrPulse supports context-optimized profiles that reduce prompt overhead from ~2,200 tokens down to ~380 tokens:

# Launch with minimal profile (3 core tools: check_trust_score, pay_cashu_nutzap, get_spending_guardrails)npx -y nostrpulse-mcp --profile=minimal
# Or via environment variableNOSTRPULSE_PROFILE=minimal npx -y nostrpulse-mcp

5. Autonomous Agent-to-Agent (A2A) Collaborative Mesh

NostrPulse includes a reference implementation for autonomous agent-to-agent decentralized negotiation and micro-commerce (scripts/test-mesh-agent.ts):

[ Agent A: Requester / Buyer ]                   [ Agent B: Worker / Seller ]             │                                                │             ├──► 1. Dispatch NIP-90 Job ('zap-analytics') ──►│             │                                                │             │    2. Audit Requester WoT Anti-Sybil Score ◄───┤ (Requires Trust Score > 40)             │       (check_trust_score)                      │             │                                                │             │◄── 3. Acknowledge & Deliver Computation ───────┤             │                                                │             ├──► 4. Inspect Budget Guardrails (assert 24h)   │             │                                                │             ├──► 5. Settle Cashu NutZap (Adaptive Fallback) ─►│

• Zero-Cloud Local Inference: Run the showcase locally using Ollama (qwen2.5-coder:1.5b) without cloud API keys:
  bash

  npm exec tsx scripts/test-mesh-agent.ts --ollama

• Adaptive Spending Fallback: If a requested micro-payment exceeds the rolling 24-hour spending limit, the agent automatically adapts down to the remaining safe allowance to settle minimum fees without crashing or overspending.

🌐 The Problem & The Freedom Solution

Open agentic systems and decentralized protocols eliminate platform lock-in, but introduce two critical vulnerabilities:

1. Agent Impersonation & Sybil Floods: Cryptographic keypairs (npub) cost $0 to generate, making spam bots, clone accounts, and wash-trading rampant.
2. Payment Fragility & KYC Lockouts: Legacy banking rails (Stripe/PayPal) freeze autonomous agents. Synchronous Lightning Zaps (NIP-57) fail when receiver nodes are offline or lack inbound liquidity channels.

Paradigm Shift

🏛️ Multi-Tier System Pipeline

🚀 Key Innovations & Engineering Highlights

1. 🛡️ 5-Pillar Cryptographic Trust Score & Anti-Sybil Visualizer

NostrPulse calculates an objective 0–100 point reputation index directly from open relay data and root anchor graph topology:

[!IMPORTANT] Anti-Sybil Damping Guard: Accounts lacking verified NIP-05 DNS signatures AND isolated from the Web-of-Trust graph are strictly capped at 44 points (Unverified / Potential Bot). This permanently neutralizes automated bot swarms.

2. ⚡ Dual-Rail Value-4-Value Settlement (Lightning + Cashu eCash)

A unified micro-transaction interface switching effortlessly between real-time Lightning and offline Chaumian eCash:

[ 1-Click In-App Minting & NutZap Pipeline ]User/Agent selects Sats ──► Request NUT-04 Quote ──► Settle via WebLN/QR ──► Poll Mint & Claim Proofs ──► Encrypt NIP-59/44 ──► Broadcast Kind 9321

• 100% Asynchronous NutZaps (NIP-61): Senders deliver bearer eCash tokens to creators even when the recipient's Lightning node is offline.
• NIP-59 Gift Wrap Envelope Privacy: Wraps NutZaps with random ephemeral keypairs to conceal sender, recipient, and payload metadata from public relay scrapers.
• Front-Running Defense (NIP-44 v2 Encryption): Bearer tokens inside Kind 9321 events are encrypted with the recipient's public key.
• Native NUT-00 V4 CBOR Decoding: Zero-dependency binary parser compliant with RFC 8949, reading both legacy cashuA (JSON Base64) and next-gen cashuB (CBOR) tokens.
• Dynamic Mint Router: Switch between Minibits, Macadamia, Cashu Testnut, or private self-hosted Mint endpoints.

3. ⚡ NIP-47 Nostr Wallet Connect (NWC) Direct Lightning Rail

NostrPulse integrates a high-performance, zero-memory-leak client for NIP-47 Nostr Wallet Connect, allowing AI agents to pay BOLT-11 Lightning invoices directly through self-hosted autonomous nodes (Alby Hub, Phoenixd, Umbrel, LNBits):

[ NIP-47 Direct Lightning Settlement Pipeline ]Agent receives Invoice ──► Parse NWC URI ──► Encrypt Payload (NIP-04/44) ──► Publish Kind 23194 ──► Listen Kind 23195 (Tagged by #e) ──► Extract Preimage & Fees ──► Destroy Pool & Subscriptions

• Standardized Connection URIs: Seamless parsing and generation of nostr+walletconnect://<wallet_pubkey>?relay=<relay_url>&secret=<client_secret>&lud16=<lightning_address>&encryption=<nip04|nip44>.
• Zero-Leak Subscription Lifecycle: Immediate resource cleanup upon resolution or timeout, destroying relay pools and event subscriptions to prevent memory retention in long-running agent daemons.
• Dual Encryption Handshake: Transparent fallback support for both legacy NIP-04 shared secrets and next-gen ChaCha20-Poly1305 NIP-44 v2 encryption.
• Autonomous MCP Execution: Exposed as pay_lightning_nwc (with alias pay_with_nwc) for 1-step settling by autonomous agents.

4. 🛡️ WoT-Gated Dynamic Mint Mesh & Counterparty Risk Radar (NUT-06)

Cashu Mints carry counterparty risk. NostrPulse acts as an objective, real-time Radar for Mints via auditCashuMint and selectBestMint:

[ 5-Pillar Mint Risk Auditing & Dynamic Mesh Routing ]Target Mint URL ──► Probe NUT-06 /v1/info ──► Extract Admin Contact ──► Resolve WoT & NIP-05 ──► Compute 5-Pillar Mint Score ──► Classify Risk (LOW / MODERATE / HIGH_RISK) ──► Route to Optimal Mint

• NUT-06 Probe & Capability Auditing: Evaluates mint uptime, operational response latency, and supported protocol capabilities (NUT-04 Mint, NUT-05 Melt, NUT-07 StateCheck, NUT-08 FeeReturn, NUT-10 DLEQ Proofs, NUT-11 P2PK).
• Cryptographic Admin Identity Discovery: Extracts Nostr operator pubkeys, NIP-05 sovereign domain signatures, or Nostr URIs from contact metadata, resolving transitive WoT graph distance to the 22 Root Anchors.
• Tri-Tier Counterparty Risk Profiling (MintRiskProfile):
  • LOW (Trust Score ≥ 75): TRUSTED (Directly verified operator, low latency, full NUT compliance).
  • MODERATE (Trust Score 45–74): USE_WITH_CAP (Community mint with acceptable uptime and WoT connectivity).
  • HIGH_RISK (Trust Score < 45 or unverified admin): AVOID (Anonymous, insecure HTTP, high latency, or isolated keypair).
• Autonomous Mesh Selection (selectBestMint): Evaluates candidate mint lists concurrently and dynamically selects the highest-trust, lowest-latency mint for proof creation and payment routing.

5. 🤖 Autonomous Machine Money Agent (/agent)

A dedicated interface demonstrating autonomous agent commerce:

• Interactive AI Spender: Agent equipped with Chaumian eCash wallet capable of paying creators automatically based on quality prompts.
• Connect MCP Modal: 1-click copy configuration for Claude Desktop and Cursor IDE.
• Stand-alone NutZap Web Component (public/widget.js): Lightweight <nutzap-me npub="..."> button ready to embed on any blog, documentation, or static site.

6. 🤖 NIP-90 Autonomous DVM Worker & Decentralized Bounty Marketplace

• Autonomous Trust Score DVM Bot (scripts/dvm-worker.ts): Background worker that listens for Kind 5000 job requests tagged with ["t", "trust-score"], computes scores, and broadcasts Kind 6000 with 5-Sat demand (["amount", "5000"]).
• NIP-90 Client SDK (src/lib/nip90.ts): Utility library offering publishJobRequest(), fetchOpenBounties(), and subscribeJobFeedbackAndResult().
• Anti-Sybil Bounty Marketplace (/bounties): Open decentralized task board filtered by creator Trust Score (All, Score ≥ 20, Score ≥ 50, Score ≥ 80).
• 1-Tap Cashu NutZap Settlement (TaskResultView.tsx): Audit deliverables and settle bounties instantly with NIP-44/59 encrypted NutZaps.

7. 🛡️ Autonomous Agent Spending Guardrails & Budget Manager

To prevent autonomous agents from draining balances through infinite loops, hallucinated calls, or prompt injections, NostrPulse enforces real-time Spending Guardrails:

[ Agent Payment Request ] ──► Check maxSatsPerTx (50 sats) ──► Check Rolling 24h Spend (500 sats) ──► Resolve WoT Score (>= 40)                                            │                                      │                                 │                                            ▼ (Any Violation)                      ▼ (Any Violation)                 ▼ (Any Violation)                                  [ Short-Circuit Block ] ◄────────────── [ Short-Circuit Block ] ◄───────── [ Short-Circuit Block ]                                            │                                            ▼                           Return { status: "blocked_by_guardrails" } (0 Sats Spent)

• Per-Transaction Cap (AGENT_MAX_SATS_PER_TX): Restricts single transaction calls to a safe default of 50 sats.
• 24-Hour Rolling Budget (AGENT_DAILY_LIMIT_SATS): Queries SQLite table agent_spending_log to enforce a rolling daily limit of 500 sats.
• Anti-Sybil Counterparty Gate (AGENT_MIN_RECIPIENT_SCORE): Evaluates counterparty trust score via Web-of-Trust graph distance; payments to unverified or bot identities (< 40 score) are automatically intercepted and blocked.
• Non-Custodial Safety: Rejections return { status: "blocked_by_guardrails", reason } instantly without spending funds.

8. 🔑 Zero-Config Sovereign Identity Bootstrapping

Eliminates the friction of requiring developers or agents to manually generate, paste, or expose nsec private keys before running:

[ Agent Initialization ]          │          ├──► 1. Check process.env.NOSTR_SECRET_KEY / AGENT_NSEC (Hex or Bech32 nsec1...)          │         └── Found? ──► Use environment identity          │          ├──► 2. Check Local Keystore (.nostrpulse/agent-identity.json)          │         └── Exists? ──► Restore persistent identity          │          └──► 3. Cryptographic CSPRNG Generation (nostr-tools/pure)                    └── Generates secp256k1 keypair ──► Writes to .nostrpulse/ (Mode 0600)

• Automated Persistence: Keypair is saved to .nostrpulse/agent-identity.json with restricted permissions and automatically excluded from Git commits via .gitignore.
• Instant Readiness: Tools like get_agent_identity allow agents to query their public identity (pubkey, npub, source, ephemeral flag) out-of-the-box.

9. 📊 Developer Telemetry & Stripe Radar Audit Trail

A comprehensive developer observability layer (src/lib/telemetry.ts) providing a Stripe-grade audit trail:

• Event Logging: Records structured JSON logs for payment, radar_block, job_settlement, and mint_audit into SQLite table agent_telemetry.
• Developer Summary Metrics: Computes totalSpentSats, txCount, and blockedSybilAttacks across configurable timeframes (default: 24h).
• Dual Access: Consumable directly by AI agents via MCP tool get_agent_telemetry and by web dashboards via Next.js REST API GET /api/telemetry.

📜 Protocol Specifications (NIPs, NUTs & MCP)

🛠️ Technology Stack & Architecture

• Framework: Next.js 16 (App Router, Server Components & Streaming SSR)
• Agent Protocols: @modelcontextprotocol/sdk (v1.30+), OpenAI / Google Gemini AI SDK
• Language: TypeScript 5 (Strict type-checking on all cryptographic structures)
• Styling: Tailwind CSS v4, Base UI, Lucide Icons
• Protocol Libraries: nostr-tools (v2.25+), @cashu/cashu-ts (v4.9+), @noble/hashes
• Zero-Buffer Client Engine: Fully decoupled from Node.js Buffer globals using native browser Uint8Array primitives for universal cross-environment compatibility.
• Non-Blocking Resilience: All network queries are wrapped with AbortSignal.timeout() and Promise.race() fallbacks to eliminate UI freezes.

⚡ Quickstart & Local Setup

Prerequisites

• Node.js >= 20.0.0
• npm, pnpm, or yarn

1. Clone & Install

git clone https://github.com/PHONGUIT22/nostrpulse-full.gitcd nostrpulse-fullnpm install

2. Run the Development Server

npm run dev

Open http://localhost:3000 in your browser to explore the live dashboard.

3. Build & Run the MCP Server

# Build the production standalone MCP server bundlenpm run build:mcp
# Launch MCP server locally over stdio JSON-RPCnpx tsx src/mcp-entry.ts
# Or run the published npm package directlynpx -y nostrpulse-mcp

4. Run Verification & Test Suites

# Test Agent Spending Guardrails, Budget Limits & Zero-Config Identitynpx tsx scripts/test-guardrails.ts
# Test Developer Telemetry & Audit Trail data layernpx tsx scripts/test-agent-telemetry.ts
# Test full MCP Stdio JSON-RPC integration (all 10 tools discovered & tested)npx tsx scripts/test-mcp-stdio.ts
# Test NIP-47 NWC payment execution, URI parsing, and timeout guardsnpx tsx scripts/test-nwc-pay.ts
# Test WoT-Gated Cashu Mint Mesh (Testnut & Minibits /v1/info audit & trust verification)npx tsx scripts/test-mint-mesh.ts
# Test autonomous Agent-to-Agent (A2A) Collaborative Mesh (Local SLM / Ollama)npm exec tsx scripts/test-mesh-agent.ts --ollama
# Test A2A Mesh against the published npm package over Stdio JSON-RPCnpm exec tsx scripts/test-mesh-agent.ts --ollama --npm
# Test 5-Stage Autonomous Mini-Agent Showcase (Ollama Minimal Profile or Gemini)npm exec tsx scripts/test-mini-agent.ts --ollama --profile=minimal
# Test self-contained NIP-59 Gift Wrap encryption & decryptionnpx tsx scripts/test-nip59-encryption.ts
# Strict TypeScript type check (zero errors)npx tsc --noEmit

🗺️ Roadmap & Milestones

• Phase 1: Deterministic 5-Pillar Trust Score Engine & Anti-Sybil Damping Guard.
• Phase 2: NIP-57 Lightning Zap integration with WebLN & live receipt streaming.
• Phase 3: NIP-61 NutZap dual-mode engine with NUT-00 V4 CBOR decoding & NIP-44 encryption.
• Phase 4: NIP-65 dynamic relay synchronization & browser WebSocket telemetry.
• Phase 5: NIP-90 Data Vending Machines: Autonomous Trust Score worker bot & decentralized /bounties marketplace.
• Phase 6: 1-Tap Cashu NutZap settlement for deliverable acceptance & instant payout.
• Phase 7: MCP Stdio Server & npm package deployment (nostrpulse-mcp on npm registry).
• Phase 8: NIP-47 Nostr Wallet Connect (NWC) direct Lightning rail for autonomous node settlement.
• Phase 9: WoT-Gated Dynamic Mint Mesh & NUT-06 5-Pillar Counterparty Risk Radar.
• Phase 10: Agent Spending Guardrails (single-tx cap & 24h limits), Zero-Config Identity Bootstrapping & Developer Telemetry Data Layer.
• Phase 11: Autonomous Agent-to-Agent (A2A) Collaborative Mesh, SLM Profiles (--profile=minimal), and Adaptive Spending Fallback.
• Phase 12: Standalone @nostrpulse/sdk with Zero-Buffer RFC 8949 CBOR, Dual Bundle Build, and Unified Test Suite Runner.

⚖️ License & Non-Custodial Disclaimer

Distributed under the MIT License. NostrPulse is strictly non-custodial software: it never generates, stores, or requests user private keys (nsec), nor does it take custody of user funds.