# Cloudflare SYWO MCP Server

A minimal Model Context Protocol (MCP) server that lets MCP-compatible clients query a Cloudflare D1 database. Designed for easy setup and usage.

## Features

- **List tables** in the target D1 database with the `d1_list_tables` tool.
- **Run arbitrary SQL queries** using the `d1_query` tool.
- Lightweight TypeScript implementation relying on Cloudflare's REST API.
- **Cross-platform support** with proper Windows, macOS, and Linux compatibility.
- **Secure credential management** via environment variables.

## Prerequisites

- Node.js 18+
- Cloudflare Account ID
- Cloudflare D1 Database ID
- Cloudflare D1 Database Name
- Cloudflare API Token with `D1:Edit` permissions

## Quick Start (5 Minutes)

1. **Install the server:**
   ```bash
   npm install -g cloudflare-sywo-mcp-server
   ```

2. **Get your Cloudflare credentials** (takes 2 minutes):
   - Account ID: Cloudflare Dashboard → Right sidebar
   - Database ID: Cloudflare Dashboard → D1 → Your database → "Database ID"
   - Database Name: The name you gave your D1 database  
   - API Token: Cloudflare Dashboard → My Profile → API Tokens → Create Token → Custom token with `D1:Edit` permission

3. **Add to VS Code** (copy-paste into settings.json):
   ```json
   {
     "mcp.servers": {
       "cloudflare-d1": {
         "command": "cloudflare-sywo-mcp",
         "args": ["--stdio"],
         "env": {
           "CLOUDFLARE_ACCOUNT_ID": "your-account-id-here",
           "CLOUDFLARE_D1_DATABASE_ID": "your-database-id-here", 
           "CLOUDFLARE_D1_DATABASE_NAME": "your-database-name-here",
           "CLOUDFLARE_API_TOKEN": "your-api-token-here"
         }
       }
     }
   }
   ```

4. **Restart VS Code** and you're done!

## Installation

```bash
npm install -g cloudflare-sywo-mcp-server
```

## Setup

### Option 1: Global Installation (Recommended)
After installing globally with `npm install -g cloudflare-sywo-mcp-server`, you can use it directly in your MCP configuration.

### Option 2: Local Development/Custom Build
If you want to build from source or modify the server:

1. Clone or download this repository
2. Install dependencies:
   ```bash
   npm install
   ```

3. Create a `.env` file (do **not** commit it) and provide credentials:
   ```ini
   CLOUDFLARE_ACCOUNT_ID=your-account-id-here
   CLOUDFLARE_D1_DATABASE_ID=your-database-id-here
   CLOUDFLARE_D1_DATABASE_NAME=your-database-name-here
   CLOUDFLARE_API_TOKEN=your-api-token-here
   ```

4. Build the TypeScript project:
   ```bash
   npm run build
   ```

5. Start the MCP server:
   ```bash
   npm start
   ```

   Or use the development runner:
   ```bash
   npm run dev
   ```

## MCP Client Configuration

### VS Code Setup (Step-by-Step)

**For VS Code users, here's exactly what to do:**

1. **Install the MCP server globally:**
   ```bash
   npm install -g cloudflare-sywo-mcp-server
   ```

2. **Find your VS Code MCP settings file:**
   - Open VS Code Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
   - Type "Open User Settings (JSON)"
   - Look for or create the file: `%APPDATA%\Code\User\settings.json` (Windows) or `~/.config/Code/User/settings.json` (Mac/Linux)

3. **Add the MCP configuration to your settings.json:**

   **Option A: Direct Environment Variables (Recommended)**
   ```json
   {
     "mcp.servers": {
       "cloudflare-d1": {
         "command": "cloudflare-sywo-mcp",
         "args": ["--stdio"],
         "env": {
           "CLOUDFLARE_ACCOUNT_ID": "your-actual-account-id",
           "CLOUDFLARE_D1_DATABASE_ID": "your-actual-database-id", 
           "CLOUDFLARE_D1_DATABASE_NAME": "your-actual-database-name",
           "CLOUDFLARE_API_TOKEN": "your-actual-api-token"
         }
       }
     }
   }
   ```

   **Option B: Using .env File**
   ```json
   {
     "mcp.servers": {
       "cloudflare-d1": {
         "command": "cloudflare-sywo-mcp",
         "args": ["--stdio"],
         "cwd": "C:/path/to/your/project/folder"
       }
     }
   }
   ```

