feat(examples): Add Gitpod MCP server example

examples/mcp-server/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Logs
+*.log
+gitpod_mcp.log
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

examples/mcp-server/.python-version

@@ -0,0 +1 @@
+3.11

examples/mcp-server/README.md

@@ -0,0 +1,124 @@
+# Gitpod MCP Server
+
+A Modal Context Protocol (MCP) server that enables Claude Desktop to interact with Gitpod's API. This integration allows Claude to create Gitpod environments, check identity information, and perform other Gitpod-related tasks directly through natural language commands.
+
+## 🌟 Features
+
+- 🔐 **Secure Authentication**: Uses Gitpod API tokens for secure access
+- 🔄 **Real-time Integration**: Direct integration with Gitpod's API
+- 🤖 **Natural Language Interface**: Interact with Gitpod using natural language through Claude
+- 📝 **Comprehensive Logging**: Detailed logging for debugging and monitoring
+- 🚀 **Environment Management**: Create and manage Gitpod environments easily
+- ⚡ **Command Execution**: Run commands in your environments directly
+
+## 🚀 Available Tools
+
+1. **get-identity**
+
+   - Get authenticated identity information from Gitpod
+   - No additional parameters required
+
+2. **create-environment**
+
+   - Create a new Gitpod environment from a repository URL
+   - Optional parameter: `repository_url` (defaults to https://github.com/gitpod-io/empty)
+
+3. **create-environment-with-command**
+   - Create a new Gitpod environment and run a command in it
+   - Required parameter: `command` (command to run in the environment)
+   - Optional parameter: `repository_url` (defaults to https://github.com/gitpod-io/empty)
+
+## 📋 Prerequisites
+
+- Python 3.11 or higher
+- Claude Desktop application
+- Gitpod flex account and Personal Access Token
+- `uv` package manager (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+
+## ⚙️ Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/gitpod-io/gitpod-sdk-python
+cd gitpod-sdk-python/examples/mcp-server
+```
+
+2. Install dependencies:
+
+```bash
+uv sync
+```
+
+## 🔑 Configuration
+
+1. Get your Gitpod API token:
+
+   - Go to [Gitpod Flex Dashboard](https://app.gitpod.io/settings/personal-access-tokens) → Settings → Personal access tokens
+
+2. Configure Claude Desktop:
+   Create or update `~/Library/Application\ Support/Claude/claude_desktop_config.json`:
+
+   ```json
+   {
+     "mcpServers": {
+       "gitpod-mcp": {
+         "command": "/path/to/uv",
+         "args": [
+           "--directory",
+           "/path/to/gitpod-sdk-python/examples/mcp-server",
+           "run",
+           "server.py"
+         ],
+         "env": {
+           "GITPOD_LOG": "info",
+           "GITPOD_API_KEY": "your-gitpod-api-token-here"
+         }
+       }
+     }
+   }
+   ```
+
+## 🎯 Usage Examples
+
+Here are some ways you can interact with the MCP server through Claude:
+
+1. Check your Gitpod identity:
+
+   ```
+   "Get my Gitpod identity"
+   ```
+
+2. Create a new environment:
+
+   ```
+   "Create a Gitpod environment"
+   "Create a Gitpod environment for https://github.com/my/repo"
+   ```
+
+3. Create an environment and run a command:
+   ```
+   "Create a Gitpod environment and run 'echo Hello World'"
+   "Create an environment from https://github.com/my/repo and run 'npm install'"
+   ```
+
+## 🔍 Troubleshooting
+
+The server logs all activities to `gitpod_mcp.log` in the project directory. Common issues:
+
+1. **Authentication Errors**
+
+   - Verify your Gitpod API token is valid
+   - Check if the token has the required scopes
+   - Look for authentication errors in the log
+
+2. **Environment Creation Issues**
+
+   - Ensure the repository URL is accessible
+   - Check if you have an environment class available
+   - Verify your Gitpod account has available resources
+
+3. **Command Execution Problems**
+   - Make sure the command is valid for the environment
+   - Check if the environment is fully initialized
+   - Look for command execution errors in the logs

examples/mcp-server/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "gitpod-mcp"
+version = "0.1.0"
+description = "A Modal Context Protocol (MCP) server for Gitpod integration with Claude Desktop"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "gitpod-sdk>=0.1.2",
+    "mcp>=1.2.1",
+]
+keywords = ["gitpod", "mcp", "claude", "anthropic", "modal-context-protocol"]