Add MCP server implementation and documentation

MCP-SERVER.md

@@ -0,0 +1,428 @@
+# DeepSite MCP Server
+
+DeepSite is now available as an MCP (Model Context Protocol) server, enabling AI assistants like Claude to create websites directly using natural language.
+
+## Two Ways to Use DeepSite MCP
+
+**Quick Comparison:**
+
+| Feature | Option 1: HTTP Server | Option 2: Local Server |
+|---------|----------------------|------------------------|
+| **Setup Difficulty** | ✅ Easy (just config) | ⚠️ Requires installation |
+| **Authentication** | HF Token in config header | HF Token or session cookie in env |
+| **Best For** | Most users | Developers, custom modifications |
+| **Maintenance** | ✅ Always up-to-date | Need to rebuild for updates |
+
+**Recommendation:** Use Option 1 (HTTP Server) unless you need to modify the MCP server code.
+
+---
+
+### 🌐 Option 1: HTTP Server (Recommended)
+
+**No installation required!** Use DeepSite's hosted MCP server.
+
+#### Setup for Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "deepsite": {
+      "url": "https://deepsite.hf.co/api/mcp",
+      "transport": {
+        "type": "sse"
+      },
+      "headers": {
+        "Authorization": "Bearer hf_your_token_here"
+      }
+    }
+  }
+}
+```
+
+**Getting Your Hugging Face Token:**
+
+1. Go to https://huggingface.co/settings/tokens
+2. Create a new token with `write` access
+3. Copy the token
+4. Add it to the `Authorization` header in your config (recommended for security)
+5. Alternatively, you can pass it as the `hf_token` parameter when using the tool
+
+**⚠️ Security Recommendation:** Use the `Authorization` header in your config instead of passing the token in chat. This keeps your token secure and out of conversation history.
+
+#### Example Usage with Claude
+
+> "Create a portfolio website using DeepSite. Include a hero section, about section, and contact form."
+
+Claude will automatically:
+1. Use the `create_project` tool
+2. Authenticate using the token from your config
+3. Create the website on Hugging Face Spaces
+4. Return the URLs to access your new site
+
+---
+
+### 💻 Option 2: Local Server
+
+Run the MCP server locally for more control or offline use.
+
+> **Note:** Most users should use Option 1 (HTTP Server) instead. Option 2 is only needed if you want to run the MCP server locally or modify its behavior.
+
+#### Installation
+
+```bash
+cd mcp-server
+npm install
+npm run build
+```
+
+#### Setup for Claude Desktop
+
+**Method A: Using HF Token (Recommended)**
+
+```json
+{
+  "mcpServers": {
+    "deepsite-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/deepsite-v3/mcp-server/dist/index.js"],
+      "env": {
+        "HF_TOKEN": "hf_your_token_here",
+        "DEEPSITE_API_URL": "https://deepsite.hf.co"
+      }
+    }
+  }
+}
+```
+
+**Method B: Using Session Cookie (Alternative)**
+
+```json
+{
+  "mcpServers": {
+    "deepsite-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/deepsite-v3/mcp-server/dist/index.js"],
+      "env": {
+        "DEEPSITE_AUTH_COOKIE": "your-session-cookie",
+        "DEEPSITE_API_URL": "https://deepsite.hf.co"
+      }
+    }
+  }
+}
+```
+
+**Getting Your Session Cookie (Method B only):**
+
+1. Log in to https://deepsite.hf.co
+2. Open Developer Tools (F12)
+3. Go to Application → Cookies
+4. Copy the session cookie value
+5. Set as `DEEPSITE_AUTH_COOKIE` in the config
+
+---
+
+## Available Tools
+
+### `create_project`
+
+Creates a new DeepSite project with HTML/CSS/JS files.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | No | Project title (defaults to "DeepSite Project") |
+| `pages` | array | Yes | Array of file objects with `path` and `html` |
+| `prompt` | string | No | Commit message/description |
+| `hf_token` | string | No* | Hugging Face API token (*optional if provided via Authorization header in config) |
+
+**Page Object:**
+```typescript
+{
+  path: string;  // e.g., "index.html", "styles.css", "script.js"
+  html: string;  // File content
+}
+```
+
+**Returns:**
+```json
+{
+  "success": true,
+  "message": "Project created successfully!",
+  "projectUrl": "https://deepsite.hf.co/username/project-name",
+  "spaceUrl": "https://huggingface.co/spaces/username/project-name",
+  "liveUrl": "https://username-project-name.hf.space",
+  "spaceId": "username/project-name",
+  "projectId": "space-id",
+  "files": ["index.html", "styles.css"]
+}
+```
+
+---
+
+## Example Prompts for Claude
+
+### Simple Landing Page
+> "Create a modern landing page for my SaaS product using DeepSite. Include a hero section with CTA, features grid, and footer. Use gradient background."
+
+### Portfolio Website
+> "Build a portfolio website with DeepSite. I need:
+> - Hero section with my name and photo
+> - Projects gallery with 3 sample projects
+> - Skills section with tech stack
+> - Contact form
+> Use dark mode with accent colors."
+
+### Blog Homepage
+> "Create a blog homepage using DeepSite. Include:
+> - Header with navigation
+> - Featured post section
+> - Grid of recent posts (3 cards)
+> - Sidebar with categories
+> - Footer with social links
+> Clean, minimal design."
+
+### Interactive Dashboard
+> "Make an analytics dashboard with DeepSite:
+> - Sidebar navigation
+> - 4 metric cards at top
+> - 2 chart placeholders
+> - Data table
+> - Modern, professional UI with charts.css"
+
+---
+
+## Direct API Usage
+
+You can also call the HTTP endpoint directly:
+
+### Using Authorization Header (Recommended)
+
+```bash
+curl -X POST https://deepsite.hf.co/api/mcp \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer hf_your_token_here" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "create_project",
+      "arguments": {
+        "title": "My Website",
+        "pages": [
+          {
+            "path": "index.html",
+            "html": "<!DOCTYPE html><html><head><title>Hello</title></head><body><h1>Hello World!</h1></body></html>"
+          }
+        ]
+      }
+    }
+  }'
+```
+
+### Using Token Parameter (Fallback)
+
+```bash
+curl -X POST https://deepsite.hf.co/api/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "create_project",
+      "arguments": {
+        "title": "My Website",
+        "pages": [
+          {
+            "path": "index.html",
+            "html": "<!DOCTYPE html><html><head><title>Hello</title></head><body><h1>Hello World!</h1></body></html>"
+          }
+        ],
+        "hf_token": "hf_xxxxx"
+      }
+    }
+  }'
+```
+
+### List Available Tools
+
+```bash
+curl -X POST https://deepsite.hf.co/api/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/list",
+    "params": {}
+  }'
+```
+
+---
+
+## Testing
+
+### Test Local Server
+
+```bash
+cd mcp-server
+./test.sh
+```
+
+### Test HTTP Server
+
+```bash
+curl -X POST https://deepsite.hf.co/api/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+---
+
+## Migration Guide: From Parameter to Header Auth
+
+If you're currently passing the token as a parameter in your prompts, here's how to migrate to the more secure header-based authentication:
+
+### Step 1: Update Your Config
+
+Edit your Claude Desktop config file and add the `headers` section:
+
+```json
+{
+  "mcpServers": {
+    "deepsite": {
+      "url": "https://deepsite.hf.co/api/mcp",
+      "transport": {
+        "type": "sse"
+      },
+      "headers": {
+        "Authorization": "Bearer hf_your_actual_token_here"
+      }
+    }
+  }
+}
+```
+
+### Step 2: Restart Claude Desktop
+
+Completely quit and restart Claude Desktop for the changes to take effect.
+
+### Step 3: Use Simpler Prompts
+
+Now you can simply say:
+> "Create a portfolio website with DeepSite"
+
+Instead of:
+> "Create a portfolio website with DeepSite using token `hf_xxxxx`"
+
+Your token is automatically included in all requests via the header!
+
+---
+
+## Security Notes
+
+### HTTP Server (Option 1)
+- **✅ Recommended:** Store your HF token in the `Authorization` header in your Claude Desktop config
+- The token is stored locally on your machine and never exposed in chat
+- The token is sent with each request but only used to authenticate with Hugging Face API
+- DeepSite does not store your token
+- Use tokens with minimal required permissions (write access to spaces)
+- You can revoke tokens anytime at https://huggingface.co/settings/tokens
+- **⚠️ Fallback:** You can still pass the token as a parameter, but this is less secure as it appears in conversation history
+
+### Local Server (Option 2)
+- Use `HF_TOKEN` environment variable (same security as Option 1)
+- Or use `DEEPSITE_AUTH_COOKIE` if you prefer session-based auth
+- All authentication data stays on your local machine
+- Better for development and testing
+- No need for both HTTP Server and Local Server - choose one!
+
+---
+
+## Troubleshooting
+
+### "Invalid Hugging Face token"
+- Verify your token at https://huggingface.co/settings/tokens
+- Ensure the token has write permissions
+- Check that you copied the full token (starts with `hf_`)
+
+### "At least one page is required"
+- Make sure you're providing the `pages` array
+- Each page must have both `path` and `html` properties
+
+### "Failed to create project"
+- Check your token permissions
+- Ensure the project title doesn't conflict with existing spaces
+- Verify your Hugging Face account is in good standing
+
+### Claude doesn't see the tool
+- Restart Claude Desktop after modifying the config
+- Check that the JSON config is valid (no trailing commas)
+- For HTTP: verify the URL is correct
+- For local: check the absolute path to index.js
+
+---
+
+## Architecture
+
+### HTTP Server Flow
+```
+Claude Desktop
+      ↓
+ (HTTP Request)
+      ↓
+deepsite.hf.co/api/mcp
+      ↓
+Hugging Face API (with user's token)
+      ↓
+New Space Created
+      ↓
+URLs returned to Claude
+```
+
+### Local Server Flow
+```
+Claude Desktop
+      ↓
+ (stdio transport)
+      ↓
+Local MCP Server
+      ↓
+ (HTTP to DeepSite API)
+      ↓
+deepsite.hf.co/api/me/projects
+      ↓
+New Space Created
+```
+
+---
+
+## Contributing
+
+The MCP server implementation lives in:
+- HTTP Server: `/app/api/mcp/route.ts`
+- Local Server: `/mcp-server/index.ts`
+
+Both use the same core DeepSite logic for creating projects - no duplication!
+
+---
+
+## License
+
+MIT
+
+---
+
+## Resources
+
+- [Model Context Protocol Spec](https://modelcontextprotocol.io/)
+- [DeepSite Documentation](https://deepsite.hf.co)
+- [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces)
+- [Claude Desktop](https://claude.ai/desktop)
+

app/api/mcp/route.ts

@@ -0,0 +1,366 @@
+import { NextRequest, NextResponse } from "next/server";
+import { RepoDesignation, createRepo, uploadFiles, spaceInfo, listCommits } from "@huggingface/hub";
+import { COLORS } from "@/lib/utils";
+import { injectDeepSiteBadge, isIndexPage } from "@/lib/inject-badge";
+import { Commit, Page } from "@/types";
+
+interface MCPRequest {
+  jsonrpc: "2.0";
+  id: number | string;
+  method: string;
+  params?: any;
+}
+
+interface MCPResponse {
+  jsonrpc: "2.0";
+  id: number | string;
+  result?: any;
+  error?: {
+    code: number;
+    message: string;
+    data?: any;
+  };
+}
+
+interface CreateProjectParams {
+  title?: string;
+  pages: Page[];
+  prompt?: string;
+  hf_token?: string; // Optional - can come from header instead
+}
+
+// MCP Server over HTTP
+export async function POST(req: NextRequest) {
+  try {
+    const body: MCPRequest = await req.json();
+    const { jsonrpc, id, method, params } = body;
+
+    // Validate JSON-RPC 2.0 format
+    if (jsonrpc !== "2.0") {
+      return NextResponse.json({
+        jsonrpc: "2.0",
+        id: id || null,
+        error: {
+          code: -32600,
+          message: "Invalid Request: jsonrpc must be '2.0'",
+        },
+      });
+    }
+
+    let response: MCPResponse;
+
+    switch (method) {
+      case "initialize":
+        response = {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: {
+              tools: {},
+            },
+            serverInfo: {
+              name: "deepsite-mcp-server",
+              version: "1.0.0",
+            },
+          },
+        };
+        break;
+
+      case "tools/list":
+        response = {
+          jsonrpc: "2.0",
+          id,
+          result: {
+            tools: [
+              {
+                name: "create_project",
+                description: `Create a new DeepSite project. This will create a new Hugging Face Space with your HTML/CSS/JS files.
+
+Example usage:
+- Create a simple website with HTML, CSS, and JavaScript files
+- Each page needs a 'path' (filename like "index.html", "styles.css", "script.js") and 'html' (the actual content)
+- The title will be formatted to a valid repository name
+- Returns the project URL and metadata`,
+                inputSchema: {
+                  type: "object",
+                  properties: {
+                    title: {
+                      type: "string",
+                      description: "Project title (optional, defaults to 'DeepSite Project'). Will be formatted to a valid repo name.",
+                    },
+                    pages: {
+                      type: "array",
+                      description: "Array of files to include in the project",
+                      items: {
+                        type: "object",
+                        properties: {
+                          path: {
+                            type: "string",
+                            description: "File path (e.g., 'index.html', 'styles.css', 'script.js')",
+                          },
+                          html: {
+                            type: "string",
+                            description: "File content",
+                          },
+                        },
+                        required: ["path", "html"],
+                      },
+                    },
+                    prompt: {
+                      type: "string",
+                      description: "Optional prompt/description for the commit message",
+                    },
+                    hf_token: {
+                      type: "string",
+                      description: "Hugging Face API token (optional if provided via Authorization header)",
+                    },
+                  },
+                  required: ["pages"],
+                },
+              },
+            ],
+          },
+        };
+        break;
+
+      case "tools/call":
+        const { name, arguments: toolArgs } = params;
+
+        if (name === "create_project") {
+          try {
+            // Extract token from Authorization header if present
+            const authHeader = req.headers.get("authorization");
+            let hf_token = toolArgs.hf_token;
+            
+            if (authHeader && authHeader.startsWith("Bearer ")) {
+              hf_token = authHeader.substring(7); // Remove "Bearer " prefix
+            }
+            
+            const result = await handleCreateProject({
+              ...toolArgs,
+              hf_token,
+            } as CreateProjectParams);
+            response = {
+              jsonrpc: "2.0",
+              id,
+              result,
+            };
+          } catch (error: any) {
+            response = {
+              jsonrpc: "2.0",
+              id,
+              error: {
+                code: -32000,
+                message: error.message || "Failed to create project",
+                data: error.data,
+              },
+            };
+          }
+        } else {
+          response = {
+            jsonrpc: "2.0",
+            id,
+            error: {
+              code: -32601,
+              message: `Unknown tool: ${name}`,
+            },
+          };
+        }
+        break;
+
+      default:
+        response = {
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32601,
+            message: `Method not found: ${method}`,
+          },
+        };
+    }
+
+    return NextResponse.json(response);
+  } catch (error: any) {
+    return NextResponse.json({
+      jsonrpc: "2.0",
+      id: null,
+      error: {
+        code: -32700,
+        message: "Parse error",
+        data: error.message,
+      },
+    });
+  }
+}
+
+// Handle OPTIONS for CORS
+export async function OPTIONS() {
+  return new NextResponse(null, {
+    status: 200,
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type",
+    },
+  });
+}
+
+async function handleCreateProject(params: CreateProjectParams) {
+  const { title: titleFromRequest, pages, prompt, hf_token } = params;
+
+  // Validate required parameters
+  if (!hf_token || typeof hf_token !== "string") {
+    throw new Error("hf_token is required and must be a string");
+  }
+
+  if (!pages || !Array.isArray(pages) || pages.length === 0) {
+    throw new Error("At least one page is required");
+  }
+
+  // Validate that each page has required fields
+  for (const page of pages) {
+    if (!page.path || !page.html) {
+      throw new Error("Each page must have 'path' and 'html' properties");
+    }
+  }
+
+  // Get user info from HF token
+  let username: string;
+  try {
+    const userResponse = await fetch("https://huggingface.co/api/whoami-v2", {
+      headers: {
+        Authorization: `Bearer ${hf_token}`,
+      },
+    });
+
+    if (!userResponse.ok) {
+      throw new Error("Invalid Hugging Face token");
+    }
+
+    const userData = await userResponse.json();
+    username = userData.name;
+  } catch (error: any) {
+    throw new Error(`Authentication failed: ${error.message}`);
+  }
+
+  const title = titleFromRequest ?? "DeepSite Project";
+
+  const formattedTitle = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .split("-")
+    .filter(Boolean)
+    .join("-")
+    .slice(0, 96);
+
+  const repo: RepoDesignation = {
+    type: "space",
+    name: `${username}/${formattedTitle}`,
+  };
+
+  const colorFrom = COLORS[Math.floor(Math.random() * COLORS.length)];
+  const colorTo = COLORS[Math.floor(Math.random() * COLORS.length)];
+  const README = `---
+title: ${title}
+colorFrom: ${colorFrom}
+colorTo: ${colorTo}
+emoji: 🐳
+sdk: static
+pinned: false
+tags:
+  - deepsite-v3
+---
+
+# Welcome to your new DeepSite project!
+This project was created with [DeepSite](https://deepsite.hf.co).
+`;
+
+  const files: File[] = [];
+  const readmeFile = new File([README], "README.md", { type: "text/markdown" });
+  files.push(readmeFile);
+
+  pages.forEach((page: Page) => {
+    // Determine MIME type based on file extension
+    let mimeType = "text/html";
+    if (page.path.endsWith(".css")) {
+      mimeType = "text/css";
+    } else if (page.path.endsWith(".js")) {
+      mimeType = "text/javascript";
+    } else if (page.path.endsWith(".json")) {
+      mimeType = "application/json";
+    }
+
+    // Inject the DeepSite badge script into index pages only
+    const content = mimeType === "text/html" && isIndexPage(page.path) 
+      ? injectDeepSiteBadge(page.html) 
+      : page.html;
+    const file = new File([content], page.path, { type: mimeType });
+    files.push(file);
+  });
+
+  try {
+    const { repoUrl } = await createRepo({
+      repo,
+      accessToken: hf_token,
+    });
+
+    const commitTitle = !prompt || prompt.trim() === "" ? "Initial project creation via MCP" : prompt;
+    
+    await uploadFiles({
+      repo,
+      files,
+      accessToken: hf_token,
+      commitTitle,
+    });
+
+    const path = repoUrl.split("/").slice(-2).join("/");
+
+    const commits: Commit[] = [];
+    for await (const commit of listCommits({ repo, accessToken: hf_token })) {
+      if (commit.title.includes("initial commit") || commit.title.includes("image(s)") || commit.title.includes("Promote version")) {
+        continue;
+      }
+      commits.push({
+        title: commit.title,
+        oid: commit.oid,
+        date: commit.date,
+      });
+    }
+
+    const space = await spaceInfo({
+      name: repo.name,
+      accessToken: hf_token,
+    });
+
+    const projectUrl = `https://deepsite.hf.co/${path}`;
+    const spaceUrl = `https://huggingface.co/spaces/${path}`;
+    const liveUrl = `https://${username}-${formattedTitle}.hf.space`;
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              success: true,
+              message: "Project created successfully!",
+              projectUrl,
+              spaceUrl,
+              liveUrl,
+              spaceId: space.name,
+              projectId: space.id,
+              files: pages.map((p) => p.path),
+              updatedAt: space.updatedAt,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  } catch (err: any) {
+    throw new Error(err.message || "Failed to create project");
+  }
+}
+