Tugboat MCP Server

Tugboat MCP 服务

一个用于与 Tugboat API 交互的模型上下文协议（MCP）服务。此服务允许 Claude 等 AI 助手通过标准化的 MCP 接口访问和操作 Tugboat 资源。

什么是 MCP？

模型上下文协议（MCP）是由 Anthropic 创建的一种开放协议，可在 AI 助手与外部数据源或工具之间实现无缝集成。它为 AI 模型提供了一种标准化方式，以便：

• 访问资源（数据和上下文）
• 使用工具（执行操作的函数）
• 遵循提示词（模板化工作流）

此 Tugboat MCP 服务通过实现该协议，向 Claude 等 AI 助手开放 Tugboat 的 API 功能。

功能

• 访问 Tugboat 项目、预览和存储库
• 创建、构建、刷新和删除预览
• 搜索 Tugboat 资源
• 查看预览日志
• 支持 stdio 和 HTTP 传输
• 支持身份验证和授权

架构

此服务采用模块化架构：

• 核心：主要服务设置和配置管理
• 资源：将 Tugboat 实体作为 MCP 资源公开
• 工具：实现与 Tugboat API 交互的函数
• 实用工具：API 客户端和配置实用工具
• 身份验证：身份验证和授权管理
• 中间件：用于身份验证的 HTTP 请求处理

安装

# 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

用法

环境变量

需要设置以下环境变量：

• TUGBOAT_API_KEY：你的 Tugboat API 密钥
• TRANSPORT_TYPE：要使用的传输类型（stdio 或 http，默认为 stdio）
• PORT：HTTP 传输使用的端口（默认为 3000）
• TUGBOAT_API_URL：Tugboat API 的基准 URL（默认为 https://api.tugboatqa.com/v3）

使用 Claude Desktop 进行设置

配置

1. 创建或编辑 Claude Desktop 配置文件：

   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
   

2. 添加 Tugboat MCP 服务配置：

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

3. 重启 Claude Desktop

在 Claude Desktop 中进行身份验证

使用 Claude Desktop 时，身份验证会通过你在配置中提供的 TUGBOAT_API_KEY 环境变量自动完成。Claude Desktop 使用的 stdio 传输无需像 HTTP 传输那样执行明确的身份验证步骤。

Claude 交互示例

以下是通过 Claude 与 Tugboat 交互的示例：

1. 打开 Claude Desktop 并开始新对话。

2. 如果 MCP 服务配置正确，你会在底部工具栏中看到一个工具图标（锤子）。

3. 请 Claude 与 Tugboat 交互：

   Can you list my Tugboat projects?
   

   Claude 会使用 MCP 服务获取并显示你的项目：

   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. 然后，你可以询问特定项目或预览：

   Show me the previews for the Website Redesign project.
   

   Claude 会使用 MCP 服务获取并显示预览：

   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?
   

使用 Cursor 进行设置

配置

1. 打开 Cursor 设置
2. 前往 Features > MCP Servers
3. 点击“+ Add New MCP Server”按钮
4. 填写以下信息：
   • 名称：输入“tugboat-mcp”
   • 类型：选择“command”作为类型
   • 命令：输入运行服务的命令：

     env TUGBOAT_API_KEY=your-api-key-here node /path/to/tugboat-mcp/dist/index.js
     

在 Cursor 中进行身份验证

与 Claude Desktop 一样，Cursor 会通过配置中提供的环境变量自动完成身份验证。MCP 服务使用 TUGBOAT_API_KEY 向 Tugboat API 进行身份验证。

Cursor 交互示例

以下介绍如何在 Cursor 中使用 Tugboat MCP 服务：

1. 打开 Cursor 并导航到你的项目。

2. 按 Cmd+L（Mac）或 Ctrl+L（Windows/Linux）打开 AI 面板。

3. 确保在 AI 面板右上角选择了“Agent”。

4. 要求 Cursor 与 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 将使用 MCP 服务创建预览：

   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. 你可以继续对话，要求 Cursor 执行其他 Tugboat 操作。

直接使用 HTTP 传输

你也可以通过 HTTP 传输运行服务并直接与之交互：

# Start the server with HTTP transport
TUGBOAT_API_KEY=your-api-key TRANSPORT_TYPE=http npm start

HTTP 传输的身份验证

使用 HTTP 传输时，你需要显式进行身份验证：

1. 获取身份验证令牌：

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

   响应：

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

2. 使用令牌访问 MCP 端点：

   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}'
   

可用资源

