cucumberstudio

Cucumber Studio MCP 服务

使用 Claude Code 和 Pu-Er 🍵 进行氛围编程

一个 Model Context Protocol（MCP）服务，为大模型提供对 Cucumber Studio 测试平台的访问能力。此服务可帮助 AI 助手从 Cucumber Studio 获取测试场景、操作词、测试运行和项目信息。

功能特性

• 双传输方式支持 - 支持 STDIO 和 Streamable HTTP 传输方式，并提供会话管理
• 项目管理 - 列出并获取项目详情
• 场景访问 - 浏览测试场景并按标签搜索
• 操作词 - 访问可复用的测试步骤和定义
• 测试执行 - 查看测试运行、执行记录和构建信息
• 热重载开发 - 文件变更时通过 tsx --watch 即时重启服务
• 可配置日志记录 - 通过多个输出目标实现结构化日志记录
• 全面的错误处理 - 提供详细反馈的稳健错误处理
• 类型安全 - 完整的 TypeScript 实现，并使用 Zod 进行验证
• 全面测试 - 使用 Vitest 和 MSW，测试覆盖率超过 82%

安装

桌面扩展（MCPB）安装

使用此 MCP 服务最简单的方式是将其作为桌面扩展：

1. 下载扩展：从 发布页面 获取最新的 .mcpb 文件（每次发布都会自动构建）
2. 安装扩展：在兼容的 AI 桌面应用中导入扩展
3. 配置凭据：通过扩展设置配置 Cucumber Studio API 凭据：
   • 访问令牌：你的 Cucumber Studio API 访问令牌
   • 客户端 ID：你的 Cucumber Studio 客户端 ID
   • 用户 ID：你的 Cucumber Studio 用户 ID

扩展会自动处理 MCP 服务的设置和通信。

快速开始（命令行）

使用 npx 直接运行（无需安装）：

npx cucumberstudio-mcp

请先设置环境变量：

export CUCUMBERSTUDIO_ACCESS_TOKEN="your_token"
export CUCUMBERSTUDIO_CLIENT_ID="your_client_id"
export CUCUMBERSTUDIO_UID="your_uid"

开发环境安装

1. 克隆代码库：

git clone https://github.com/HeroSizy/cucumberstudio-mcp.git
cd cucumberstudio-mcp

2. 安装依赖：

npm install

3. 设置环境变量：

cp .env.example .env
# Edit .env with your Cucumber Studio API credentials

4. 构建服务：

npm run build

Docker 支持

使用预构建镜像（推荐）

从 Docker Hub 运行官方 Docker 镜像：

# With environment file
docker run --env-file .env herosizy/cucumberstudio-mcp

# With environment variables
docker run -e CUCUMBERSTUDIO_ACCESS_TOKEN=your_token \
           -e CUCUMBERSTUDIO_CLIENT_ID=your_client_id \
           -e CUCUMBERSTUDIO_UID=your_uid \
           herosizy/cucumberstudio-mcp

使用 Docker Compose

1. 设置环境变量：

cp .env.example .env
# Edit .env with your Cucumber Studio API credentials

2. 更新 docker-compose.yml 以使用预构建镜像：

version: '3.8'
services:
  cucumberstudio-mcp:
    image: herosizy/cucumberstudio-mcp
    env_file:
      - .env
    restart: unless-stopped
    ports:
      - "${MCP_PORT:-3000}:3000"

3. 使用 Docker Compose 运行：

docker-compose up

本地构建

1. 构建镜像：

npm run docker:build

2. 运行容器：

npm run docker:run

Docker 设置包含健康检查和自动重启功能，可用于生产环境。多阶段构建流程会生成经过优化的生产镜像，其中仅包含运行时依赖（约 150MB）。

配置

此服务需要 Cucumber Studio API 凭据。请从你的 Cucumber Studio 账户设置中获取这些凭据：

必需的环境变量

• CUCUMBERSTUDIO_ACCESS_TOKEN - API 访问令牌
• CUCUMBERSTUDIO_CLIENT_ID - 客户端 ID
• CUCUMBERSTUDIO_UID - 用户 ID

可选配置

• CUCUMBERSTUDIO_BASE_URL - API 基础 URL（默认值：https://studio.cucumberstudio.com/api）
• MCP_TRANSPORT - 传输类型：stdio（默认）、http 或 streamable-http
• MCP_PORT - HTTP 传输端口（默认值：3000）
• MCP_HOST - HTTP 传输主机（默认值：0.0.0.0）
• MCP_CORS_ORIGIN - CORS 来源设置（默认值：true）

日志配置

• LOG_LEVEL - 日志级别：error、warn、info、debug、trace（默认值：info）
• LOG_API_RESPONSES - 记录 Cucumber Studio API 响应（默认值：false）
• LOG_REQUEST_BODIES - 记录用于调试的 API 请求正文（默认值：false）
• LOG_RESPONSE_BODIES - 记录用于调试的 API 响应正文（默认值：false）
• LOG_TRANSPORT - 日志输出方式：console、stderr、file、none（默认值：stderr）
• LOG_FILE - 日志文件路径（若 LOG_TRANSPORT=file，则必需）

用法

传输选项

此服务支持 STDIO 和 HTTP 两种传输方式：

STDIO 传输（默认）

# Development
npm run dev

# Production
npm start

HTTP 传输

# Development
npm run dev:http

# Production
npm run start:http

与 MCP 客户端配合使用

桌面扩展（推荐）

将 .mcpb 扩展文件直接导入兼容的 AI 桌面应用。该扩展可通过其设置界面处理所有配置。

手动配置 MCP

手动配置 MCP 客户端：

