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:

HTTP Header (recommended for REST API):

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

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

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

Step 3: Get Your Repl's SSH Address

Open your Repl
Click on the three dots menu
Select "Connect via SSH"
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

Install "Remote - SSH" extension
Press Ctrl+Shift+P → "Remote-SSH: Connect to Host"
Select "replit" from the list
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

API Server - MCP + REST API

Features

Quick Start

1. Set Up API Key

2. Access the Dashboard

3. View API Documentation

Authentication

REST API Endpoints

File Operations

Create/Update File

Read File

Delete File

Command Execution

Project Structure

AI Prompts

MCP Server

SSE Connection (GET /mcp)

JSON-RPC Tool Calls (POST /mcp)

Available MCP Tools

SSH Access Setup

Step 1: Generate SSH Keys

Step 2: Add Public Key to Replit

Step 3: Get Your Repl's SSH Address

Step 4: Configure SSH Client

Step 5: Connect

VSCode/Cursor Setup

Security Features

Rate Limiting

Input Validation

Path Traversal Protection

Command Sandboxing

Monitoring

API Statistics

Request Logs

Error Handling

Development

Running Locally

Project Structure

License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API