Cucumberstudio

Cucumber Studio MCP服务器

*用克劳德码和普洱编码的Vibe🍵*

一个模型上下文协议（MCP）服务器，提供对Cucumber Studio测试平台的LLM访问。此服务器使AI助手能够从Cucumber Studio检索测试场景、动作词、测试运行和项目信息。

特性

• 双重运输支持 -带有会话管理的STDIO和流式HTTP传输
• 项目管理 -列出并检索项目详细信息
• 场景访问 -浏览测试场景并按标签搜索
• 动作词 -访问可重用的测试步骤和定义
• 测试执行 -查看测试运行、执行和构建信息
• 热重载开发 -使用tsx-watch在文件更改时立即重新启动服务器
• 可配置日志记录 -具有多个输出目的地的结构化日志记录
• 全面的错误处理 -具有详细反馈的稳健错误处理
• 类型安全 -带有Zod验证的完整TypeScript实现
• 全面测试 -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

1. 安装依赖项：

npm install

1. 设置环境变量：

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

1. 构建服务器：

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

1. 更新docker-compose.yml以使用预构建映像：

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

1. 使用Docker Compose运行：

docker-compose up

在当地建设

1. 塑造形象：

npm run docker:build

1. 运行容器：

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用于本地使用，流式HTTP用于远程访问
• 黄道带 -API输入和配置的运行时验证
• 阿西奥斯 -具有全面错误处理和日志记录功能的HTTP客户端
• MCP-SDK -官方模型上下文协议实现
• 快速 -具有CORS、安全中间件和会话管理的HTTP服务器
• Vitest -现代测试框架，代码覆盖率超过82%
• 微软视窗 -模拟服务工人，用于实际的API测试

主要特点

• 会话管理 -具有会话跟踪和清理功能的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

1. 按下标签以触发释放：

git push origin --tags

1. GitHub Action将自动执行以下操作：

- 发布到NPM：https://www.npmjs.com/package/cucumberstudio-mcp - 推送到Docker Hub：https://hub.docker.com/r/herosizy/cucumberstudio-mcp - 使用changelog创建GitHub版本

必需的秘密

对于自动发布，必须在GitHub存储库中配置以下机密：

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

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 确保所有测试通过： npm test
6. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

资源

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