关键词

AI辅助开发自动化测试规约验证代码分析Cursor集成

项目简介

CheckMate 是一个 AI 驱动的测试规约（Specs）验证工具，旨在通过结构化的规约和自动化的验证流程，辅助开发者进行 AI 测试驱动开发（AI-TDD）。该仓库包含 CheckMate 的核心实现，其中包括一个符合 Model Context Protocol (MCP) 定义的服务器组件。这个 MCP 服务器允许兼容的 MCP 客户端（如 Cursor AI 编辑器）与其通信，以自动化触发代码分析、规约生成和测试验证等工作流。

主要功能点

  • 规约管理: 托管和管理位于 'checkmate/specs' 目录下的测试规约文件（支持 Markdown 和 YAML 格式），这些规约定义了软件功能的预期行为和验证标准。
  • 工具执行: 接收来自 MCP 客户端的请求，根据请求调用内部的 AI 模型及 CheckMate CLI 命令（如规约生成、测试运行、代码分析、代码修改建议等），执行具体的开发和测试自动化任务。
  • 上下文提供: 根据客户端请求，分析项目代码库，提供相关文件内容作为上下文供 AI 模型进行分析和生成，增强 AI 对当前项目语境的理解能力。
  • 事件通知: 在关键工作流程（如测试开始、进度更新、完成、错误）期间，通过标准输出（Stdio）向客户端发送结构化的事件通知，使客户端能够实时跟踪后端任务状态。
  • 会话及能力声明: 管理与客户端的连接会话，并通过处理特定的事件类型（如 'features.list', 'task.started', 'spec.create', 'spec.run'）间接声明其提供的自动化能力。

安装步骤

CheckMate 通常通过 npm 全局安装。

  1. 确保您已安装 Node.js 和 npm。

  2. 打开终端，运行以下命令全局安装 CheckMate CLI 工具：

    npm install -g checkmateai

  3. 在您的项目根目录初始化 CheckMate：

    npx checkmateai init

    此命令会创建 '.checkmate' 配置文件和 'checkmate/specs' 目录。

  4. 编辑 '.checkmate' 文件，添加您的 OpenAI 和/或 Anthropic API Key。

    openai_key: sk-****      # 您的 OpenAI API Key
anthropic_key: sk-ant-**** # 您的 Anthropic API Key

    或者使用环境变量 'OPENAI_API_KEY' 和 'ANTHROPIC_API_KEY'。

服务器配置（供 MCP 客户端使用）

CheckMate MCP 服务器是为 MCP 客户端（如 Cursor）提供服务的后端。MCP 客户端需要通过配置来启动 CheckMate MCP 服务器进程并与其建立连接。以下是标准的 Cursor '.cursor/config.json' 文件中 MCP 服务器配置示例，您需要根据您的客户端类型和实际情况进行调整：

{
  "mcpServers": {
    "checkmate": {
      "command": "node", // 启动 CheckMate 服务器进程的命令
      "args": [
        "dist/mcp/index.js" // 启动 CheckMate MCP 服务器入口文件的参数
        // CheckMate MCP 服务器默认监听 8765 端口，您可以通过设置环境变量来自定义端口：
        // 例如，添加 "CHECKMATE_MCP_PORT": "您的端口号" 到 env 字段
      ],
      "env": {
        "CHECKMATE_MODEL_REASON": "您在 .checkmate 中配置的 Reasoning 模型名称，例如 claude-3-7-sonnet-20250219",
        "CHECKMATE_MODEL_QUICK": "您在 .checkmate 中配置的 Quick 模型名称，例如 gpt-4o-mini"
        // 如果您的 CheckMate 配置使用了环境变量来存储 API Key，您也需要在 env 中将这些变量传递给服务器进程：
        // "OPENAI_API_KEY": "您的 OpenAI API Key 或环境变量名",
        // "ANTHROPIC_API_KEY": "您的 Anthropic API Key 或环境变量名"
      }
    }
  }
}

服务器启动后，会默认监听一个端口（默认 8765），并打印启动信息、认证 Token 以及接收到的 MCP 事件和其处理过程到标准输出。

基本使用方法

CheckMate MCP 服务器主要作为后端为兼容的 MCP 客户端提供自动化服务。开发者通常不需要直接与服务器交互，而是通过支持 MCP 协议的客户端界面来使用 CheckMate 的功能。

例如，在 MCP 客户端（如 Cursor）中：

  1. 描述功能: 在客户端的 AI 对话或任务界面中，描述您希望实现或验证的功能需求（例如：“实现用户注册流程”）。
  2. 触发任务: 客户端根据您的描述，通过 MCP 协议向 CheckMate 服务器发送一个结构化的事件（例如 'task.started' 或 'spec.create'），包含任务描述和可能的上下文信息（如相关文件列表）。
  3. 服务器处理: CheckMate 服务器接收到事件后，会：
    • 根据任务描述和上下文（代码文件），调用 AI 模型分析并生成相应的测试规约（Specs）。
    • 将生成的规约保存到 'checkmate/specs' 目录。
    • 可能触发对代码的分析或测试验证流程。
  4. 接收通知: CheckMate 服务器在处理过程中，会通过标准输出发送 'progress'、'complete'、'error' 等事件通知回客户端，客户端界面可以根据这些通知更新任务状态或显示结果。
  5. 客户端操作: 客户端收到规约生成完成的通知后，可能会提示您在编辑器中打开新生成的规约文件进行查看或编辑。在代码实现后，客户端也可能触发 CheckMate 服务器运行规约测试来验证实现是否符合要求。

简而言之，CheckMate MCP 服务器为客户端提供了通过统一协议调用 AI 辅助的 TDD 工作流程的能力，开发者通过客户端界面即可完成规约驱动的开发和验证。

信息

分类

开发者工具

访问项目