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

# 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

Create or edit the Claude Desktop configuration file:

macOS:

touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Windows:

code %APPDATA%\Claude\claude_desktop_config.json

Add the Tugboat MCP server configuration:

{
  "mcpServers": {
    "tugboat-mcp": {
      "command": "node",
      "args": ["/path/to/tugboat-mcp/dist/index.js"],
      "env": {
        "TUGBOAT_API_KEY": "your-api-key-here"
      }
    }
  }
}

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:

Open Claude Desktop and start a new conversation.
You'll see a tools icon (hammer) in the bottom toolbar if the MCP server is properly configured.

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?

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

Open Cursor Settings
Navigate to Features > MCP Servers
Click on the "+ Add New MCP Server" button
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:

Open Cursor and navigate to your project.
Press Cmd+L (Mac) or Ctrl+L (Windows/Linux) to open the AI panel.
In the top right of the AI panel, make sure "Agent" is selected.

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?

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:

# 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:

Get an authentication token:

curl -X POST http://localhost:3000/auth/login

Response:

{
  "success": true,
  "token": "your-tugboat-api-key"
}

Use the token to access the MCP endpoint:

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

# 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:

# 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.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
coverage		coverage
dist		dist
node_modules		node_modules
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
TODO.md		TODO.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
run-tests.sh		run-tests.sh
tsconfig.json		tsconfig.json

Lullabot/tugboat-mcp

Folders and files

Latest commit

History

Repository files navigation

Tugboat MCP Server

What is MCP?

Features

Architecture

Installation

Usage

Environment Variables

Setting Up With Claude Desktop

Configuration

Authentication in Claude Desktop

Example Claude Interaction

Setting Up With Cursor

Configuration

Authentication in Cursor

Example Cursor Interaction

Using the HTTP Transport Directly

Authentication with HTTP Transport

Available Resources

Available Tools

Projects

Previews

Repositories

Example Prompts

List available Tugboat projects

Create a new preview

Check preview logs

Get project details

Update a project

List project repositories

View project statistics

Create a repository

Get repository details

Update repository settings

List repository branches

View repository previews

Development

Project Structure

Contributing

License

Testing

Running Tests

Test Structure

Adding New Tests

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages