@testkase/mcp-server 2.0.13 → 2.2.0

package/README.md

@@ -1,229 +1,187 @@
-# @testkase/mcp-server
-
-[![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.
-
-## 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
-
-## Installation
-
-### Global Installation (Recommended)
-
-```bash
-npm install -g @testkase/mcp-server
-```
-
-### Local Installation
-
-```bash
-npm install @testkase/mcp-server
-```
-
-## Quick Start
-
-### 1. Get Your PAT Token
-
-1. Log in to [TestKase](https://apiqa.testkase.com)
-2. Navigate to **Settings → Personal Access Tokens**
-3. Click **"Generate New Token"**
-4. Copy the token (starts with `xyz_`)
-
-### 2. Configure Your AI Agent
-
-#### For Claude Desktop
-
-Edit your Claude config file:
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "testkase": {
-      "command": "npx",
-      "args": ["-y", "@testkase/mcp-server"],
-      "env": {
-        "TESTKASE_API_BASE_URL": "https://apiqa.testkase.com",
-        "TESTKASE_PAT_TOKEN": "xyz_your_pat_token_here"
-      }
-    }
-  }
-}
-```
-
-#### For GitHub Copilot (VS Code)
-
-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`
-
-```json
-{
-  "mcpServers": {
-    "testkase": {
-      "command": "npx",
-      "args": ["-y", "@testkase/mcp-server"],
-      "env": {
-        "TESTKASE_API_BASE_URL": "https://apiqa.testkase.com",
-        "TESTKASE_PAT_TOKEN": "xyz_your_pat_token_here"
-      }
-    }
-  }
-}
-```
-
-### 3. Restart Your AI Agent
-
-- **Claude Desktop**: Close and reopen completely
-- **VS Code**: Restart VS Code
-
-### 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
-
-## Configuration
-
-### Environment Variables
-
-- **`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"
-}
-```
-
-## Usage Examples
-
-### 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"
-```
-
-### 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"
-```
-
-## 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
-
-### 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
-- 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
-
-- [TestKase Documentation](https://docs.testkase.com)
-- [Model Context Protocol](https://modelcontextprotocol.io)
-
-## 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
-
-## License
-
-MIT © TestKase
-
+<p align="center">
+  <a href="https://testkase.com">
+    <img src="https://testkase.com/logo.png" alt="TestKase" width="120" />
+  </a>
+</p>
+
+<h3 align="center">@testkase/mcp-server</h3>
+
+<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>
+
+<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>
+
+---
+
+## What is this?
+
+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.
+
+**11 tools. Zero config beyond a token. Works out of the box.**
+
+## Quick Start
+
+### 1. Get a PAT token
+
+Log in to [TestKase](https://app.testkase.com) > **Settings** > **Personal Access Tokens** > **Generate New Token**
+
+### 2. Add to your AI agent
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Edit your config file:
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "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>
+
+<details>
+<summary><strong>GitHub Copilot (VS Code)</strong></summary>
+
+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
+{
+  "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>
+
+<details>
+<summary><strong>Claude Code (CLI)</strong></summary>
+
+```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>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "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>
+
+### 3. Restart your agent and start talking
+
+```
+"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"
+```
+
+---
+
+## 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 with filters, sorting, and pagination |
+| `get_testcase` | Get full test case details including steps |
+| `manage_testcase` | Create, bulk create, update, or delete test cases |
+| `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 (single or bulk) |
+| `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 AI-powered report types:
+
+| 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` |
+| **AI 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` |
+
+---
+
+## Configuration
+
+| 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 |
+
+---
+
+## Troubleshooting
+
+| 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 |
+
+---
+
+## Links
+
+- [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>