驳船-MCP

Name: 驳船-MCP
Author: TugboatQA

作者：TugboatQA3 星标更新：2025-03-15

安装使用来源：spider==github.com

项目介绍

Tugboat MCP 服务器

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

什么是MCP？

模型上下文协议（MCP）是由Anthropic创建的一个开放协议，它使AI助手能够无缝地集成外部数据源或工具。它提供了一种标准化的方式让AI模型：

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

这个Tugboat MCP服务器实现了该协议，以暴露Tugboat API的能力给像Claude这样的AI助手。

功能

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

架构

服务器遵循模块化架构：

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

安装

# 克隆仓库
git clone https://github.com/yourusername/tugboat-mcp.git
cd tugboat-m-mp

# 安装依赖
npm install

# 构建项目
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中设置

配置

创建或编辑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

添加Tugboat MCP服务器配置：

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

重启Claude Desktop

在Claude Desktop中的身份验证

在使用Claude Desktop时，身份验证是通过您在配置中提供的TUGBOAT_API_KEY环境变量自动处理的。Claude Desktop使用的stdio传输不需要像HTTP传输那样进行显式的身份验证步骤。

示例Claude交互

这是如何通过Claude与Tugboat交互的例子：

打开Claude Desktop并开始新的对话。
如果MCP服务器正确配置，您将在底部工具栏看到一个工具图标（锤子）。

请求Claude与Tugboat交互：

你能列出我的Tugboat项目吗？

Claude将通过MCP服务器获取并显示您的项目：

我找到了以下Tugboat项目：

1. 网站重新设计（ID: abc123）
   - 创建日期：2023-05-15
   - 预览数：7

2. API集成（ID: def456）
   - 创建日期：2023-08-20
   - 预览数：3

您想查看任何特定项目的详细信息吗？

您可以询问关于特定项目或预览的信息：

显示网站重新设计项目的预览。

Claude将通过MCP服务器获取并显示预览：

这里是网站重新设计项目的预览：

1. 主页更新（ID: prev789）
   - 状态：运行中
   - 创建日期：2023-09-10
   - URL: https://prev789.tugboatqa.com

2. 导航菜单修复（ID: prev012）
   - 状态：构建中
   - 创建日期：2023-09-15

您想查看这些预览的日志吗？

在Cursor中设置

配置

打开Cursor设置
导航到功能 > MCP服务器
点击“+ 新增MCP服务器”按钮
填写以下信息：
- 名称：输入“tugboat-mcp”
- 类型：选择“命令”类型
- 命令：输入运行服务器的命令：
```
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交互

这是如何使用Tugboat MCP服务器与Cursor交互的例子：

打开Cursor并导航到您的项目。
按Cmd+L（Mac）或Ctrl+L（Windows/Linux）打开AI面板。
在AI面板右上角，确保选择了“代理”。

请求Cursor与Tugboat交互：

你能使用分支“feature/new-button”在我的Tugboat仓库def456中创建一个新的预览，并命名为“按钮特性测试”吗？

Cursor将通过MCP服务器创建预览：

我会为您在仓库def456中创建一个新的预览。

我已创建了一个名为“按钮特性测试”的预览，使用了分支“feature/new-button”。 

预览ID: prev345
状态：构建中

当构建完成后，预览将在 https://prev345.tugboatqa.com 可用。

您希望我检查构建状态或对Tugboat执行其他操作吗？

您可以通过继续对话来请求Cursor执行其他Tugboat操作。

直接使用HTTP传输

您也可以使用HTTP传输运行服务器并直接与其交互：

# 使用HTTP传输启动服务器
TUGBOAT_API_KEY=your-api-key TRANSPORT_TYPE=http npm start

使用HTTP传输的身份验证

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

获取身份验证令牌：

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

响应：

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

使用令牌访问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项目

我有哪些可以访问的Tugboat项目？

创建新的预览

在仓库5f7c8d9e3b2a1c0e7f6d5a4b中使用“feature/new-homepage”分支创建一个名为“feature-branch-test”的新预览。

查看预览日志

显示预览3a2b1c0d9e8f7g6h5i4j的日志。

获取项目详情

显示项目5d810c19f6f8203d5b65ef01的详细信息。

更新项目

将项目5d810c19f6f8203d5b65ef01的名称更改为“网站重新设计2.0”。

列出项目仓库

项目5d810c19f6f8203d5b65ef01包含哪些仓库？

查看项目统计信息

获取项目5d810c19f6f8203d5b65ef01过去30天的大小统计信息。

创建仓库

使用我的个人访问令牌ghp_abc123为TugboatQA/demo项目在项目5d810c19f6f8203d5b65ef01中创建一个新的GitHub仓库。

获取仓库详情

显示仓库5d810c19f6f82083ed65ef03的详细信息。

更新仓库设置

更新仓库5d810c19f6f82083ed65ef03以启用自动重建和自动部署。

列出仓库分支

仓库5d810c19f6f82083ed65ef03有哪些可用的分支？

查看仓库预览

显示仓库5d810c19f6f82083ed65ef03的所有预览。

开发

# 开发模式运行
npm run dev

# 运行测试
npm test

项目结构

tugboat-mcp/
├── src/
│   ├── index.ts              # 主入口点
│   ├── resources/            # MCP资源实现
│   │   └── index.ts          # 资源注册
│   ├── tools/                # MCP工具实现
│   │   └── index.ts          # 工具注册
│   ├── middleware/           # HTTP中间件
│   │   └── auth.ts           # 身份验证中间件
│   ├── utils/                # 实用函数
│   │   ├── api-client.ts     # Tugboat API客户端
│   │   ├── auth.ts           # 身份验证实用工具
│   │   ├── config.ts         # 配置管理
│   │   └── openapi.yaml      # Tugboat API规范
│   ├── test.ts               # stdio传输测试脚本
│   └── test-http.ts          # HTTP传输测试脚本
├── dist/                     # 编译后的JavaScript文件
├── node_modules/             # Node.js依赖
├── package.json              # 项目元数据和依赖
├── tsconfig.json             # TypeScript配置
├── README.md                 # 项目文档
└── TODO.md                   # 任务列表和进度跟踪

贡献

欢迎贡献！请参阅TODO.md文件了解需要工作的领域。

许可证

MIT

测试

服务器包括一套全面的测试套件，以确保其功能正常工作。测试使用Jest编写，包括身份验证、API客户端和其他组件的单元测试。

运行测试

要运行测试，请使用以下命令：

# 运行所有测试
npm test

# 在监视模式下运行测试（开发期间有用）
npm run test:watch

# 运行带有覆盖率报告的测试
npm run test:coverage

测试结构

测试组织在tests目录中，具有以下结构：

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

添加新测试

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