@testkase/mcp-server 2.1.0 → 2.3.0

package/README.md

@@ -1,48 +1,43 @@
-# @testkase/mcp-server
+<p align="center">
+  <a href="https://testkase.com">
+    <img src="https://testkase.com/logo.png" alt="TestKase" width="120" />
+  </a>
+</p>
 
-[![npm version](https://img.shields.io/npm/v/@testkase/mcp-server.svg)](https://www.npmjs.com/package/@testkase/mcp-server)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<h3 align="center">@testkase/mcp-server</h3>
 
-Model Context Protocol (MCP) server for TestKase API. Enables AI agents like Claude Desktop and GitHub Copilot to manage the complete test management lifecycle — test cases, cycles, plans, execution, and reporting.
+<p align="center">
+  Official MCP server for <a href="https://testkase.com">TestKase</a> — connect your AI agent to a complete test management platform.
+</p>
 
-## Features
+<p align="center">
+  <a href="https://www.npmjs.com/package/@testkase/mcp-server"><img src="https://img.shields.io/npm/v/@testkase/mcp-server.svg?style=flat-square" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@testkase/mcp-server"><img src="https://img.shields.io/npm/dm/@testkase/mcp-server.svg?style=flat-square" alt="npm downloads" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="MIT License" /></a>
+</p>
 
-- **Complete lifecycle** — test cases, cycles, plans, execution, and 40+ report types
-- **Stateless** — every tool takes `projectId` explicitly (no state management required)
-- **11 thoughtful tools** — fewer tools, broader coverage, designed for AI agents
-- **Structured JSON** — all responses are JSON (AI agents format for users)
-- **Secure** — PAT token authentication with auto-resolved organization
+---
 
-## Installation
+## What is this?
 
-### Global Installation (Recommended)
+This package gives AI agents — Claude Desktop, GitHub Copilot, Cursor, or any [MCP](https://modelcontextprotocol.io)-compatible client — full access to your TestKase projects. Your agent can create test cases, run test cycles, record execution results, and pull reports, all through natural language.
 
-```bash
-npm install -g @testkase/mcp-server
-```
-
-### Local Installation
-
-```bash
-npm install @testkase/mcp-server
-```
+**11 tools. Zero config beyond a token. Works out of the box.**
 
 ## Quick Start
 
-### 1. Get Your PAT Token
+### 1. Get a PAT token
 
-1. Log in to [TestKase](https://app.testkase.com)
-2. Navigate to **Settings > Personal Access Tokens**
-3. Click **"Generate New Token"**
-4. Copy the token (starts with `xyz_`)
+Log in to [TestKase](https://www.testkase.com) > **API Keys** > **Generate New Token**
 
-### 2. Configure Your AI Agent
+### 2. Add to your AI agent
 
-#### For Claude Desktop
+<details>
+<summary><strong>Claude Desktop</strong></summary>
 
-Edit your Claude config file:
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+Edit your config file:
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
 ```json
 {
@@ -51,19 +46,21 @@ Edit your Claude config file:
       "command": "npx",
       "args": ["-y", "@testkase/mcp-server"],
       "env": {
-        "TESTKASE_API_BASE_URL": "https://apiqa.testkase.com",
-        "TESTKASE_PAT_TOKEN": "xyz_your_pat_token_here"
+        "TESTKASE_API_BASE_URL": "https://api.testkase.com",
+        "TESTKASE_PAT_TOKEN": "xyz_your_token_here"
       }
     }
   }
 }
 ```
+</details>
 
-#### For GitHub Copilot (VS Code)
+<details>
+<summary><strong>GitHub Copilot (VS Code)</strong></summary>
 
-Edit your Copilot config file:
-- **Windows**: `%APPDATA%\Code\User\globalStorage\github.copilot\mcp.json`
-- **macOS**: `~/Library/Application Support/Code/User/globalStorage/github.copilot/mcp.json`
+Edit your config file:
+- **Windows:** `%APPDATA%\Code\User\globalStorage\github.copilot\mcp.json`
+- **macOS:** `~/Library/Application Support/Code/User/globalStorage/github.copilot/mcp.json`
 
 ```json
 {
@@ -72,149 +69,121 @@ Edit your Copilot config file:
       "command": "npx",
       "args": ["-y", "@testkase/mcp-server"],
       "env": {
-        "TESTKASE_API_BASE_URL": "https://apiqa.testkase.com",
-        "TESTKASE_PAT_TOKEN": "xyz_your_pat_token_here"
+        "TESTKASE_API_BASE_URL": "https://api.testkase.com",
+        "TESTKASE_PAT_TOKEN": "xyz_your_token_here"
       }
     }
   }
 }
 ```
+</details>
 
-### 3. Restart Your AI Agent
+<details>
+<summary><strong>Claude Code (CLI)</strong></summary>
 
-- **Claude Desktop**: Close and reopen completely
-- **VS Code**: Restart VS Code
-
-### 4. Start Using!
-
-```
-"List my projects"
-"Show test cases in project PRJ-1001"
-"Create a test cycle called 'Sprint 42 Regression' in project PRJ-1001"
-"Execute TEST-1 as pass and TEST-2 as fail in cycle TCYCLE-5"
-"Show me the execution summary report for project PRJ-1001"
+```bash
+claude mcp add testkase -e TESTKASE_API_BASE_URL=https://api.testkase.com -e TESTKASE_PAT_TOKEN=xyz_your_token_here -- npx -y @testkase/mcp-server
 ```
+</details>
 
-## Available Tools (11)
-
-### 1. `list_projects`
-List all projects the user has access to. Use this first to discover project IDs.
-- **Params:** `search?`, `page?`, `limit?`
-
-### 2. `get_project_structure`
-Get folders, labels, and team members for a project.
-- **Params:** `projectId`, `section?` (TESTCASE|TEST_CYCLE|TEST_PLAN), `include?` (folders,labels,members)
-
-### 3. `search_testcases`
-Search and list test cases with filters, sorting, and pagination.
-- **Params:** `projectId`, `search?`, `filters?`, `page?`, `limit?`, `sortBy?`, `sortOrder?`
-
-### 4. `get_testcase`
-Get full details of a test case including test steps.
-- **Params:** `projectId`, `testcaseId`
-
-### 5. `manage_testcase`
-Create, bulk create, update, or delete test cases.
-- **Actions:** `create`, `create_bulk`, `update`, `delete`
-- **Params:** `projectId`, `action`, + action-specific params (title, summary, priority, folder_id, labels, test_steps, testcases, ids, field, value)
-
-### 6. `manage_folder`
-Create, rename, move, or delete folders across all sections.
-- **Actions:** `create`, `rename`, `move`, `delete`
-- **Params:** `projectId`, `action`, `section?`, `name?`, `folderId?`, `parentId?`
-
-### 7. `search_test_cycles`
-List and search test cycles with execution progress.
-- **Params:** `projectId`, `search?`, `folderId?`, `status?`, `page?`, `limit?`
-
-### 8. `manage_test_cycle`
-Full test cycle lifecycle management.
-- **Actions:** `create`, `update`, `delete`, `get_details`, `get_testcases`, `link_testcases`, `unlink_testcases`, `assign_testcases`
-- **Params:** `projectId`, `action`, `cycleId?`, + action-specific params
-
-### 9. `execute_tests`
-Record test execution results (single or bulk). This is the most critical tool for test execution workflows.
-- **Params:** `projectId`, `cycleId`, `results` (JSON array with testcase_id, execution_status, actual_result?, environment?)
-- Auto-detects single vs bulk execution by array length
-
-### 10. `manage_test_plan`
-Full test plan lifecycle management.
-- **Actions:** `create`, `update`, `delete`, `list`, `get_details`, `link_cycles`, `unlink_cycles`, `get_cycles`, `get_testcases`
-- **Params:** `projectId`, `action`, `planId?`, + action-specific params
-
-### 11. `get_report`
-Unified reporting with 40+ report types covering execution, coverage, trends, team, defects, and AI insights.
-- **Params:** `projectId`, `report_type`, `test_cycle_ids?`, `test_plan_ids?`, `startDate?`, `endDate?`, `granularity?`
-- **Report types:** execution_summary, execution_by_cycle, execution_by_tester, execution_by_priority, execution_by_environment, execution_by_folder, requirement_coverage, traceability_matrix, failed_requirements, uncovered_requirements, testcase_coverage, unlinked_testcases, defects_by_folder, tester_workload, testcase_distribution, execution_trend, execution_burnup, execution_burndown, test_creation, cycle_comparison, scorecard_by_folder, scorecard_by_tester, created_vs_executed, execution_by_automation, defects_by_cycle, defects_by_tester, requirement_coverage_trend, flaky_tests, release_readiness, risk_heatmap_folder, risk_heatmap_feature, testcase_quality, predictive_failure, smart_prioritization, tester_effectiveness, stale_tests, defect_hotspots, cycle_health, suite_optimization, requirement_risk_matrix, execution_velocity, project_health
-
-## Configuration
+<details>
+<summary><strong>Cursor</strong></summary>
 
-### Environment Variables
+Add to `.cursor/mcp.json` in your project root:
 
-- **`TESTKASE_API_BASE_URL`**: API base URL (default: `https://apiqa.testkase.com`)
-- **`TESTKASE_PAT_TOKEN`**: Your Personal Access Token (required)
-
-### Using with Different Environments
-
-**Production:**
-```json
-"env": {
-  "TESTKASE_API_BASE_URL": "https://api.testkase.com",
-  "TESTKASE_PAT_TOKEN": "xyz_your_token"
-}
-```
-
-**Local Development:**
 ```json
-"env": {
-  "TESTKASE_API_BASE_URL": "http://localhost:8080",
-  "TESTKASE_PAT_TOKEN": "xyz_your_token"
+{
+  "mcpServers": {
+    "testkase": {
+      "command": "npx",
+      "args": ["-y", "@testkase/mcp-server"],
+      "env": {
+        "TESTKASE_API_BASE_URL": "https://api.testkase.com",
+        "TESTKASE_PAT_TOKEN": "xyz_your_token_here"
+      }
+    }
+  }
 }
 ```
+</details>
 
-## Migration from v2.0
+### 3. Restart your agent and start talking
 
-v2.1 is a redesign of the tool surface. Key changes:
+```
+"List my projects"
+"Create a login test case in PRJ-1001 with steps"
+"Run TEST-1 as pass in cycle TCYCLE-5"
+"Show me the execution summary for PRJ-1001"
+```
 
-| v2 (14 tools) | v3 (11 tools) |
-|---|---|
-| `get_my_projects` + `set_active_project` + `get_active_project` | `list_projects` (stateless) |
-| `get_folders` + `get_labels` | `get_project_structure` (combined) |
-| `get_testcases` | `search_testcases` |
-| `get_testcase_detail` | `get_testcase` |
-| `create_testcase` + `create_bulk_testcase` + `update_testcase_field` + `delete_testcase` | `manage_testcase` (action-based) |
-| `create_folder` | `manage_folder` (full CRUD, all sections) |
-| N/A | `search_test_cycles` (NEW) |
-| N/A | `manage_test_cycle` (NEW) |
-| N/A | `execute_tests` (NEW) |
-| N/A | `manage_test_plan` (NEW) |
-| N/A | `get_report` (NEW - 40+ report types) |
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all accessible projects |
+| `get_project_structure` | Get folders, labels, members, and field options for a project |
+| `search_testcases` | Search test cases by text, folder, filters, sorting, and pagination |
+| `get_testcase` | Get full test case details including steps |
+| `manage_testcase` | Create, bulk create, update, or delete test cases; add, edit, delete or reorder test steps |
+| `manage_folder` | Create, rename, move, or delete folders (all sections) |
+| `search_test_cycles` | Search test cycles with execution progress |
+| `manage_test_cycle` | Full cycle lifecycle — CRUD, link/unlink/assign test cases |
+| `execute_tests` | Record execution results — manual (default) or as a CI/automation run |
+| `manage_test_plan` | Full plan lifecycle — CRUD, link/unlink cycles, view test cases |
+| `get_report` | Pull from 40+ report types (see below) |
+
+### Reporting
+
+`get_report` covers execution, coverage, trends, team, defect, and insight report types (insights are computed from your data and use no AI credits):
+
+| Category | Report Types |
+|----------|-------------|
+| **Execution** | `execution_summary`, `execution_by_cycle`, `execution_by_tester`, `execution_by_priority`, `execution_by_environment`, `execution_by_folder`, `execution_by_automation` |
+| **Coverage** | `requirement_coverage`, `traceability_matrix`, `failed_requirements`, `uncovered_requirements`, `testcase_coverage`, `unlinked_testcases` |
+| **Trends** | `execution_trend`, `execution_burnup`, `execution_burndown`, `test_creation`, `requirement_coverage_trend`, `execution_velocity` |
+| **Comparison** | `cycle_comparison`, `created_vs_executed`, `scorecard_by_folder`, `scorecard_by_tester` |
+| **Team** | `tester_workload`, `testcase_distribution`, `tester_effectiveness` |
+| **Defects** | `defects_by_cycle`, `defects_by_tester`, `defects_by_folder`, `defect_hotspots` |
+| **Insights** | `predictive_failure`, `smart_prioritization`, `testcase_quality`, `stale_tests`, `flaky_tests`, `suite_optimization` |
+| **Risk & Release** | `release_readiness`, `risk_heatmap_folder`, `risk_heatmap_feature`, `requirement_risk_matrix`, `cycle_health`, `project_health` |
+
+---
 
-## Troubleshooting
+## Configuration
 
-### "Authentication required" error
-- Verify your PAT token is correct and starts with `xyz_`
-- Check that the token hasn't been revoked or expired
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `TESTKASE_PAT_TOKEN` | Yes | — | Personal Access Token (starts with `xyz_`) |
+| `TESTKASE_API_BASE_URL` | No | `https://api.testkase.com` | API endpoint |
+| `TESTKASE_ORGANIZATION_ID` | No | your first organization | Set this if you belong to more than one organization |
+| `TESTKASE_APP_URL` | No | `https://test-management.testkase.com` | Base for the links returned with results |
 
-### Tool not showing up
-1. Restart your AI agent completely
-2. Check the config file path is correct
-3. Verify the JSON syntax is valid
+---
 
-### API connection issues
-- Check that the API base URL is correct
-- Verify the TestKase API is accessible
+## Troubleshooting
 
-## Documentation
+| Problem | Solution |
+|---------|----------|
+| "Authentication required" | Verify your token starts with `xyz_` and hasn't expired |
+| Tool not showing up | Restart your AI agent completely; check JSON syntax in config |
+| API connection errors | Verify `TESTKASE_API_BASE_URL` is reachable |
 
-- [TestKase Documentation](https://docs.testkase.com)
-- [Model Context Protocol](https://modelcontextprotocol.io)
+---
 
-## Support
+## Links
 
-- Email: support@testkase.com
-- Website: [testkase.com](https://testkase.com)
+- [TestKase](https://testkase.com) — Product website
+- [Documentation](https://docs.testkase.com) — Full platform docs
+- [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol spec
 
 ## License
 
 MIT
+
+---
+
+<p align="center">
+  Built by <a href="https://testkase.com">TestKase</a>
+</p>