Content
# Tugboat MCP Server
A Model Context Protocol (MCP) server for interacting with the Tugboat API. This server allows AI assistants like Claude to access and manipulate Tugboat resources through the standardized MCP interface.
## What is MCP?
The Model Context Protocol (MCP) is an open protocol created by Anthropic that enables seamless integration between AI assistants and external data sources or tools. It provides a standardized way for AI models to:
- Access resources (data and context)
- Use tools (functions to perform actions)
- Follow prompts (templated workflows)
This Tugboat MCP server implements the protocol to expose Tugboat's API capabilities to AI assistants like Claude.
## Features
- Access Tugboat projects, previews, and repositories
- Create, build, refresh, and delete previews
- Search for Tugboat resources
- View preview logs
- Support for both stdio and HTTP transports
- Authentication and authorization support
## Architecture
The server follows a modular architecture:
- **Core**: Main server setup and configuration management
- **Resources**: Exposes Tugboat entities as MCP resources
- **Tools**: Implements functions to interact with Tugboat API
- **Utils**: API client and configuration utilities
- **Auth**: Authentication and authorization management
- **Middleware**: HTTP request handling for authentication
## Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/tugboat-mcp.git
cd tugboat-mcp
# Install dependencies
npm install
# Build the project
npm run build
```
## Usage
### Environment Variables
The following environment variables are required:
- `TUGBOAT_API_KEY`: Your Tugboat API key
- `TRANSPORT_TYPE`: The transport type to use (`stdio` or `http`, defaults to `stdio`)
- `PORT`: The port to use for HTTP transport (defaults to `3000`)
- `TUGBOAT_API_URL`: The base URL for the Tugboat API (defaults to `https://api.tugboatqa.com/v3`)
## Setting Up With Claude Desktop
### Configuration
1. Create or edit the Claude Desktop configuration file:
**macOS**:
```bash
touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
```
**Windows**:
```bash
code %APPDATA%\Claude\claude_desktop_config.json
```
2. Add the Tugboat MCP server configuration:
```json
{
"mcpServers": {
"tugboat-mcp": {
"command": "node",
"args": ["/path/to/tugboat-mcp/dist/index.js"],
"env": {
"TUGBOAT_API_KEY": "your-api-key-here"
}
}
}
}
```
3. Restart Claude Desktop
### Authentication in Claude Desktop
When using Claude Desktop, authentication is handled automatically through the `TUGBOAT_API_KEY` environment variable that you provide in the configuration. The stdio transport used by Claude Desktop doesn't require the explicit authentication steps that the HTTP transport does.
### Example Claude Interaction
Here's how you might interact with Tugboat through Claude:
1. Open Claude Desktop and start a new conversation.
2. You'll see a tools icon (hammer) in the bottom toolbar if the MCP server is properly configured.
3. Ask Claude to interact with Tugboat:
```
Can you list my Tugboat projects?
```
Claude will respond by using the MCP server to fetch and display your projects:
```
I've found the following Tugboat projects:
1. Website Redesign (ID: abc123)
- Created: 2023-05-15
- Previews: 7
2. API Integration (ID: def456)
- Created: 2023-08-20
- Previews: 3
Would you like to see details for any specific project?
```
4. You can then ask about specific projects or previews:
```
Show me the previews for the Website Redesign project.
```
Claude will use the MCP server to fetch and display the previews:
```
Here are the previews for the Website Redesign project:
1. Homepage Update (ID: prev789)
- Status: Running
- Created: 2023-09-10
- URL: https://prev789.tugboatqa.com
2. Nav Menu Fix (ID: prev012)
- Status: Building
- Created: 2023-09-15
Would you like to see logs for any of these previews?
```
## Setting Up With Cursor
### Configuration
1. Open Cursor Settings
2. Navigate to Features > MCP Servers
3. Click on the "+ Add New MCP Server" button
4. Fill out the following information:
- **Name**: Enter "tugboat-mcp"
- **Type**: Select "command" as the type
- **Command**: Enter the command to run the server:
```
env TUGBOAT_API_KEY=your-api-key-here node /path/to/tugboat-mcp/dist/index.js
```
### Authentication in Cursor
Like Claude Desktop, Cursor handles authentication automatically through the environment variables provided in the configuration. The MCP server uses the `TUGBOAT_API_KEY` to authenticate with the Tugboat API.
### Example Cursor Interaction
Here's how to use the Tugboat MCP server with Cursor:
1. Open Cursor and navigate to your project.
2. Press `Cmd+L` (Mac) or `Ctrl+L` (Windows/Linux) to open the AI panel.
3. In the top right of the AI panel, make sure "Agent" is selected.
4. Ask Cursor to interact with Tugboat:
```
Can you create a new preview in my Tugboat repository def456 using the branch "feature/new-button" and name it "Button Feature Test"?
```
Cursor will respond by using the MCP server to create the preview:
```
I'll create a new preview for you in repository def456.
I've created a preview named "Button Feature Test" using the branch "feature/new-button".
Preview ID: prev345
Status: Building
The preview will be available at https://prev345.tugboatqa.com once the build is complete.
Would you like me to check the build status or perform any other actions with Tugboat?
```
5. You can continue the conversation by asking Cursor to perform other Tugboat operations.
## Using the HTTP Transport Directly
You can also run the server with HTTP transport and interact with it directly:
```bash
# Start the server with HTTP transport
TUGBOAT_API_KEY=your-api-key TRANSPORT_TYPE=http npm start
```
### Authentication with HTTP Transport
When using the HTTP transport, you need to authenticate explicitly:
1. Get an authentication token:
```bash
curl -X POST http://localhost:3000/auth/login
```
Response:
```json
{
"success": true,
"token": "your-tugboat-api-key"
}
```
2. Use the token to access the MCP endpoint:
```bash
curl -X POST http://localhost:3000/mcp \
-H "Authorization: Bearer your-tugboat-api-key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'
```
## Available Resources
| Resource URI | Description |
| --- | --- |
| `tugboat://projects` | List all projects |
| `tugboat://project/{id}` | Get details for a specific project |
| `tugboat://previews` | List all previews |
| `tugboat://preview/{id}` | Get details for a specific preview |
| `tugboat://preview/{id}/logs` | Get logs for a specific preview |
| `tugboat://repositories` | List all repositories |
| `tugboat://repository/{id}` | Get details for a specific repository |
## Available Tools
### Projects
| Tool | Description | Parameters |
| --- | --- | --- |
| `listProjects` | List all projects | - |
| `getProject` | Get details of a specific project | `id` |
| `updateProject` | Update a project's settings | `id`, `name` (optional), `domain` (optional) |
| `deleteProject` | Delete a project | `id`, `confirm` |
| `getProjectRepos` | Get repositories for a project | `id` |
| `getProjectJobs` | Get jobs for a project | `id`, `children` (optional), `limit` (optional) |
| `getProjectStats` | Get statistics for a project | `id`, `item`, `after` (optional), `before` (optional), `limit` (optional) |
| `searchProjects` | Search for projects | `query` |
### Previews
| Tool | Description | Parameters |
| --- | --- | --- |
| `createPreview` | Create a new preview | `repo`, `ref`, `name` (optional), `config` (optional) |
| `buildPreview` | Build a preview | `previewId` |
| `refreshPreview` | Refresh a preview | `previewId` |
| `deletePreview` | Delete a preview | `previewId` |
| `getPreview` | Get details of a specific preview | `previewId` |
| `updatePreview` | Update a preview's settings | `previewId`, `name` (optional), `locked` (optional), `anchor` (optional), `anchor_type` (optional), `config` (optional) |
| `getPreviewJobs` | Get jobs for a preview | `previewId`, `active` (optional) |
| `getPreviewStatistics` | Get statistics for a preview | `previewId`, `item`, `limit` (optional), `before` (optional), `after` (optional) |
| `clonePreview` | Clone a preview | `previewId`, `name` (optional), `expires` (optional) |
| `startPreview` | Start a preview | `previewId` |
| `stopPreview` | Stop a preview | `previewId` |
| `suspendPreview` | Suspend a preview | `previewId` |
| `searchPreviews` | Search for previews | `query`, `state` (optional) |
### Repositories
| Tool | Description | Parameters |
| --- | --- | --- |
| `createRepository` | Create a new repository | `project`, `provider`, `repository`, `auth` (optional), plus multiple optional settings |
| `getRepository` | Get details of a specific repository | `id` |
| `updateRepository` | Update a repository's settings | `id`, plus multiple optional settings |
| `deleteRepository` | Delete a repository | `id`, `confirm` |
| `updateRepositoryAuth` | Update provider authentication for a repository | `id`, `auth` |
| `getRepositoryPreviews` | Get previews for a repository | `id` |
| `getRepositoryBranches` | Get branches for a repository | `id` |
| `getRepositoryTags` | Get tags for a repository | `id` |
| `getRepositoryPullRequests` | Get pull requests for a repository | `id` |
| `getRepositoryJobs` | Get jobs for a repository | `id`, `action` (optional), `children` (optional), `limit` (optional) |
| `getRepositoryRegistries` | Get Docker registries for a repository | `id` |
| `getRepositoryStats` | Get statistics for a repository | `id`, `item`, `after` (optional), `before` (optional), `limit` (optional) |
| `createRepositorySSHKey` | Generate new SSH key for a repository | `id`, `type` (optional), `bits` (optional) |
## Example Prompts
### List available Tugboat projects
```
What Tugboat projects do I have access to?
```
### Create a new preview
```
Create a new preview in repository 5f7c8d9e3b2a1c0e7f6d5a4b named "feature-branch-test" using the "feature/new-homepage" branch.
```
### Check preview logs
```
Show me the logs for preview 3a2b1c0d9e8f7g6h5i4j.
```
### Get project details
```
Show me the details for project 5d810c19f6f8203d5b65ef01.
```
### Update a project
```
Update the name of project 5d810c19f6f8203d5b65ef01 to "Website Redesign 2.0".
```
### List project repositories
```
What repositories belong to project 5d810c19f6f8203d5b65ef01?
```
### View project statistics
```
Get the size statistics for project 5d810c19f6f8203d5b65ef01 from the last 30 days.
```
### Create a repository
```
Create a new GitHub repository for the TugboatQA/demo project in project 5d810c19f6f8203d5b65ef01 using my personal access token ghp_abc123.
```
### Get repository details
```
Show me the details for repository 5d810c19f6f82083ed65ef03.
```
### Update repository settings
```
Update repository 5d810c19f6f82083ed65ef03 to enable autorebuild and autoredeploy.
```
### List repository branches
```
What branches are available in repository 5d810c19f6f82083ed65ef03?
```
### View repository previews
```
Show me all the previews for repository 5d810c19f6f82083ed65ef03.
```
## Development
```bash
# Run in development mode
npm run dev
# Run tests
npm test
```
## Project Structure
```
tugboat-mcp/
├── src/
│ ├── index.ts # Main entry point
│ ├── resources/ # MCP resources implementation
│ │ └── index.ts # Resource registration
│ ├── tools/ # MCP tools implementation
│ │ └── index.ts # Tool registration
│ ├── middleware/ # HTTP middleware
│ │ └── auth.ts # Authentication middleware
│ ├── utils/ # Utility functions
│ │ ├── api-client.ts # Tugboat API client
│ │ ├── auth.ts # Authentication utilities
│ │ ├── config.ts # Configuration management
│ │ └── openapi.yaml # Tugboat API specification
│ ├── test.ts # Test script for stdio transport
│ └── test-http.ts # Test script for HTTP transport
├── dist/ # Compiled JavaScript files
├── node_modules/ # Node.js dependencies
├── package.json # Project metadata and dependencies
├── tsconfig.json # TypeScript configuration
├── README.md # Project documentation
└── TODO.md # Task list and progress tracking
```
## Contributing
Contributions are welcome! See the TODO.md file for areas that need work.
## License
MIT
## Testing
The server includes a comprehensive test suite to ensure its functionality works correctly. The tests are written using Jest and include unit tests for authentication, API client, and other components.
### Running Tests
To run the tests, use the following command:
```bash
# Run all tests
npm test
# Run tests in watch mode (useful during development)
npm run test:watch
# Run tests with coverage report
npm run test:coverage
```
### Test Structure
The tests are organized in the `tests` directory with the following structure:
- `auth.test.ts` - Tests for the authentication manager and middleware
- `api-client.test.ts` - Tests for the Tugboat API client
- More test files will be added as functionality expands
### Adding New Tests
When adding new functionality, please add corresponding tests to ensure code quality and prevent regressions. Test files should follow the naming convention `[component].test.ts`.
