API Server - MCP + REST API

A comprehensive API server providing Model Context Protocol (MCP) support, RESTful endpoints for file operations, command execution, project management, and AI integration.

Features

• MCP Server: Model Context Protocol compatible server for AI assistants
• REST API: RESTful endpoints for remote development control
• Real-time Communication: Server-Sent Events (SSE) for MCP
• Security: API key authentication, rate limiting, input validation
• Monitoring: Request logging and statistics dashboard
• Documentation: Interactive Swagger/OpenAPI documentation

Quick Start

1. Set Up API Key

The API key is stored in Replit Secrets as API_KEY. All authenticated endpoints require this key.

2. Access the Dashboard

Visit the root URL (/) to access the API dashboard with:

• Real-time statistics
• Request logs
• Endpoint documentation
• Security information

3. View API Documentation

Visit /docs for interactive Swagger documentation.

Authentication

All API endpoints (except /, /docs, /api/stats, /api/logs) require authentication via either:

1. HTTP Header (recommended for REST API):

curl -X GET \
  -H "X-API-KEY: your-api-key" \
  https://your-repl.repl.co/api/project

2. Query Parameter (for SSE connections):

GET /mcp?api_key=your-api-key

REST API Endpoints

File Operations

Create/Update File

POST /api/files
Content-Type: application/json
X-API-KEY: your-api-key

{
  "path": "src/hello.ts",
  "content": "console.log('Hello World');"
}

Read File

GET /api/files/src/hello.ts
X-API-KEY: your-api-key

Delete File

DELETE /api/files/src/hello.ts
X-API-KEY: your-api-key

Command Execution

Execute safe shell commands (whitelisted commands only):

POST /api/execute
Content-Type: application/json
X-API-KEY: your-api-key

{
  "command": "ls -la",
  "timeout": 10000
}

Allowed Commands: ls, cat, head, tail, wc, grep, find, echo, pwd, date, whoami, env, node, npm, npx, pnpm, yarn, git, which, mkdir, touch, cp, mv, rm

Project Structure

GET /api/project?depth=3
X-API-KEY: your-api-key

AI Prompts

POST /api/ai
Content-Type: application/json
X-API-KEY: your-api-key

{
  "prompt": "Explain this code",
  "context": "function add(a, b) { return a + b; }",
  "maxTokens": 1000
}

MCP Server

The MCP (Model Context Protocol) server is available at /mcp and supports:

SSE Connection (GET /mcp)

Connect via Server-Sent Events for real-time MCP communication:

// Use query parameter for authentication (EventSource doesn't support custom headers)
const eventSource = new EventSource('/mcp?api_key=your-api-key');

eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
});

// Handle connection open
eventSource.onopen = () => {
  console.log('MCP connection established');
};

// Handle errors
eventSource.onerror = (error) => {
  console.error('MCP connection error:', error);
};

Note: The SSE endpoint supports api_key query parameter since EventSource API doesn't support custom headers.

JSON-RPC Tool Calls (POST /mcp)

Send MCP tool calls via HTTP:

POST /mcp
Content-Type: application/json
X-API-KEY: your-api-key

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "package.json"
    }
  }
}

Available MCP Tools

Tool	Description
read_file	Read file contents
write_file	Create or update files
list_files	List directory contents
delete_file	Delete files or directories
execute_command	Run safe shell commands
get_project_structure	Get file tree
create_directory	Create new directories

SSH Access Setup

Replit supports SSH access for remote development with VSCode, Cursor, or any SSH client.

Step 1: Generate SSH Keys

If you don't have SSH keys, generate them:

ssh-keygen -t ed25519 -C "your_email@example.com"

Step 2: Add Public Key to Replit

1. Go to Replit Account Settings
2. Navigate to "SSH Keys" section
3. Click "Add SSH Key"
4. Paste your public key (~/.ssh/id_ed25519.pub)
5. Save the key

Step 3: Get Your Repl's SSH Address

1. Open your Repl
2. Click on the three dots menu
3. Select "Connect via SSH"
4. Copy the SSH address (format: ssh <repl-id>@ssh.replit.com)

Step 4: Configure SSH Client

Add to your ~/.ssh/config:

Host replit
    HostName ssh.replit.com
    User YOUR_REPL_ID
    IdentityFile ~/.ssh/id_ed25519
    ForwardAgent yes
    ServerAliveInterval 60
    ServerAliveCountMax 3

Replace YOUR_REPL_ID with your actual Repl ID.

Step 5: Connect

ssh replit

VSCode/Cursor Setup

1. Install "Remote - SSH" extension
2. Press Ctrl+Shift+P → "Remote-SSH: Connect to Host"
3. Select "replit" from the list
4. VSCode will open a new window connected to your Repl

Security Features

Rate Limiting

• 100 requests per 15 minutes per IP
• Returns 429 Too Many Requests when exceeded

Input Validation

• All inputs validated with Zod schemas
• File paths sanitized to prevent directory traversal
• Commands whitelisted for safe execution

Path Traversal Protection

• Paths normalized and validated
• .. patterns rejected
• All file operations confined to project directory

Command Sandboxing

• Only whitelisted commands allowed
• Shell operators (|, ;, &&, etc.) blocked
• Timeout enforcement on all commands

Monitoring

API Statistics

GET /api/stats

Returns:

• Total requests
• Success/failure counts
• Average response time
• Server uptime

Request Logs

GET /api/logs?limit=100

Returns recent API requests with:

• Timestamp
• Method and path
• Status code
• Response time

Error Handling

All errors return JSON responses:

{
  "error": "Error Type",
  "message": "Detailed error message"
}

Common status codes:

• 400 - Bad Request (invalid input)
• 401 - Unauthorized (missing API key)
• 403 - Forbidden (invalid API key)
• 404 - Not Found (resource doesn't exist)
• 429 - Too Many Requests (rate limited)
• 500 - Internal Server Error

Development

Running Locally

npm run dev

Project Structure

├── client/           # React frontend
│   └── src/
│       ├── pages/    # Page components
│       └── components/
├── server/           # Express backend
│   ├── middleware/   # Auth, logging, security
│   ├── services/     # File, command, MCP services
│   ├── routes.ts     # API routes
│   └── swagger.ts    # OpenAPI spec
├── shared/           # Shared types/schemas
│   └── schema.ts
└── README.md

License

MIT License