4. **Where to get your Cloudflare credentials:**
   - **Account ID**: Cloudflare Dashboard → Right sidebar under "Account ID"
   - **Database ID**: Cloudflare Dashboard → D1 → Your database → "Database ID" 
   - **Database Name**: The name you gave your D1 database
   - **API Token**: Cloudflare Dashboard → My Profile → API Tokens → Create Token → Use "Custom token" with `D1:Edit` permission

5. **No additional files needed!** The credentials go directly in the VS Code settings.json file or in a .env file if you choose that option.

### Cursor / Trae Configuration

Add this to your MCP configuration file:

```json
{
  "mcpServers": {
    "cloudflare-d1": {
      "command": "cloudflare-sywo-mcp",
      "args": ["--stdio"],
      "env": {
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id-here",
        "CLOUDFLARE_D1_DATABASE_ID": "your-database-id-here",
        "CLOUDFLARE_D1_DATABASE_NAME": "your-database-name-here",
        "CLOUDFLARE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

### Windows Command Line Configuration

For Windows users, you may need to use the full command path or cmd syntax:

```json
{
  "mcpServers": {
    "cloudflare-d1": {
      "command": "cmd",
      "args": ["/c", "set CLOUDFLARE_ACCOUNT_ID=your-account-id-here && set CLOUDFLARE_D1_DATABASE_ID=your-database-id-here && set CLOUDFLARE_D1_DATABASE_NAME=your-database-name-here && set CLOUDFLARE_API_TOKEN=your-api-token-here && cloudflare-sywo-mcp --stdio"]
    }
  }
}
```

### Alternative: Using .env File

You can also use a `.env` file in your project directory:

```json
{
  "mcpServers": {
    "cloudflare-d1": {
      "command": "cloudflare-sywo-mcp",
      "args": ["--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

Make sure to keep your API token secret and rotate immediately if it is ever exposed.

## Credential Management Options

### Option 1: Direct Environment Variables (Recommended for VS Code)
Put credentials directly in your MCP configuration file. This is the simplest approach.

### Option 2: .env File (Good for Development)
Create a `.env` file in your project directory:
```ini
CLOUDFLARE_ACCOUNT_ID=your-account-id-here
CLOUDFLARE_D1_DATABASE_ID=your-database-id-here
CLOUDFLARE_D1_DATABASE_NAME=your-database-name-here
CLOUDFLARE_API_TOKEN=your-api-token-here
```

Then reference the directory in your MCP config:
```json
{
  "mcpServers": {
    "cloudflare-d1": {
      "command": "cloudflare-sywo-mcp",
      "args": ["--stdio"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

### Option 3: System Environment Variables (Advanced)
Set the variables in your system environment, then use a minimal MCP config:
```json
{
  "mcpServers": {
    "cloudflare-d1": {
      "command": "cloudflare-sywo-mcp",
      "args": ["--stdio"]
    }
  }
}
```

**Windows:** Set via System Properties → Environment Variables
**macOS/Linux:** Add to `~/.bashrc` or `~/.zshrc`:
```bash
export CLOUDFLARE_ACCOUNT_ID="your-account-id-here"
export CLOUDFLARE_D1_DATABASE_ID="your-database-id-here"
export CLOUDFLARE_D1_DATABASE_NAME="your-database-name-here"
export CLOUDFLARE_API_TOKEN="your-api-token-here"
```

## Tools Summary

- **d1_list_tables**: Returns an array of table names from the database.
- **d1_query**: Executes a SQL query and returns the raw D1 response payload.

## Troubleshooting

### Connection Issues

If you encounter "Connection closed" errors:
1. Ensure all required environment variables are set correctly
2. Check that your Cloudflare API token has the necessary permissions (`D1:Edit`)
3. Verify your account ID, database ID, and database name are correct

### Windows-Specific Issues

If you see "Syntax Error" from Windows Script Host or "how do I want to open this" popups:
- Make sure you're using version 1.0.7 or later (we fixed Windows compatibility issues)
- Use the Windows command line configuration shown above
- Ensure Node.js is properly installed and in your PATH

### JSON Parsing Errors

If you see "Unexpected token" JSON parsing errors:
- Update to the latest version (1.0.7+) which suppresses debug output
- Check that no other processes are writing to stdout/stderr

## Security Note

Never commit API tokens to source control. If a token becomes exposed, revoke it in the Cloudflare dashboard and create a fresh one.