# MCP Tilt Server

A Model Context Protocol (MCP) server that provides read-only access to Tilt.dev resources and logs. This package can be run as a CLI tool via `npx` and supports both Node.js native and Docker modes.

## Installation

```bash
# Run directly with npx (recommended)
npx @gc-mcp/tilt --help

# Or install globally
npm install -g @gc-mcp/tilt
mcp-tilt --help
```

## Quick Start

```bash
# Start the server in Node mode (default)
npx @gc-mcp/tilt

# Start on a specific port
npx @gc-mcp/tilt --port 9000

# Start in Docker mode
npx @gc-mcp/tilt --mode docker

# Set environment variables
npx @gc-mcp/tilt --env TILT_HOST=localhost --env LOG_LEVEL=debug
```

## Usage

### Command Line Interface

```bash
Usage: mcp-tilt [options]

MCP Server for Tilt.dev - provides read-only access to Tilt resources and logs

Options:
  -V, --version          output the version number
  -p, --port <port>      Port to listen on (default: 8087 or MCP_TILT_PORT env var)
  -e, --env <key=value>  Set environment variable (can be used multiple times)
  -m, --mode <mode>      Server mode: node or docker (default: node or MCP_TILT_MODE env var)
  --dry-run              Validate configuration without starting server
  --status               Check server status and exit
  -h, --help             output usage information
```

### Server Modes

#### Node Mode (Default)

Runs the MCP server directly in Node.js. This is the fastest and most efficient mode.

```bash
npx @gc-mcp/tilt --mode node --port 8087
```

#### Docker Mode

Runs the MCP server in a Docker container. The CLI automatically handles container lifecycle management.

```bash
npx @gc-mcp/tilt --mode docker --port 8087
```

**Note**: Docker mode requires Docker to be installed and running.

### Configuration

#### Environment Variables

You can set environment variables using the `--env` flag or by setting them in your environment:

```bash
# Via CLI flags
npx @gc-mcp/tilt --env TILT_HOST=localhost --env TILT_PORT=10350

# Via environment variables
export TILT_HOST=localhost
export TILT_PORT=10350
npx @gc-mcp/tilt
```

#### Available Environment Variables

- `MCP_TILT_PORT`: Default port for the server (default: 8087)
- `MCP_TILT_MODE`: Default server mode (default: node)
- `TILT_HOST`: Tilt API host (default: localhost)
- `TILT_PORT`: Tilt API port (default: 10350)
- `TILT_USE_CLI`: Use Tilt CLI instead of API (default: false)
- `LOG_LEVEL`: Logging level (default: info)
- `LOG_MAX_LINES`: Maximum log lines to retrieve (default: 1000)
- `RESP_MAX_BYTES`: Maximum response size in bytes (default: 1048576)
- `STREAM_THROTTLE_MS`: Stream throttling interval (default: 100)
- `REDACTION_PATTERNS`: Comma-separated patterns to redact from logs
- `VERBOSE`: Enable verbose logging (default: false)

## Health Checks

The server provides a health check endpoint at `/health`:

```bash
curl http://localhost:8087/health
```

Response:

```json
{
  "status": "healthy",
  "timestamp": "2025-01-24T12:00:00.000Z",
  "service": "mcp-tilt-server"
}
```

## MCP Integration

### Available Tools

The server provides the following MCP tools:

- `check_tilt_status`: Check if Tilt is running and accessible
- `list_resources`: List all Tilt resources
- `get_status`: Get status for a specific resource or all resources
- `get_logs`: Get logs for a specific resource
- `tail_logs`: Stream logs for a specific resource in real-time
- `search_logs`: Search logs for a specific resource

### MCP Client Configuration

Configure your MCP client to connect to the server:

```json
{
  "mcpServers": {
    "tilt": {
      "command": "npx",
      "args": ["@gc-mcp/tilt", "--port", "8087"],
      "env": {
        "TILT_HOST": "localhost",
        "TILT_PORT": "10350"
      }
    }
  }
}
```

For HTTP mode (when using Docker or HTTP clients):

```json
{
  "mcpServers": {
    "tilt": {
      "url": "http://localhost:8087/mcp"
    }
  }
}
```

## Troubleshooting

### Common Issues

#### Port Already in Use

```bash
Error: listen EADDRINUSE: address already in use 0.0.0.0:8087
```

**Solution**: Use a different port:

```bash
npx @gc-mcp/tilt --port 9000
```

#### Docker Not Available

```bash
Error: Docker is not available. Please install Docker or use --mode node
```

**Solution**: Install Docker or use Node mode:

```bash
npx @gc-mcp/tilt --mode node
```

#### Tilt Not Running

```bash
Tilt Status: ❌ Not running
```

**Solution**: Start Tilt or check your Tilt configuration:

```bash
tilt up
```

### Debugging

Enable verbose logging:

```bash
npx @gc-mcp/tilt --env LOG_LEVEL=debug --env VERBOSE=true
```

Check server status:

```bash
npx @gc-mcp/tilt --status
```

Validate configuration:

```bash
npx @gc-mcp/tilt --dry-run
```

### Logs

The server logs are output to stdout/stderr. In Docker mode, you can view container logs:

```bash
docker logs mcp-tilt-server
```

## Development

### Building from Source

```bash
git clone <repository-url>
cd mcp-tilt
npm install
npm run build
```

### Running Tests

```bash
npm test
npm run test:e2e
```

### Local Development

```bash
npm run dev
```

## License

MIT

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## Support

- [GitHub Issues](https://github.com/your-org/mcp-tilt/issues)
- [Documentation](https://github.com/your-org/mcp-tilt#readme)