# 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.
