STARWARCLOUD STARWAR.AI
返回市场
黄瓜工作室-MCP

黄瓜工作室-MCP

作者：HeroSizy18 星标更新：2025-11-10
安装使用来源：spider==github.com

项目介绍

Cucumber Studio MCP Server

NPM 版本 NPM 下载量 Docker 拉取次数 GitHub 发布 构建状态 测试覆盖率 TypeScript 许可证

Vibe 使用 Claude Code 和 Pu-Er 编码 🍵

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

功能

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

安装

桌面扩展（DXT）安装

使用此 MCP 服务器最简单的方法是作为桌面扩展：

  1. 下载扩展：从 发布页面 获取最新的 .dxt 文件（每个发布自动构建）
  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
# 使用您的 Cucumber Studio API 凭据编辑 .env
  1. 构建服务器：
npm run build

Docker 支持

使用预构建镜像（推荐）

运行来自 Docker Hub 的官方 Docker 镜像：

# 使用环境文件
docker run --env-file .env herosizy/cucumberstudio-mcp

# 使用环境变量
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
# 使用您的 Cucumber Studio API 凭据编辑 .env
  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 传输（默认）

# 开发
npm run dev

# 生产
npm start

HTTP 传输

# 开发
npm run dev:http

# 生产
npm run start:http

与 MCP 客户端一起使用

桌面扩展（推荐）

直接将 .dxt 扩展文件导入到兼容的 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 传输带热重载
npm run dev

# HTTP 传输带热重载
npm run dev:http

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

测试和质量

# 安装依赖项
npm install

# 运行类型检查
npm run typecheck

# 运行代码检查
npm run lint

# 为生产构建
npm run build

# 运行测试
npm test

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

# 运行测试并生成覆盖率报告（82%以上覆盖率）
npm run test:coverage

# 使用UI运行测试
npm run test:ui

构建选项

# 生产构建（默认）- 优化大小，不包含 .d.ts/.js.map 文件
npm run build

# 开发构建 - 包含源映射和类型声明用于调试
npm run build:dev

DXT 扩展开发

# 验证 manifest.json
npm run dxt:validate

# 为本地测试构建完整的 DXT 扩展（优化的生产构建）
npm run dxt:build

# 检查已构建扩展的信息
npm run dxt:info

# 清理构建工件
npm run dxt:clean

架构

服务器采用模块化、生产就绪的架构：

核心技术

  • TypeScript - 严格的配置下的完全类型安全
  • 双传输 - STDIO 用于本地使用，Streamable HTTP 用于远程访问
  • Zod - 对 API 输入和配置进行运行时验证
  • Axios - 具有全面错误处理和日志记录的 HTTP 客户端
  • MCP SDK - 官方的模型上下文协议实现
  • Express - 具有 CORS、安全中间件和会话管理的 HTTP 服务器
  • Vitest - 现代测试框架，代码覆盖率超过82%
  • MSW - 用于真实 API 测试的模拟服务工作者

关键特性

  • 会话管理 - 具有会话跟踪和清理的 HTTP 传输
  • 全面的日志记录 - 具有可配置输出和级别的结构化日志记录
  • 错误处理 - 具有详细反馈和恢复的健壮错误处理
  • 安全性 - 原始验证、CORS 保护和输入净化
  • 健康监控 - 健康检查端点和请求/响应跟踪
  • 开发工作流程 - 热重载、全面测试和 Docker 支持

测试

该项目包括全面的测试覆盖率：

# 运行所有测试
npm test

# 运行测试并生成覆盖率报告
npm run test:coverage

# 在监视模式下运行测试（用于开发）
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 将自动：

必要的秘密

为了自动化发布，必须在 GitHub 仓库中配置以下秘密：

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

贡献

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

许可证

MIT 许可证 - 详见 LICENSE 文件

资源