<p align="center">
  <img src="logo/withtext.webp" alt="Pastebase Logo" width="280" />
</p>

# Pastebase Model Context Protocol (MCP) Server

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/Protocol-MCP-green.svg" alt="Protocol" /></a>
  <a href="https://www.pastebase.site"><img src="https://img.shields.io/badge/Website-pastebase.site-purple.svg" alt="Website" /></a>
</p>

An official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) stdio server that connects your local AI coding assistants—like **Cursor IDE**, **Claude Desktop**, and **Cline**—to the **[Pastebase](https://www.pastebase.site)** extraction engine. 

With this server active, your AI assistant can programmatically crawl, audit, and absorb the design systems, color tokens, typography scales, sitemaps, and copywriting guide of any live website. This feeds highly accurate, real-world context directly into your code generation windows.

```
┌──────────────────┐         ┌──────────────┐         ┌────────────────────┐
│ AI Assistant     │ ──────> │  Local MCP   │ ──────> │ Pastebase API      │
│ (Cursor/Claude)  │ <────── │  Server      │ <────── │ https://pastebase  │
└──────────────────┘         └──────────────┘         └────────────────────┘
```

---

## ✨ Features

- **Semantic Extraction**: Extracts style variables, design parameters, layouts, and copy hierarchies from any live HTTP/HTTPS URL in under 30 seconds.
- **Three Specialized Output Modes**:
  - `brand`: Color tokens, active typography weights, voice description, target audience, and messaging guardrails.
  - `copy`: High-fidelity copy blocks organized by page layout sections to preserve copy during migrations.
  - `structure`: Structural outline, head outline (H1-H6 outline), navigation trees, and footer links.
- **Deep Scrape Support**: Crawl a single page or automatically follow local sub-links (up to 5 pages) to merge sitemaps and guide layouts.

---

## 📋 Prerequisites

1. **Node.js**: Installed on your machine (v18.0.0 or higher recommended).
2. **Pastebase API Key**: An active developer key. You can generate one inside your [Pastebase Developer Dashboard](https://pastebase.site/developer).

---

## 🚀 Setup & Installation

First, clone this repository locally (or download the source directory) to a path on your machine (e.g., `C:/developer/pastebase-mcp` or `/Users/name/developer/pastebase-mcp`).

Navigate into the directory and install the required dependencies:

```bash
cd pastebase-mcp
npm install
```

---

## ⚙️ Configuration Guides

### 1. Configure in Cursor IDE

To integrate the tool into Cursor:
1. Open **Cursor Settings** -> **Features** -> **MCP**.
2. Click **+ Add New MCP Server**.
3. Configure the settings:
   - **Name**: `pastebase`
   - **Type**: `stdio`
   - **Command**: `node C:/path/to/pastebase-mcp/index.js` *(Note: Replace with the actual absolute path to index.js on your machine, using forward slashes `/`)*.
4. Under Environment Variables:
   - Key: `PASTEBASE_API_KEY`, Value: `your_pb_live_api_key_here`
   - Key: `PASTEBASE_API_URL`, Value: `https://pastebase.site`
5. Click **Save**.

---

### 2. Configure in Claude Desktop

Open your Claude Desktop configuration file. This file is usually located at:
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the `pastebase` server configuration to the `mcpServers` object:

```json
{
  "mcpServers": {
    "pastebase": {
      "command": "node",
      "args": ["C:/absolute/path/to/pastebase-mcp/index.js"],
      "env": {
        "PASTEBASE_API_KEY": "your_pb_live_api_key_here",
        "PASTEBASE_API_URL": "https://pastebase.site"
      }
    }
  }
}
```
*(Make sure to use absolute paths with forward slashes `/` on Windows).*

Restart Claude Desktop. You will see a new tool icon active in the prompt input field.

---

### 3. Configure in Cline (VS Code Extension)

Open the configuration file for Cline, typically located at:
* **Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
* **macOS**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

Append the `pastebase` object to the `mcpServers` object in the JSON file.

---

## 🛠️ Tool Reference

### `pastebase_extract`
Extracts design specs, sitemaps, or text copy from a target website.

#### Arguments

| Argument | Type | Required | Description |
|---|---|---|---|
| `url` | string | **Yes** | The absolute HTTP/HTTPS URL of the website to scrape (e.g. `https://stripe.com`). |
| `mode` | string | No | The extraction target. Options: <br> • `brand` (default): Extracts colors, fonts, tone, CTAs. <br> • `copy`: Extracts page copy by section. <br> • `structure`: Extracts sitemap sitemaps and outlines. |
| `scope` | string | No | Crawl depth. Options: <br> • `page` (default): Scrapes target homepage. <br> • `site`: Crawls up to 5 sublinks in parallel. |

---

## 💬 Prompt Examples

Once configured, your AI assistant can use the tool automatically when you prompt it to analyze websites. Here are examples:

* **UI Redesign**:
  > *"Use pastebase to fetch the brand guidelines for https://linear.app, and then write a React Tailwind landing page component matching their color system and font pairings."*

* **Copy Migration**:
  > *"Can you scrape the text copy from https://stripe.com/payments using the `copy` mode on pastebase, and summarize their primary value proposition?"*

* **Site Architecture Audit**:
  > *"Run a `site` scope sitemap audit on https://notion.so using pastebase, and map out their main navigation page structure."*

---

## 🔍 Troubleshooting & Logging

If the tool fails or does not appear in your editor:

1. **Verify Absolute Paths**: Ensure the path in your config points directly to `index.js` and that you used forward slashes (`/`), even on Windows.
2. **Inspect Claude Desktop Logs**:
   * **Windows**: Check files under `%APPDATA%\Claude\logs\`
   * **macOS**: Run `tail -f ~/Library/Logs/Claude/mcp*.log` in your terminal to see real-time error logging.
3. **Verify API Key**: Confirm your Pastebase API Key is copied correctly and has not been revoked.

---

## 🛡️ Security & Privacy Notice
- The MCP server only executes actions when explicitly prompted.
- All requests are securely routed over HTTPS.
- Pastebase respects standard `robots.txt` specifications and checks requests against standard Private Subnet and SSRF protection lists.

---

## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.