@testkase/mcp-server 2.0.12 → 2.1.0

package/README.md

@@ -3,16 +3,15 @@
 [![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)
 
-Model Context Protocol (MCP) server for TestKase API. Enables AI agents like Claude Desktop and GitHub Copilot to interact with your TestKase testcase management system.
+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.
 
 ## Features
 
-✨ **Get Testcases** - Retrieve testcases with advanced filtering and search
-📊 **Pagination** - Control page size and navigate through results
-🔍 **Advanced Filtering** - Filter by status, priority, dates, custom fields
-🔎 **Search** - Text search and AI-powered semantic search
-🔐 **Secure** - Uses Personal Access Token (PAT) authentication
-🤖 **AI-Ready** - Works with Claude Desktop, GitHub Copilot, and other MCP clients
+- **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
 
@@ -32,8 +31,8 @@ npm install @testkase/mcp-server
 
 ### 1. Get Your PAT Token
 
-1. Log in to [TestKase](https://apiqa.testkase.com)
-2. Navigate to **Settings → Personal Access Tokens**
+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_`)
 
@@ -88,52 +87,65 @@ Edit your Copilot config file:
 
 ### 4. Start Using!
 
-Ask your AI agent:
-- "Get testcases for project PRJ-1030 in organization 1171"
-- "Show high priority testcases from project ABC-123"
-- "Find testcases containing 'login' in project XYZ-456"
-
-## Available Tools (26 Total)
-
-### Testcases (12 tools)
-- **`get_testcases`** - Retrieve testcases with filtering, pagination, and search
-- **`get_testcase_detail`** - Get detailed information about a specific testcase
-- **`get_testcase_history`** - View complete change history of a testcase
-- **`create_testcase`** - Create a new testcase with optional test steps
-- **`create_bulk_testcase`** - Create multiple testcases at once
-- **`update_testcase_field`** - Update specific fields for one or multiple testcases
-- **`delete_testcase`** - Delete single or multiple testcases
-- **`clone_testcase`** - Clone an existing testcase with all its steps
-- **`create_test_step`** - Create or update test steps for a testcase
-- **`delete_test_step`** - Delete test steps from a testcase
-- **`download_testcases`** - Download testcases as CSV file
-- **`import_testcases`** - Import testcases from CSV file
-
-### Folders (4 tools)
-- **`get_folders`** - Get folder/section structure of a project
-- **`create_folder`** - Create a new folder in a project
-- **`delete_folder`** - Delete a folder and its subfolders
-- **`update_folder`** - Rename or update folder details
-
-### Labels (2 tools)
-- **`get_labels`** - Get all labels/tags available in a project
-- **`create_label`** - Create new labels for a project
-
-### Projects (1 tool)
-- **`get_my_projects`** - Get all projects the user has access to
-
-### Auth & Organization (2 tools)
-- **`get_user_profile`** - Get current logged-in user profile information
-- **`get_organization`** - Get current user organization details
-
-### Integration (3 tools)
-- **`get_mapped_issues`** - Get mapped issues for a specific testcase
-- **`search_issues`** - Search issues from integrated platforms (Jira, GitHub, GitLab)
-- **`map_issues`** - Map integration issues to a TestKase requirement/defect
-
-### AI & Issues (2 tools)
-- **`generate_testcases`** - Generate testcases using AI from requirement text
-- **`create_issue`** - Create or update a requirement or defect issue
+```
+"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"
+```
+
+## 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
 
@@ -160,41 +172,29 @@ Ask your AI agent:
 }
 ```
 
-## Usage Examples
+## Migration from v2.0
 
-### Basic Queries
-```
-"Show me testcases for project PRJ-1030 organization 1171"
-"Get high priority active testcases from project PRJ-1030 org 1171"
-"Find testcases about 'authentication' in project PRJ-1030 org 1171"
-"Show testcases updated this week in project PRJ-1030 org 1171"
-```
+v2.1 is a redesign of the tool surface. Key changes:
 
-### Detailed Information
-```
-"Get detailed information about testcase TC-123 in project PRJ-1030 org 1171"
-"Show me the history of changes for testcase TC-456 in project PRJ-1030 org 1171"
-```
-
-### Project Organization
-```
-"Show me all folders in project PRJ-1030 org 1171"
-"List all labels available in project PRJ-1030 org 1171"
-"Get all issues/defects for project PRJ-1030 org 1171"
-```
-
-### User Projects
-```
-"Show me all my projects"
-"List all projects I have access to"
-```
+| 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) |
 
 ## Troubleshooting
 
 ### "Authentication required" error
 - Verify your PAT token is correct and starts with `xyz_`
-- Check that the token hasn't been revoked
-- Ensure it hasn't expired
+- Check that the token hasn't been revoked or expired
 
 ### Tool not showing up
 1. Restart your AI agent completely
@@ -204,7 +204,6 @@ Ask your AI agent:
 ### API connection issues
 - Check that the API base URL is correct
 - Verify the TestKase API is accessible
-- Test with curl: `curl -H "Authorization: Bearer xyz_YOUR_TOKEN" https://apiqa.testkase.com/api/v1/projects/testcases/get-testcase/PROJECT_ID?organizationId=ORG_ID`
 
 ## Documentation
 
@@ -213,17 +212,9 @@ Ask your AI agent:
 
 ## Support
 
-- 📧 Email: support@testkase.com
-- 🌐 Website: [testkase.com](https://testkase.com)
-
-## Security
-
-- PAT tokens are sent securely via HTTPS
-- Tokens are validated by TestKase's backend
-- Each user has their own unique token
-- Tokens can be revoked at any time
+- Email: support@testkase.com
+- Website: [testkase.com](https://testkase.com)
 
 ## License
 
-MIT © TestKase
-
+MIT