比特币MCP服务平台

btc-mcp/
├── README.md                  # Project overview
├── DIRECTORY_GUIDE.md         # This file
├── backend/                   # FastAPI backend (Python)
├── frontend/                  # Next.js frontend (TypeScript/React)
└── pip/                       # Publishable Python package (btc-mcp)

backend/
├── server.py                          # Entry point — runs uvicorn on src.app:app
├── .env                               # Environment variables (secrets, DB URIs)
├── builds/                            # Docker build contexts (one dir per deployed MCP server)
│   └── <uuid>/                        # Each deployed server gets a unique UUID folder
├── venv/                              # Python virtual environment
└── src/
    ├── __init__.py
    ├── app.py                         # FastAPI app factory, CORS, router registration, lifespan
    ├── database/
    │   ├── __init__.py
    │   ├── mongo.py                   # MongoDB connection (AsyncMongoClient), get_db()
    │   ├── redis.py                   # Redis async client instance
    │   └── embed.py                   # SentenceTransformer embeddings (all-MiniLM-L6-v2)
    ├── l402/
    │   ├── __init__.py
    │   └── l402.py                    # L402 payment offers, Lightning invoice creation, USD↔sats
    ├── middleware/
    │   ├── __init__.py
    │   └── middleware.py              # Auth middleware — creator_session (JWT) & user_session (Bearer)
    ├── routes/
    │   ├── agents.py                  # GET /api/agents — list/search agents (vector + text search)
    │   ├── creator.py                 # /creator/* — LNURL-auth sign-in, session polling, JWT cookies
    │   ├── mcp_client.py             # /ws/chat/<id> — WebSocket MCP client, Anthropic chat loop
    │   ├── mcp_server.py             # POST /api/deploy — upload & deploy MCP servers in Docker
    │   ├── payments.py                # /api/payments/* — top-up, stake, withdraw, verify payments
    │   └── user.py                    # /user/user-signin — anonymous user creation (UUID-based)
    ├── scripts/
    │   ├── __init__.py
    │   ├── requirements.txt           # Script-specific dependencies
    │   ├── server.py                  # Standalone script server
    │   ├── create_test_data.py        # Seed test agents into MongoDB
    │   ├── test_data.json             # Sample agent data
    │   ├── test_lnurl_callback.py     # LNURL callback testing
    │   ├── test_payment_request.py    # Payment flow testing
    │   └── test_websocket_chat.py     # WebSocket chat testing
    └── utils/
        ├── __init__.py
        └── logging.py                # Shared logger configuration

frontend/
├── package.json                       # Dependencies & scripts
├── next.config.ts                     # Next.js configuration
├── tsconfig.json                      # TypeScript configuration
├── eslint.config.mjs                  # ESLint config
├── postcss.config.mjs                 # PostCSS (Tailwind) config
├── next-env.d.ts                      # Next.js type declarations
├── app/
│   ├── layout.tsx                     # Root layout — font, Navbar, AuthProvider, session check
│   ├── page.tsx                       # Landing page — hero section with city image
│   ├── globals.css                    # Global styles (Tailwind)
│   ├── not-found.tsx                  # 404 page
│   ├── chat/
│   │   └── [slug]/
│   │       └── page.tsx               # Chat interface with a specific agent
│   ├── create/
│   │   └── page.tsx                   # Deploy a new MCP server (file upload form)
│   ├── explore/
│   │   ├── page.tsx                   # Browse & search agents
│   │   └── [slug]/
│   │       └── page.tsx               # Agent detail page
│   └── payments/
│       └── page.tsx                   # Top-up credits / payment management
├── components/
│   ├── AgentCard.tsx                  # Agent preview card (explore grid)
│   ├── AgentDetails.tsx               # Full agent details view
│   ├── AgentView.tsx                  # Agent page wrapper
│   ├── AuthContext.tsx                # React context for creator auth state
│   ├── HeroButton.tsx                 # Animated CTA button on landing page
│   ├── Loader.tsx                     # Loading spinner
│   └── Navbar.tsx                     # Top navigation bar
├── hooks/                             # Custom React hooks (empty)
├── lib/
│   └── utils.js                       # Shared utility functions
├── types/
│   └── global.d.ts                    # Global TypeScript type declarations
└── public/
    └── assets/
        └── images/                    # Static images (icons, backgrounds)

pip/
├── setup.py                           # Package metadata & install config (name: btc-mcp)
├── requirements.txt                   # Runtime dependencies
├── README.md                          # Package documentation
├── LICENSE.txt                        # MIT License
├── MANIFEST.in                        # Files to include in distribution
└── src/
    ├── example.py                     # Example usage with LangGraph ReAct agent
    ├── Penguins.txt                   # Sample data file for the example
    └── btc_mcp/
        ├── __init__.py
        ├── tools.py                   # LangChain tools: search_agents, start_chat,
        │                              #   continue_chat, end_chat, top_up, get_max_spend
        └── lightspark_client.py       # Lightspark wrapper — pay_invoice, spending limits

from btc_mcp.tools import BTC_MCP_TOOLS, init_lightspark_client

init_lightspark_client(client_id, secret, node_id, node_password)

# Use BTC_MCP_TOOLS with any LangChain-compatible agent
agent = create_react_agent(model=llm, tools=BTC_MCP_TOOLS)

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (Next.js)                       │
│         Browse · Deploy · Chat · Pay · Stake                    │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTP / WebSocket
┌──────────────────────────▼──────────────────────────────────────┐
│                     Backend (FastAPI + Uvicorn)                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  ┌───────────────┐  │
│  │  Agents  │  │  MCP     │  │ Payments  │  │  Creator Auth │  │
│  │  Search  │  │  Client  │  │ (L402)    │  │  (LNURL/JWT)  │  │
│  └────┬─────┘  └────┬─────┘  └─────┬─────┘  └───────────────┘  │
│       │              │              │                            │
│  ┌────▼──────────────▼──────────────▼────────────────────────┐  │
│  │  MongoDB (agents, users, creators, stakes)                │  │
│  │  Redis (LNURL challenges, ephemeral state)                │  │
│  │  Sentence-Transformers (vector search embeddings)         │  │
│  └───────────────────────────────────────────────────────────┘  │
│                           │                                     │
│              ┌────────────▼────────────┐                        │
│              │  Docker Containers      │                        │
│              │  (Deployed MCP Servers)  │                        │
│              │  FastMCP + Uvicorn       │                        │
│              └─────────────────────────┘                        │
└─────────────────────────┬───────────────────────────────────────┘
                          │ Lightning Network
              ┌───────────▼───────────┐
              │   Lightspark Node     │
              │   (Bitcoin/Lightning) │
              └───────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│               pip package (btc-mcp)                             │
│  Python client for programmatic agent interaction               │
│  LangChain tools + Lightspark auto-payments                     │
│  Connects to Backend via HTTP + WebSocket                       │
└─────────────────────────────────────────────────────────────────┘