# MCP Remote Server

A Model Context Protocol (MCP) server that enables Cursor IDE to execute SSH commands on remote servers and manage Google Cloud Platform (GCE) instances. This server provides a seamless integration between Cursor and your remote infrastructure.

## Features

- 🔐 **SSH Command Execution**: Run commands on remote servers via SSH
- ☁️ **GCE Instance Management**: Start and stop Google Cloud Compute Engine instances
- 🔄 **Connection Pooling**: Reuses SSH connections for improved performance
- 📝 **SSH Config Integration**: Uses your existing `~/.ssh/config` for host configuration
- 🚀 **MCP Protocol**: Full support for Model Context Protocol v2025-06-18

## Prerequisites

- Node.js 16+ installed
- SSH access configured to your remote server
- Google Cloud Platform credentials (for GCE features)
- Cursor IDE installed

## Installation

1. **Clone or navigate to the repository:**
   ```bash
   cd mcp-remote
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Start the MCP server:**
   ```bash
   node src/index.js
   ```

   The server will start on `http://localhost:3000` by default.

## Configuration

### 1. SSH Configuration

First, you need to configure your SSH connection in `~/.ssh/config`. The server always uses the host alias `dev` regardless of what you specify in prompts.

Create or edit `~/.ssh/config`:

```ssh-config
Host dev
    HostName your-server.example.com
    User your-username
    Port 22
    IdentityFile ~/.ssh/id_rsa
    # Optional: Add additional SSH options
    # ServerAliveInterval 60
    # ServerAliveCountMax 3
    # StrictHostKeyChecking no
    # UserKnownHostsFile ~/.ssh/known_hosts
```

**Example with AWS EC2:**
```ssh-config
Host dev
    HostName ec2-12-34-56-78.compute-1.amazonaws.com
    User ubuntu
    Port 22
    IdentityFile ~/.ssh/my-aws-key.pem
```

**Example with Google Cloud:**
```ssh-config
Host dev
    HostName 34.123.45.67
    User root
    Port 22
    IdentityFile ~/.ssh/gcp-key.pem
```

**Important Notes:**
- The host alias **must** be named `dev` (all lowercase)
- The server will **always** connect to `dev` regardless of the host you specify in prompts
- Make sure your SSH key has proper permissions: `chmod 600 ~/.ssh/id_rsa`

### 2. Cursor MCP Configuration

Configure Cursor to connect to the MCP server by editing `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "local-mcp": {
      "name": "Local MCP",
      "url": "http://localhost:3000",
      "description": "Runs SSH commands and manages GCE instances",
      "apiKeyHeader": "x-api-key",
      "apiKeyValue": "8BOe6KshR5Eq0otTSjSGMEf5P1edKcq"
    }
  }
}
```

**Configuration Fields:**
- `name`: Display name for the MCP server in Cursor
- `url`: The URL where your MCP server is running (default: `http://localhost:3000`)
- `description`: Description of what the server does
- `apiKeyHeader`: Header name for API authentication (currently optional)
- `apiKeyValue`: API key value for authentication (currently optional)

**After modifying `mcp.json`:**
1. Save the file
2. Restart Cursor IDE
3. The MCP server should appear in Cursor's tool list

### 3. Environment Variables (Optional)

You can set environment variables to customize behavior:

```bash
# SSH Configuration (optional - defaults to ~/.ssh/id_rsa)
export SSH_USERNAME=your-username
export SSH_PRIVATE_KEY_PATH=~/.ssh/custom_key

# Server Configuration
export PORT=3000

# GCP Configuration (for GCE features)
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/gcp-credentials.json
```

## Usage

### Starting the Server

```bash
# Start the server
node src/index.js

# Or with custom port
PORT=8080 node src/index.js
```

The server will output:
```
MCP server running on http://localhost:3000
Ready to accept MCP connections from Cursor
```

### Using in Cursor IDE

Once configured, you can use the MCP tools directly in Cursor:

