# TTG Scratchpad MCP Server

Production-ready MCP server for agent workspace/scratchpad functionality with MongoDB persistence and user isolation.

## Features

- **Persistent Workspaces**: Tasks and files stored in MongoDB Atlas
- **User Isolation**: Each user has their own isolated workspace (via X-User-ID header)
- **File Management**: Create, read, update, delete files in workspace
- **Progress Tracking**: Real-time progress updates visible in chat widget
- **Activity Logging**: Full audit trail of workspace operations
- **Bearer Authentication**: Secure API access via MCP_API_KEYS

## Tools

### Workspace Management
- `scratchpad_start` - Start a new task workspace
- `scratchpad_update` - Update progress during task
- `scratchpad_complete` - Mark task as complete
- `scratchpad_demo` - Demo widget with sample data

### File Management
- `scratchpad_write_file` - Save file to workspace
- `scratchpad_read_file` - Read file from workspace
- `scratchpad_list_files` - List all workspace files
- `scratchpad_delete_file` - Delete file from workspace

## Local Development

### Prerequisites
- Python 3.11+
- MongoDB Atlas cluster (ttg-workspaces)

### Setup

```powershell
# Create virtual environment
python -m venv venv
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
copy .env.template .env
# Edit .env with your MongoDB URI and API key
```

### Run Locally

```powershell
cd C:\Users\Adam\Desktop\ttgeco\scratchpad-mcp
.\venv\Scripts\activate
python server.py
```

Server runs on `http://localhost:8001/mcp`

### Test Without Database

The server runs in demo/stateless mode if `MONGODB_URI` is not set. Useful for UI testing.

## Deployment (Render)

### 1. Push to GitHub

```powershell
git add .
git commit -m "Add MongoDB persistence and file management"
git push origin main
```

### 2. Configure Render Environment Variables

In Render dashboard, add these environment variables:

| Variable | Value | Notes |
|----------|-------|-------|
| `MONGODB_URI` | `mongodb+srv://...` | Your ttg-workspaces connection string |
| `MCP_API_KEYS` | `scratchpad-mcp-ttg-2026-...` | Must match LibreChat SCRATCHPAD_MCP_TOKEN |

**Do NOT set PORT** - Render provides it automatically.

### 3. Verify Deployment

After deploy, test the `/mcp` endpoint:

```bash
curl -X POST https://scratchpad-mcp-18ab.onrender.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## LibreChat Configuration

### librechat.yaml

```yaml
mcpServers:
  scratchpad:
    type: streamable-http
    url: "https://scratchpad-mcp-18ab.onrender.com/mcp"
    headers:
      Authorization: "Bearer ${SCRATCHPAD_MCP_TOKEN}"
      X-User-ID: "{{LIBRECHAT_USER_ID}}"
    timeout: 60000
    initTimeout: 30000
    serverInstructions: true
```

### LibreChat .env

```env
SCRATCHPAD_MCP_TOKEN=your-token-here
```

## Database Schema

### Collections

**workspaces**
```json
{
  "_id": "ObjectId",
  "user_id": "string",
  "conversation_id": "string (optional)",
  "task": "string",
  "status": "idle|active|complete",
  "progress": {"current": 0, "total": 10},
  "working_on": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

**files**
```json
{
  "_id": "ObjectId",
  "user_id": "string",
  "workspace_id": "ObjectId",
  "name": "string",
  "path": "string",
  "type": "file|folder",
  "content": "string",
  "updated": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

**activity_logs**
```json
{
  "_id": "ObjectId",
  "user_id": "string",
  "workspace_id": "ObjectId",
  "action": "string",
  "icon": "write|read|complete|delete",
  "timestamp": "datetime"
}
```

## Security

- Bearer token authentication via `MCP_API_KEYS`
- User isolation via `X-User-ID` header (provided by LibreChat)
- All database queries scoped by user_id
- Input validation on file paths and content

## Troubleshooting

### "No HTTP request context available"
Tool called outside of request context. Ensure using FastMCP 0.5.0+.

### "X-User-ID header required"
LibreChat not sending user ID. Check librechat.yaml headers config.

### "MONGODB_URI environment variable required"
Set `MONGODB_URI` in Render dashboard or local `.env`.

### Connection timeout
Check MongoDB Atlas network access - ensure Render IP is whitelisted or use `0.0.0.0/0` for all access.