tilt-mcp 0.1.3
Model Context Protocol server for Tilt - interact with Tilt resources through MCP
License: MIT
Requires Python: >=3.8
Keywords: mcp, tilt, kubernetes, development, model-context-protocol

# Tilt MCP Server

A Model Context Protocol (MCP) server that integrates with [Tilt](https://tilt.dev/) to provide programmatic access to Tilt resources and logs through LLM applications.

## Overview

The Tilt MCP server allows Large Language Models (LLMs) and AI assistants to interact with your Tilt development environment. It provides tools to:

- List all enabled Tilt resources
- Fetch logs from specific resources
- Monitor resource status and health

This enables AI-powered development workflows, debugging assistance, and automated monitoring of your Tilt-managed services.

## Features

- 🔍 **Resource Discovery**: List all active Tilt resources with their current status
- 📜 **Log Retrieval**: Fetch recent logs from any Tilt resource
- 🛡️ **Type Safety**: Built with Python type hints for better IDE support
- 🚀 **Async Support**: Fully asynchronous implementation using FastMCP
- 📊 **Structured Output**: Returns well-formatted JSON responses

## Prerequisites

- Python 3.8 or higher
- [Tilt](https://docs.tilt.dev/install.html) installed and configured
- An MCP-compatible client (e.g., Claude Desktop, mcp-cli)

## Installation

### From PyPI (recommended)

```bash
pip install tilt-mcp
```

### From Source

```bash
git clone https://github.com/aryan-agrawal-glean/tilt-mcp.git
cd tilt-mcp
pip install -e .
```

## Configuration

### For Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
**Linux**: `~/.config/claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tilt": {
      "command": "tilt-mcp"
    }
  }
}
```

### For Development/Testing

You can run the server directly:

```bash
python -m tilt_mcp.server
```

Or use it with the MCP CLI:

```bash
mcp run python -m tilt_mcp.server
```

## Usage

Once configured, the Tilt MCP server provides the following tools:

### `get_all_resources`

Lists all enabled Tilt resources with their current status.

Example response:
```json
[
  {
    "name": "frontend",
    "type": "k8s",
    "status": "ok",
    "updateStatus": "ok"
  },
  {
    "name": "backend-api",
    "type": "k8s", 
    "status": "pending",
    "updateStatus": "pending"
  }
]
```

### `get_resource_logs`

Fetches recent logs from a specific Tilt resource.

Parameters:
- `resource_name` (string, required): Name of the Tilt resource
- `tail` (integer, optional): Number of log lines to return (default: 1000)

Example request:
```json
{
  "resource_name": "frontend",
  "tail": 50
}
```

Example response:
```json
{
  "logs": "2024-01-15 10:23:45 INFO Starting server on port 3000\n2024-01-15 10:23:46 INFO Server ready"
}
```

## Example Prompts

Here are some example prompts you can use with an AI assistant that has access to this MCP server:

- "Show me all the Tilt resources that are currently running"
- "Get the last 100 lines of logs from the backend-api service"
- "Which services are failing or have errors?"
- "Show me the recent logs from all services that aren't healthy"
- "Help me debug why the frontend service is crashing"

## Development

### Setting up the development environment

```bash
# Clone the repository
git clone https://github.com/yourusername/tilt-mcp.git
cd tilt-mcp

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"
```

### Running tests

```bash
pytest
```

### Code formatting and linting

```bash
# Format code
black src tests

# Run linter
ruff check src tests

# Type checking
mypy src
```

## Troubleshooting

### Common Issues

1. **"Tilt not found" error**
   - Ensure Tilt is installed and available in your PATH
   - Try running `tilt version` to verify installation

2. **"No resources found" when Tilt is running**
   - Make sure your Tiltfile is loaded and resources are started
   - Check that you're running the MCP server in the correct directory

3. **Connection errors**
   - Verify the MCP client configuration is correct
   - Check the logs at `~/.tilt-mcp/tilt_mcp.log`

### Debug Logging

To enable debug logging, set the environment variable:

```bash
export LOG_LEVEL=DEBUG
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:

- Setting up your development environment
- Running tests
- Submitting pull requests
- Code style guidelines

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server implementation
- Integrates with [Tilt](https://tilt.dev/) for Kubernetes development

## Support

- 📧 Email: aryan.agrawal@glean.com
- 💬 Issues: [GitHub Issues](https://github.com/aryan-agrawal-glean/tilt-mcp/issues)
- 📖 Docs: [GitHub Wiki](https://github.com/aryan-agrawal-glean/tilt-mcp/wiki)