1. **Run SSH Commands:**
   - Ask Cursor: "Check disk usage on server1.example.com"
   - The server will automatically connect to `dev` and execute the command
   - Example: "Run `df -h` on my remote server"

2. **Manage GCE Instances:**
   - Ask Cursor: "Start instance my-vm in project my-project, zone us-central1-a"
   - Ask Cursor: "Stop instance my-vm in project my-project, zone us-central1-a"

### Available Tools

1. **run_command**
   - Execute SSH commands on the remote server
   - Always connects to `dev` from `~/.ssh/config`
   - Parameters:
     - `host`: Ignored (always uses `dev`)
     - `cmdKey`: The command to execute (e.g., `df -h`, `ls -la`)

2. **start_instance**
   - Start a GCE instance
   - Parameters:
     - `project`: GCP project ID
     - `zone`: GCE zone (e.g., `us-central1-a`)
     - `instance`: Instance name

3. **stop_instance**
   - Stop a GCE instance
   - Parameters:
     - `project`: GCP project ID
     - `zone`: GCE zone
     - `instance`: Instance name

## Architecture

### Connection Pooling

The server maintains a pool of SSH connections to improve performance:
- Connections are reused across multiple commands
- Connections are kept alive with keepalive settings
- Automatic cleanup on connection errors

### SSH Config Integration

The server reads connection details from `~/.ssh/config`:
- Hostname, port, username, and identity file
- Supports all standard SSH config options
- Handles `~` expansion in file paths
- Supports multiple IdentityFile entries (uses the first one)

## Troubleshooting

### Server Won't Start

1. **Check if port is already in use:**
   ```bash
   lsof -i :3000
   ```

2. **Check Node.js version:**
   ```bash
   node --version  # Should be 16+
   ```

### Cursor Can't Connect

1. **Verify server is running:**
   ```bash
   curl http://localhost:3000
   ```

2. **Check `~/.cursor/mcp.json` syntax:**
   - Ensure valid JSON
   - Verify the URL matches your server

3. **Restart Cursor IDE** after modifying `mcp.json`

### SSH Connection Issues

1. **Test SSH connection manually:**
   ```bash
   ssh dev
   ```

2. **Verify SSH config:**
   ```bash
   ssh -F ~/.ssh/config dev
   ```

3. **Check SSH key permissions:**
   ```bash
   ls -la ~/.ssh/id_rsa
   chmod 600 ~/.ssh/id_rsa
   ```

4. **Verify the host alias exists:**
   ```bash
   grep -A 5 "^Host dev" ~/.ssh/config
   ```

### Commands Not Executing

1. **Check server logs** for error messages
2. **Verify the `dev` host is properly configured** in `~/.ssh/config`
3. **Check SSH key has access** to the remote server

## Development

### Project Structure

```
mcp-remote/
├── src/
│   ├── index.js          # Main MCP server
│   ├── ssh.js            # SSH connection handling
│   └── gcp.js            # GCP instance management
├── package.json
├── README.md
└── .gitignore
```

### Adding New Tools

To add new MCP tools:

1. Add tool definition to the `tools` array in `src/index.js`
2. Add handler in the `tools/call` case
3. Implement the functionality in the appropriate module

### Testing

```bash
# Test SSH connection
node -e "const {runRemoteCommand} = require('./src/ssh'); runRemoteCommand({host: 'dev', command: 'echo test'}).then(r => console.log(r));"

# Test MCP server
curl -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18"},"id":1}'
```

## Security Considerations

- The server runs on `localhost:3000` by default (not exposed to network)
- SSH credentials are read from `~/.ssh/config` (standard SSH security)
- API key authentication is available but currently optional
- Consider using environment variables for sensitive data

## License

[Add your license here]

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions:
- Check the Troubleshooting section
- Review server logs for error messages
- Ensure SSH configuration is correct

---

**Note**: The server always connects to the `dev` host alias from your SSH config, regardless of the host you specify in prompts. Make sure `dev` is properly configured in `~/.ssh/config`.