Origin Trial MCP Server (API Version)

MCP (Model Context Protocol) server for managing Origin trials and todos through a secure REST API.

🏗️ New Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐      ┌──────────────┐
│   Cursor    │ ───▶ │  MCP Server  │ ───▶ │  Trial API  │ ───▶ │  PostgreSQL  │
│   Claude    │      │  (This pkg)  │      │  (Fastify)  │      │   (Prisma)   │
└─────────────┘      └──────────────┘      └─────────────┘      └──────────────┘
                     API Key Auth           API Key Auth         Direct Connection

Why This Architecture:

• ✅ Secure: No database credentials in client config
• ✅ Scalable: API can handle multiple MCP instances
• ✅ Maintainable: Centralized business logic
• ✅ Flexible: Easy to add more endpoints

📦 Two Packages

1. Trial API (trial-api/)

• Lightweight REST API with Fastify
• Prisma ORM for type-safe database access
• API key authentication
• Runs as a service

2. MCP Server (this package)

• MCP protocol implementation
• Calls Trial API via HTTP
• Works with Cursor, Claude Desktop, etc.
• Published to npm: @code44/trial-mcp

🚀 Setup

Step 1: Start the API Server

cd /Users/saidbello/Documents/mcp/trial-api

# Create .env
cat > .env << EOF
PORT=3456
API_KEY=my-secure-api-key-12345
DATABASE_URL="postgresql://user:password@localhost:5432/origin_db"
EOF

# Install and start
npm install
npm run prisma:generate
npm run dev

Server runs on http://localhost:3456

Step 2: Configure MCP Server

Add to your Cursor/Claude config:

{
  "mcpServers": {
    "origin-trial": {
      "command": "npx",
      "args": ["-y", "@code44/trial-mcp@latest"],
      "env": {
        "TRIAL_API_URL": "http://localhost:3456",
        "TRIAL_API_KEY": "my-secure-api-key-12345"
      }
    }
  }
}

Or use local build:

{
  "mcpServers": {
    "origin-trial": {
      "command": "node",
      "args": ["/Users/saidbello/Documents/mcp/trial-mcp/dist/index.js"],
      "env": {
        "TRIAL_API_URL": "http://localhost:3456",
        "TRIAL_API_KEY": "my-secure-api-key-12345"
      }
    }
  }
}

Step 3: Restart Cursor

Completely quit and reopen Cursor.

🎯 Available Tools

Trial Management

1. get-trial

Get details of a specific trial.

Parameters:

• trialId (UUID) - Required

Returns: Trial status, title, type, error message, timestamps

2. update-trial-status

Update a trial's status.

Parameters:

• trialId (UUID) - Required
• status (enum: STOPPED, INITIALIZING, ARCHIVED, RUNNING, COMPLETED, FAILED) - Required
• errorMessage (string) - Optional, for FAILED status

Todo Management

3. get-todos

Get all todos for a trial with status summary.

Parameters:

• trialId (UUID) - Required

Returns:

• List of todos ordered by sequence
• Summary: { total, pending, inProgress, completed, cancelled }

4. add-todo

Add a single todo to a trial.

Parameters:

• trialId (UUID) - Required
• content (string, 1-70 chars) - Required
• status (enum: PENDING, IN_PROGRESS, COMPLETED, CANCELLED) - Optional, default: PENDING

5. add-todos-bulk

Add multiple todos at once (1-20 items).

Parameters:

• trialId (UUID) - Required
• todos (array) - Required, 1-20 items
  • Each item: { content: string, status?: enum }

Features:

• Atomic transaction
• Duplicate detection (case-insensitive)
• Batch validation

6. update-todo-status

Update only the status of a todo.

Parameters:

• trialId (UUID) - Required
• todoId (UUID) - Required
• status (enum: PENDING, IN_PROGRESS, COMPLETED, CANCELLED) - Required

7. update-todo

Update a todo's content and/or status.

Parameters:

• trialId (UUID) - Required
• todoId (UUID) - Required
• content (string, 1-70 chars) - Optional
• status (enum) - Optional

Note: At least one of content or status must be provided.

8. delete-todo

Delete a todo item from a trial.

Parameters:

• trialId (UUID) - Required
• todoId (UUID) - Required

🔧 Configuration

Environment Variables

For API Server:

PORT=3456
API_KEY=your-secret-key
DATABASE_URL=postgresql://...

For MCP Server:

TRIAL_API_URL=http://localhost:3456
TRIAL_API_KEY=your-secret-key

🧪 Testing

Test API Directly

# Health check
curl http://localhost:3456/health

# Add todo
curl -X POST http://localhost:3456/api/todos/add \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "trialId": "uuid",
    "content": "Test todo",
    "status": "PENDING"
  }'

Test in Cursor/Claude

After configuring, ask:

Add a todo "Test API integration" to trial [trial-id]

📊 Response Format

All API responses follow this structure:

Success:

{
  "ok": true,
  "data": {
    "message": "Operation description",
    "todo": { /* todo object */ },
    "trial": { /* trial object */ },
    "summary": { /* for bulk operations */ }
  }
}

Error:

{
  "ok": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

The MCP server forwards these responses directly to the AI assistant.

🚀 Production Deployment

API Server

Deploy to:

• Railway: railway up
• Render: Connect repo, set env vars
• Fly.io: fly deploy
• Docker: Use provided Dockerfile
• VPS: Use systemd service

MCP Server

Update config to use production API URL:

{
  "env": {
    "TRIAL_API_URL": "https://trial-api.yourdomain.com",
    "TRIAL_API_KEY": "production-api-key"
  }
}

🔒 Security Best Practices

1. API Key: Use strong, random API keys (32+ characters)
2. HTTPS: Use SSL/TLS in production
3. Rate Limiting: Add rate limiting middleware
4. CORS: Restrict origins in production
5. Monitoring: Log all API calls
6. Secrets: Use secret manager for API_KEY

📈 Performance

| Metric | Value | |--------|-------| | API Response Time | < 50ms (local DB) | | MCP Server Size | 7.15 KB | | API Server Size | 11.66 KB | | Connection Pool | 10 connections | | Bulk Todo Limit | 20 items |

🆚 Old vs New Architecture

Before (v1.0-1.2.1):

MCP Server → PostgreSQL (direct connection)

• ❌ Database credentials in client config
• ❌ Connection timeout issues
• ❌ Hard to scale

After (v2.0.0):

MCP Server → API (HTTP) → Prisma → PostgreSQL

• ✅ Secure API key authentication
• ✅ Centralized access control
• ✅ Easy to monitor and scale
• ✅ No connection timeout issues from MCP

📚 Links

• API Server: /Users/saidbello/Documents/mcp/trial-api/
• MCP Server: /Users/saidbello/Documents/mcp/trial-mcp/
• NPM Package: @code44/trial-mcp

License

MIT