# [MCPay Build](https://mcpay.tech/build)

<img src="./assets/mcpay-hero-painting.png" alt="MCPay Build Banner" width="600">

**[MCPay](https://mcpay.tech) Build** is an **MCP server that acts as a no-code builder for MCP Servers** with built-in monetization.  
It lets developers design, preview, and deploy MCP servers to GitHub + Vercel — and instantly monetize tool usage with **x402 micropayments** via [MCPay](https://mcpay.tech).  

👉 **Build → Preview → Deploy → Monetize**

Our vision is an **agent-to-agent economy** powered by microtransactions, where AI agents can autonomously pay to use tools. [MCPay](https://mcpay.tech) Build provides the rails to make that future possible.  

---

## 🖼️ Workflow

```

┌───────────┐      ┌───────────┐      ┌───────────┐      ┌───────────────┐
│   Build   │ ───▶ │  Preview  │ ───▶ │  Deploy   │ ───▶ │   Monetize    │
│ (AI/MCP)  │      │ (sandbox) │      │ (Vercel)  │      │ (MCPay/x402)  │
└───────────┘      └───────────┘      └───────────┘      └───────────────┘

````

---

# Big Picture

This repo implements an **MCP server “factory”**:

- Lets an AI/chat (or you) **spin up a brand-new MCP server** in memory.  
- Provides **tools** to edit files, manage deps, run type checks, format, version, and preview live.  
- Deploys your server into a **real Node.js environment** using **Vercel Sandbox**.  
- Monetizes expensive operations (`preview`, `run_command`, `stream_logs`, etc.) using **[MCPay](https://mcpay.tech)** (per-call x402 micropayments).  

Flow:  
**Create session → edit files → preview in sandbox → get live URL → iterate → export as ZIP → monetize tools.**

---

## ✨ Features

- **[MCPay](https://mcpay.tech) integration** → free + paid tools side-by-side, billed automatically  
- **Simple API** → `server.tool(...)` & `server.paidTool(...)` via `mcpay/handler`  
- **Vercel-ready** → `vercel.json` + function exports (`GET/POST/OPTIONS`)  
- **Type-safe** → modern TypeScript + Zod validation  
- **Dev UX** → session/file/diff/format tools, `ts-check`, logs, live preview  

---

## 🚀 Quickstart

### 1. Install dependencies
```bash
pnpm install
````

### 2. Configure environment

```bash
MCPAY_API_KEY=your_api_key     # required for paid tools
MCPAY_API_URL=https://api.mcpay.tech  # optional
```

### 3. Run locally

```bash
pnpm dlx vercel dev
```

Server runs at `http://localhost:3000`.

### 4. Connect from MCP client

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mcpay-local": { "url": "http://localhost:3000" }
  }
}
```

---

# Under the Hood

## Main runtime & routing

* **Hono** as the HTTP framework.
* **Open CORS** (all origins/headers/methods allowed).
* `GET /` → serves a **system prompt** describing tools + philosophy.
* All other routes → handled by `createPaidMcpHandler(...)`.
* Function exports (`GET/POST/OPTIONS`) → deploys cleanly to Vercel.

---

## State & storage

* **Sessions** in Vercel KV (`session:{id}`) with virtual file system + sandbox metadata.
* **Commits** in KV (`commit:{session}:{commit}`) for full snapshots.
* **Logs/ZIPs** uploaded to Vercel Blob with public URLs.

---

## Templates & defaults

When you run `create_session`, it seeds:

* `index.ts` — MCP server template (with `hello` + `get-time` tools).
* `package.json`, `tsconfig.json`, `.gitignore`, `.env.example`, `README.md`.

---

## Preview = live sandbox

`preview` tool does:

1. Loads session + hashes files.
2. Reuses existing sandbox if files unchanged (<30 min).
3. Else:

   * Creates fresh Vercel Sandbox (Node 22, 2 vCPUs).
   * Uploads files.
   * Detects Node/npm versions.
   * Installs deps (npm/yarn/pnpm).
   * Runs build if available.
   * Starts server (`npm start` or fallback).
   * Health-checks endpoints until ready.
   * Aggregates logs (uploads long logs to Blob).

Returns: sandbox ID, preview URL, logs, node/npm versions, status.

---

## Built-in Tools

**Paid (metered via [MCPay](https://mcpay.tech))**

* `create_session` — bootstrap project
* `preview` — deploy to sandbox, return live URL
* `download_session` — zip + upload project
* `run_command` — exec arbitrary shell in sandbox
* `stream_logs` — live-tail logs

**Free**

* File ops: `add_or_update_file`, `delete_file`, `get_file`, `list_files`, `get_all_codebase`
* Env ops: `add_env_key`, `list_env_keys`, `delete_env_key`
* Package ops: `add_dependency`, `debug_package_json`
* Quality: `ts_check`, `npm_audit`, `format_file`
* Versioning: `commit`, `diff`, `revert`, `get_logs`
* Info: `get_environment_info`, `get_session_stats`, `stop_preview`, `force_refresh_sandbox`

---

## Monetization

* MCP handler is created with `createPaidMcpHandler`.
* Paid tools have explicit `{ price, currency }`.
* Requires `MCPAY_API_KEY` (and optional `MCPAY_API_URL`).

Example:

```ts
server.paidTool(
  "analyze-data",
  "Analyze data (paid)",
  { price: 0.1, currency: "USD" },
  { data: z.string(), format: z.enum(["json","csv"]) },
  async ({ data, format }) => ({
    content: [{ type: "text", text: `Analyzed ${format} data` }]
  })
);
```

---

## 🛠 Typical Flow

1. `create_session` → new ID
2. `add_or_update_file` → edit `index.ts`
3. `ts_check` + `format_file`
4. `commit` → snapshot
5. `preview` → live sandbox URL
6. `stream_logs` → monitor in real time
7. `download_session` → zip/export

---

## 📦 Deployment

Deploy to Vercel:

```bash
pnpm dlx vercel
```

Set env vars in project settings:

* `MCPAY_API_KEY`
* `MCPAY_API_URL` (optional)

---

## ❗ Notes

* **Blob uploads are public** → don’t commit secrets.
* **Sandbox per tool** (for some ops) → isolation at cost of speed/\$\$.
* **.env handling** → only keys are tracked; actual secrets must be set in runtime env.

---

## 📄 License

MIT