使用说明

拖船MCP服务器

用于与拖船API交互的模型上下文协议（MCP）服务器。该服务器允许像克劳德这样的人工智能助手通过标准化的MCP接口访问和操纵拖船资源。

什么是MCP？

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

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

该拖船MCP服务器实现协议，向Claude等人工智能助手展示拖船的API功能。

特性

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

建筑

服务器采用模块化架构：

核心：主服务器设置和配置管理
资源：将拖船实体作为MCP资源公开
工具：实现与拖船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：您的拖船API钥匙
TRANSPORT_TYPE：要使用的运输类型(stdio 或 http，默认为 stdio)
PORT：用于HTTP传输的端口（默认为 3000)
TUGBOAT_API_URL：拖船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"

视窗:

code %APPDATA%\Claude\claude_desktop_config.json

添加拖船MCP服务器配置：

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

重新启动克劳德桌面

Claude桌面中的身份验证

使用Claude Desktop时，身份验证将通过 TUGBOAT_API_KEY 您在配置中提供的环境变量。Claude Desktop使用的stdio传输不需要HTTP传输所做的显式身份验证步骤。

克劳德互动示例

以下是您如何通过Claude与Tugboat互动：

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

请克劳德与拖船互动：

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?

然后，您可以询问特定项目或预览：

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?

使用光标进行设置

配置

打开光标设置
导航到功能>MCP服务器
点击“+添加新MCP服务器”按钮
填写以下信息：
- 名字：输入“拖船mcp”
- 类型：选择“command”作为类型
- 命令：输入运行服务器的命令：
```
env TUGBOAT_API_KEY=your-api-key-here node /path/to/tugboat-mcp/dist/index.js
```

游标中的身份验证

与Claude Desktop一样，Cursor通过配置中提供的环境变量自动处理身份验证。MCP服务器使用 TUGBOAT_API_KEY 通过API拖船认证。

光标交互示例

以下是如何将拖船MCP服务器与Cursor一起使用：

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

要求Cursor与拖船交互：

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?

您可以通过要求Cursor执行其他拖船操作来继续对话。

直接使用HTTP传输

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

# Start the server with HTTP transport
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` （可选）

示例提示

列出可用拖船项目

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文件。

许可证

麻省理工学院

测试

该服务器包括一个全面的测试套件，以确保其功能正常工作。测试是使用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 -API客户拖船试验
随着功能的扩展，将添加更多的测试文件

添加新测试

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