# 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):
```bash
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
```bash
POST /api/files
Content-Type: application/json
X-API-KEY: your-api-key

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

#### Read File
```bash
GET /api/files/src/hello.ts
X-API-KEY: your-api-key
```

#### Delete File
```bash
DELETE /api/files/src/hello.ts
X-API-KEY: your-api-key
```

### Command Execution

Execute safe shell commands (whitelisted commands only):

```bash
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

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

### AI Prompts

```bash
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:

```javascript
// 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:

```bash
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:

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

### Step 2: Add Public Key to Replit

1. Go to [Replit Account Settings](https://replit.com/account)
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

```bash
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
```bash
GET /api/stats
```

Returns:
- Total requests
- Success/failure counts
- Average response time
- Server uptime

### Request Logs
```bash
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:

```json
{
  "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

```bash
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