选项 1：NPX（推荐）

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "npx",
      "args": ["cucumberstudio-mcp"],
      "env": {
        "CUCUMBERSTUDIO_ACCESS_TOKEN": "your_token",
        "CUCUMBERSTUDIO_CLIENT_ID": "your_client_id",
        "CUCUMBERSTUDIO_UID": "your_uid"
      }
    }
  }
}

选项 2：本地安装

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "node",
      "args": ["/path/to/cucumberstudio-mcp/build/index.js"],
      "env": {
        "CUCUMBERSTUDIO_ACCESS_TOKEN": "your_token",
        "CUCUMBERSTUDIO_CLIENT_ID": "your_client_id",
        "CUCUMBERSTUDIO_UID": "your_uid"
      }
    }
  }
}

选项 3：Docker Hub 镜像

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/.env", "herosizy/cucumberstudio-mcp"]
    }
  }
}

选项 4：本地 Docker 构建

{
  "mcpServers": {
    "cucumberstudio": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/path/to/.env", "cucumberstudio-mcp"]
    }
  }
}

可用工具

项目工具

• cucumberstudio_list_projects - 列出所有可访问的项目
• cucumberstudio_get_project - 获取项目详细信息

场景工具

• cucumberstudio_list_scenarios - 列出项目中的场景
• cucumberstudio_get_scenario - 获取场景详细信息
• cucumberstudio_find_scenarios_by_tags - 按标签查找场景

操作词工具

• cucumberstudio_list_action_words - 列出可重复使用的操作词
• cucumberstudio_get_action_word - 获取操作词详细信息
• cucumberstudio_find_action_words_by_tags - 按标签查找操作词

测试执行工具

• cucumberstudio_list_test_runs - 列出测试运行
• cucumberstudio_get_test_run - 获取测试运行详细信息
• cucumberstudio_get_test_executions - 获取单项测试结果
• cucumberstudio_list_builds - 列出构建
• cucumberstudio_get_build - 获取构建详情
• cucumberstudio_list_execution_environments - 列出执行环境

开发

热重载开发

此服务支持热重载，可加快开发：

# STDIO transport with hot reload
npm run dev

# HTTP transport with hot reload  
npm run dev:http

检测到更改时，文件会自动重新编译，服务也会重启。

测试与质量

# Install dependencies
npm install

# Run type checking
npm run typecheck

# Run linting
npm run lint

# Build for production
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage (82%+ coverage)
npm run test:coverage

# Run tests with UI
npm run test:ui

构建选项

# Production build (default) - optimized for size, no .d.ts/.js.map files
npm run build

# Development build - includes source maps and type declarations for debugging
npm run build:dev

MCPB 扩展开发

# Validate manifest.json
npm run mcpb:validate

# Build complete MCPB extension for local testing (optimized production build)
npm run mcpb:build

# Check info about built extension
npm run mcpb:info

# Clean up build artifacts
npm run mcpb:clean

架构

此服务采用模块化、可用于生产环境的架构构建：

核心技术

• TypeScript - 通过严格配置实现完整的类型安全
• 双传输方式 - 用于本地使用的 STDIO，以及用于远程访问的 Streamable HTTP
• Zod - 对 API 输入和配置进行运行时验证
• Axios - 具备全面错误处理和日志记录功能的 HTTP 客户端
• MCP SDK - 官方 Model Context Protocol 实现
• Express - 提供 CORS、安全中间件和会话管理的 HTTP 服务
• Vitest - 现代化测试框架，代码覆盖率超过 82%
• MSW - 用于逼真 API 测试的 Mock Service Worker

主要功能

• 会话管理 - 支持会话跟踪和清理的 HTTP 传输
• 全面日志记录 - 结构化日志记录，支持配置输出和级别
• 错误处理 - 稳健的错误处理，提供详细反馈和恢复机制
• 安全性 - 来源验证、CORS 防护和输入清理
• 运行状况监控 - 运行状况检查端点以及请求/响应跟踪
• 开发工作流 - 热重载、全面测试和 Docker 支持

测试

项目包含全面的测试覆盖：

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode (for development)
npm run test:watch

测试覆盖范围包括：

• 所有模块的单元测试
• MCP 服务的集成测试
• 传输层测试
• API 客户端模拟和测试
• 配置验证
• 错误处理场景

发布与版本发行

本项目通过 GitHub Actions 自动发布。推送版本标签时，系统会自动：

1. 运行完整测试套件 - 确保代码质量和覆盖率
2. 发布到 NPM - 通过 npx cucumberstudio-mcp 提供此软件包
3. 构建并发布 Docker 镜像 - 将多平台镜像推送到 Docker Hub
4. 创建 GitHub 版本发行 - 生成版本说明和链接

创建版本发行

1. 更新 package.json 中的版本：

npm version patch|minor|major

2. 推送标签以触发版本发行：

git push origin --tags

3. GitHub Action 将自动：
   • 发布到 NPM：https://www.npmjs.com/package/cucumberstudio-mcp
   • 推送到 Docker Hub：https://hub.docker.com/r/herosizy/cucumberstudio-mcp
   • 创建包含变更日志的 GitHub 版本发行

必需的密钥

要自动发布，必须在 GitHub 仓库中配置以下密钥：

• NPM_TOKEN - NPM 身份验证令牌
• DOCKER_USERNAME - Docker Hub 用户名
• DOCKER_PASSWORD - Docker Hub 密码或访问令牌

贡献

1. 复刻此仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过：npm test
6. 提交拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

资源

• Cucumber Studio API 文档
• Cucumber Studio API 参考
• 模型上下文协议
• MCP TypeScript SDK