资源 URI	描述
tugboat://projects	列出所有项目
tugboat://project/{id}	获取特定项目的详细信息
tugboat://previews	列出所有预览
tugboat://preview/{id}	获取特定预览的详细信息
tugboat://preview/{id}/logs	获取特定预览的日志
tugboat://repositories	列出所有存储库
tugboat://repository/{id}	获取特定存储库的详细信息

可用工具

项目

工具	描述	参数
listProjects	列出所有项目	-
getProject	获取特定项目的详细信息	id
updateProject	更新项目设置	id、name（可选）、domain（可选）
deleteProject	删除项目	id、confirm
getProjectRepos	获取项目的存储库	id
getProjectJobs	获取项目的作业	id、children（可选）、limit（可选）
getProjectStats	获取项目的统计信息	id、item、after（可选）、before（可选）、limit（可选）
searchProjects	搜索项目	query

预览

工具	描述	参数
createPreview	创建新预览	repo、ref、name（可选）、config（可选）
buildPreview	构建预览	previewId
refreshPreview	刷新预览	previewId
deletePreview	删除预览	previewId
getPreview	获取特定预览的详细信息	previewId
updatePreview	更新预览设置	previewId、name（可选）、locked（可选）、anchor（可选）、anchor_type（可选）、config（可选）
getPreviewJobs	获取预览的作业	previewId、active（可选）
getPreviewStatistics	获取预览的统计信息	previewId、item、limit（可选）、before（可选）、after（可选）
clonePreview	克隆预览	previewId、name（可选）、expires（可选）
startPreview	启动预览	previewId
stopPreview	停止预览	previewId
suspendPreview	暂停预览	previewId
searchPreviews	搜索预览	query、state（可选）

仓库

工具	描述	参数
createRepository	创建新仓库	project、provider、repository、auth（可选），以及多个可选设置
getRepository	获取指定仓库的详细信息	id
updateRepository	更新仓库设置	id，以及多个可选设置
deleteRepository	删除仓库	id、confirm
updateRepositoryAuth	更新仓库的提供商身份验证	id、auth
getRepositoryPreviews	获取仓库的预览	id
getRepositoryBranches	获取仓库的分支	id
getRepositoryTags	获取仓库的标签	id
getRepositoryPullRequests	获取仓库的拉取请求	id
getRepositoryJobs	获取仓库的任务	id、action（可选）、children（可选）、limit（可选）
getRepositoryRegistries	获取仓库的 Docker 镜像仓库	id
getRepositoryStats	获取仓库的统计数据	id、item、after（可选）、before（可选）、limit（可选）
createRepositorySSHKey	为仓库生成新的 SSH 密钥	id、type（可选）、bits（可选）

示例提示词

列出可用的 Tugboat 项目

What Tugboat projects do I have access to?

创建新的预览

Create a new preview in repository 5f7c8d9e3b2a1c0e7f6d5a4b named "feature-branch-test" using the "feature/new-homepage" branch.

查看预览日志

Show me the logs for preview 3a2b1c0d9e8f7g6h5i4j.

获取项目详细信息

Show me the details for project 5d810c19f6f8203d5b65ef01.

更新项目

Update the name of project 5d810c19f6f8203d5b65ef01 to "Website Redesign 2.0".

列出项目仓库

What repositories belong to project 5d810c19f6f8203d5b65ef01?

查看项目统计数据

Get the size statistics for project 5d810c19f6f8203d5b65ef01 from the last 30 days.

创建仓库

Create a new GitHub repository for the TugboatQA/demo project in project 5d810c19f6f8203d5b65ef01 using my personal access token ghp_abc123.

获取仓库详细信息

Show me the details for repository 5d810c19f6f82083ed65ef03.

更新仓库设置

Update repository 5d810c19f6f82083ed65ef03 to enable autorebuild and autoredeploy.

列出仓库分支

What branches are available in repository 5d810c19f6f82083ed65ef03?

查看仓库预览

Show me all the previews for repository 5d810c19f6f82083ed65ef03.

开发

# Run in development mode
npm run dev

# Run tests
npm test

项目结构

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

贡献

欢迎贡献！请参阅 TODO.md 文件，了解需要改进的部分。

许可证

MIT

测试

该服务包含全面的测试套件，以确保其功能正常运行。测试使用 Jest 编写，包含身份验证、API 客户端及其他组件的单元测试。

运行测试

使用以下命令运行测试：

# 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

测试结构

测试按以下结构组织在 tests 目录中：

• auth.test.ts - 身份验证管理器和中间件的测试
• api-client.test.ts - Tugboat API 客户端的测试
• 随着功能扩展，还会添加更多测试文件

添加新测试

添加新功能时，请添加相应的测试，以确保代码质量并防止回归。测试文件应遵循 [component].test.ts 命名约定。