@qase/mcp-server 1.1.7 → 2.0.0

package/README.md

@@ -1,585 +1,119 @@
 # Qase MCP Server
 
-Official Model Context Protocol (MCP) server for [Qase Test Management Platform](https://qase.io).
+Official [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [Qase Test Management Platform](https://qase.io) — connect AI assistants to your test cases, runs, defects, and more.
 
 [![npm version](https://img.shields.io/npm/v/@qase/mcp-server)](https://www.npmjs.com/package/@qase/mcp-server)
-[![npm downloads](https://img.shields.io/npm/dm/@qase/mcp-server)](https://www.npmjs.com/package/@qase/mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.qase%2Fmcp--server-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.qase%2Fmcp-server)
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Use Cases](#use-cases)
+- [Quick Start](#quick-start)
+  - [Use the hosted Qase MCP (recommended)](#use-the-hosted-qase-mcp-recommended)
+  - [Run it yourself](#run-it-yourself)
+- [Upgrading from v1](#upgrading-from-v1)
+- [Tools](#tools)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
+- [Links](#links)
 
 ## Overview
 
-The Qase MCP Server provides seamless integration between AI assistants (Claude, Cursor, etc.) and the Qase Test Management Platform. It enables AI assistants to interact with your test cases, test runs, defects, and other Qase entities through a standardized protocol.
+The Qase MCP Server lets AI assistants (Claude, Cursor, Codex, and any other MCP client) read and write Qase test cases, runs, results, defects, suites, milestones, and more — through a standardized protocol, with no custom integration code.
 
-### Features
+**Features:**
 
-- ✅ **Complete Qase API Coverage** - Access all Qase entities and operations
-- ✅ **QQL Support** - Powerful Qase Query Language for advanced searches
-- ✅ **Type-Safe** - Full TypeScript implementation with comprehensive validation
-- ✅ **Custom Domains** - Support for enterprise custom domains
+- **29 task-oriented tools** (30 total, including `qase_discover_tools`) — consolidated from 83 v1 tools for lower token usage and better LLM accuracy
+- **Composite tools** — multi-step workflows in a single call: CI reporting, defect triage, regression run setup
+- **QQL support** — Qase Query Language for advanced searches across cases, runs, results, defects, and plans
+- **Project context bootstrap** — one call returns full project structure (suites, milestones, environments, users, custom fields)
+- **Tool discovery** — secondary tools stay hidden until needed, keeping the default tool list small
+- **Hosted or self-run** — connect to `https://mcp.qase.io/mcp` with just your Qase login, or run the server locally with your own API token
+- **Tenant-safe caching & HTTP resilience** — two-tier cache (in-memory + optional Redis), connection pooling, retry with backoff
+- **Escape hatch** — direct REST API access for any endpoint via `qase_api`
 
-### Supported Entities
+## Use Cases
 
-The server provides tools for managing:
+| Scenario | Example prompt | Tool |
+| --- | --- | --- |
+| Bootstrap project context | "Show me the structure of project DEMO — suites, milestones, environments" | `qase_project_context` |
+| Create or update a test case | "Create a high-priority smoke test case in project DEMO titled 'Login with valid credentials'" | `qase_case_upsert` |
+| Report CI results | "Report these CI results for project DEMO: case 1 passed, case 2 failed with 'timeout error'" | `qase_ci_report` |
+| Triage a failed test | "Create a critical defect for the login timeout failure in run #42" | `qase_triage_defect` |
+| Search with QQL | "Find all failed test results from the last 7 days in project DEMO" | `qql_search` |
 
-- **Projects** - Create and manage test projects
-- **Test Cases** - Create, update, and organize test cases
-- **Test Suites** - Organize tests into hierarchical suites
-- **Test Runs** - Execute test runs and track progress
-- **Test Results** - Record and analyze test execution results
-- **Test Plans** - Define and manage test plans
-- **Defects** - Track and manage bugs
-- **Milestones** - Organize work by sprints/releases
-- **Environments** - Manage test environments
-- **Shared Steps** - Create reusable test steps
-- **Shared Parameters** - Define reusable test data
-- **Attachments** - Upload and manage files
-- **Custom Fields** - Define custom metadata
-- **Configurations** - Manage test configurations
-- **Users** - User management operations
-- **QQL Search** - Advanced cross-project queries
+See [Tools](#tools) and [docs/tools.md](docs/tools.md) for the full reference.
 
-## Installation
+## Quick Start
 
-### Prerequisites
+### Use the hosted Qase MCP (recommended)
 
-- Node.js 18+
-- Qase account with API token ([Get your token](https://app.qase.io/user/api/token))
+No install, no API token — connect to the Qase-hosted server and sign in with your Qase account.
 
-### Option 1: Install from NPM (Recommended)
+> **Note:** The hosted Qase MCP is available on the **Enterprise** plan in Qase. On other plans, [run the server yourself](#run-it-yourself) with your own API token.
 
-```bash
-npm install -g @qase/mcp-server
-```
-
-### Option 2: Install from Source (Development)
-
-```bash
-# Clone the repository
-git clone https://github.com/qase-tms/qase-mcp-server.git
-cd qase-mcp-server
-
-# Install dependencies
-npm install
-
-# Build the server
-npm run build
-```
-
-## Configuration
-
-### Environment Variables
-
-Create a `.env` file or set environment variables:
-
-```bash
-# Required: Your Qase API token
-QASE_API_TOKEN=your_api_token_here
-
-# Optional: Custom API domain for enterprise customers
-QASE_API_DOMAIN=api.qase.io
-```
-
-Get your API token from: https://app.qase.io/user/api/token
-
-### Custom Domains (Enterprise)
-
-If you're using Qase Enterprise with a custom domain:
-
-```bash
-QASE_API_DOMAIN=api.yourcompany.qase.io
-```
-
-## Integration
-
-### Claude Desktop
-
-Add to your Claude Desktop configuration file:
-
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "qase": {
-      "command": "npx",
-      "args": ["-y", "@qase/mcp-server"],
-      "env": {
-        "QASE_API_TOKEN": "your_api_token_here"
-      }
-    }
-  }
-}
-```
-
-Or, if installed from source:
-
-```json
-{
-  "mcpServers": {
-    "qase": {
-      "command": "node",
-      "args": ["/absolute/path/to/qase-mcp-server/build/index.js"],
-      "env": {
-        "QASE_API_TOKEN": "your_api_token_here"
-      }
-    }
-  }
-}
-```
+- **Claude** — open **Settings → Connectors**, find **Qase Test Management**, click **Connect**.
+- **Cursor** — add `{"mcpServers": {"qase": {"url": "https://mcp.qase.io/mcp"}}}` to `.cursor/mcp.json`.
+- **Codex** — add the URL `https://mcp.qase.io/mcp` in **Settings → MCPs → Add server**, or configure `~/.codex/config.toml` for the CLI.
+- **VS Code** — add `{"servers": {"qase": {"type": "http", "url": "https://mcp.qase.io/mcp"}}}` to `.vscode/mcp.json`, or run **MCP: Add Server**.
 
-### Cursor
-
-1. Open Cursor Settings
-2. Navigate to MCP settings
-3. Add the Qase MCP server:
-
-```json
-{
-  "mcpServers": {
-    "qase": {
-      "command": "npx",
-      "args": ["-y", "@qase/mcp-server"],
-      "env": {
-        "QASE_API_TOKEN": "your_api_token_here"
-      }
-    }
-  }
-}
-```
-
-### Claude Code
-
-You can add the Qase MCP server to Claude Code using the CLI command:
+Full per-client steps, other clients, and the active-workspace model: **[docs/connect.md](docs/connect.md)**.
 
-```bash
-claude mcp add qase -- npx -y @qase/mcp-server
-```
+### Run it yourself
 
-Set the required environment variable:
-
-```bash
-export QASE_API_TOKEN=your_api_token_here
-```
-
-Alternatively, add a `.mcp.json` file to your project root for automatic project-scoped configuration:
-
-```json
-{
-  "mcpServers": {
-    "qase": {
-      "command": "npx",
-      "args": ["-y", "@qase/mcp-server"],
-      "env": {
-        "QASE_API_TOKEN": "your_api_token_here"
-      }
-    }
-  }
-}
-```
-
-You can also use the `--scope` flag to choose where the configuration is stored:
-
-```bash
-# Project-scoped (saved in .mcp.json)
-claude mcp add --scope project qase -- npx -y @qase/mcp-server
-
-# User-scoped (available in all projects)
-claude mcp add --scope user qase -- npx -y @qase/mcp-server
-```
-
-### OpenAI Codex CLI
-
-Add a `.codex/config.json` file to your project root:
-
-```json
-{
-  "mcpServers": {
-    "qase": {
-      "command": "npx",
-      "args": ["-y", "@qase/mcp-server"],
-      "env": {
-        "QASE_API_TOKEN": "your_api_token_here"
-      }
-    }
-  }
-}
-```
-
-Set the required environment variable before running Codex:
+Install the package and provide your own API token:
 
 ```bash
+npm install -g @qase/mcp-server
 export QASE_API_TOKEN=your_api_token_here
 ```
 
-### OpenCode
-
-Add an `opencode.json` file to your project root (or `~/.config/opencode/opencode.json` for global configuration):
-
-```json
-{
-  "mcp": {
-    "qase": {
-      "type": "local",
-      "command": ["npx", "-y", "@qase/mcp-server"],
-      "environment": {
-        "QASE_API_TOKEN": "your_api_token_here"
-      }
-    }
-  }
-}
-```
-
-> **Note:** OpenCode uses a different format from other MCP clients — the command and args are combined into a single `command` array, env vars go under `environment`, and servers are nested under `mcp` (not `mcpServers`).
-
-## Usage Examples
+Then point your MCP client's stdio config at the `@qase/mcp-server` binary. Full install options, client configs (Claude Desktop, Cursor, Claude Code, Codex, OpenCode), environment variables, and transports (stdio/SSE/streamable-HTTP): **[docs/self-run.md](docs/self-run.md)**.
 
-### Basic Operations
+## Upgrading from v1
 
-#### List All Projects
-
-```
-Can you list all my Qase projects?
-```
+v2 consolidates 83 v1 tools into **29 task-oriented tools** (30 total, including a discovery tool). Tool names and response shapes have changed. See **[MIGRATION.md](MIGRATION.md)** for the complete tool mapping table, response format changes, and before/after examples.
 
-#### Create a Test Case
+## Tools
 
-```
-Create a test case in project DEMO titled "Login with valid credentials" with steps for entering username, password, and clicking login
-```
+30 tools across 6 groups (29 task-oriented tools plus `qase_discover_tools` for on-demand activation of secondary tools):
 
-#### Search with QQL
+| Group | Count | Description |
+| --- | --- | --- |
+| Read | 2 | Fetch any entity by type/ID, or bootstrap full project context in one call |
+| QQL | 2 | Search across cases, runs, results, defects, and plans with Qase Query Language |
+| Write | 21 | Create, update, and delete cases, runs, results, defects, suites, milestones, plans, shared steps, environments, and attachments |
+| Composite | 3 | Multi-step workflows in one call: CI reporting, defect triage, regression run setup |
+| Escape hatch | 1 | Direct REST API access for any endpoint not covered by the tools above |
+| Meta | 1 | `qase_discover_tools` — find and activate secondary tools on demand |
 
-```
-Find all failed test results from the last 7 days in project DEMO
-```
+Full tool-by-tool reference with parameters and the discovery model: **[docs/tools.md](docs/tools.md)**.
 
-### Advanced QQL Queries
+## Documentation
 
-#### Find Flaky Tests
-
-```
-Search for all flaky test cases in project DEMO that are not automated
-```
-
-The server will execute:
-```
-entity = "case" and project = "DEMO" and isFlaky = true and automation = "Not automated"
-```
-
-#### Find Open Blocker Defects
-
-```
-Show me all open blocker defects in project DEMO
-```
-
-#### Find Tests by Author
-
-```
-Find all test cases created by john@example.com in the last month
-```
-
-### Working with Test Runs
-
-#### Create and Execute a Test Run
-
-```
-Create a test run in project DEMO called "Sprint 24 Regression" including all test cases from the "Authentication" suite, then add a passed result for case ID 123
-```
-
-## Available Tools
-
-### Projects (6 tools)
-- `list_projects` - Get all projects
-- `get_project` - Get project details
-- `create_project` - Create new project
-- `delete_project` - Delete project
-- `grant_project_access` - Grant user/group access
-- `revoke_project_access` - Revoke access
-
-### Test Cases (8 tools)
-- `list_cases` - List all test cases
-- `get_case` - Get test case details
-- `create_case` - Create new test case
-- `update_case` - Update test case
-- `delete_case` - Delete test case
-- `bulk_create_cases` - Create multiple cases
-- `attach_external_issue` - Link external issue (Jira, etc.)
-- `detach_external_issue` - Unlink external issue
-
-### Case enum values
-
-`create_case`, `bulk_create_cases`, and `update_case` automatically normalize friendly labels to whatever numeric IDs your workspace currently configures for the built-in system fields (`priority`, `severity`, `type`, `behavior`, `status`, `layer`). The server fetches `/v1/system_field` and caches the available options so you can keep using the titles or slugs you see in Qase while still satisfying the API’s numeric requirements.
-
-The normalization does not touch `automation`/`is_flaky`, so pass those values as the API expects (strings or booleans).
-The server keeps any existing label in place when it does not match a known enum so invalid values still bubble up as errors from Qase.
-
-### Test Runs (7 tools)
-- `list_runs` - List test runs
-- `get_run` - Get run details
-- `create_run` - Create new run
-- `delete_run` - Delete run
-- `complete_run` - Mark run as complete
-- `get_run_public_link` - Get public link
-- `delete_run_public_link` - Remove public link
-
-### Test Results (6 tools)
-- `list_results` - List test results
-- `get_result` - Get result details
-- `create_result` - Create test result
-- `create_results_bulk` - Create multiple results
-- `update_result` - Update result
-- `delete_result` - Delete result
-
-### Test Plans (5 tools)
-- `list_plans` - List test plans
-- `get_plan` - Get plan details
-- `create_plan` - Create test plan
-- `update_plan` - Update test plan
-- `delete_plan` - Delete test plan
-
-### Suites (5 tools)
-- `list_suites` - List suites
-- `get_suite` - Get suite details
-- `create_suite` - Create suite
-- `update_suite` - Update suite
-- `delete_suite` - Delete suite
-
-### Defects (7 tools)
-- `list_defects` - List defects
-- `get_defect` - Get defect details
-- `create_defect` - Create defect
-- `update_defect` - Update defect
-- `delete_defect` - Delete defect
-- `resolve_defect` - Mark as resolved
-- `update_defect_status` - Update status
-
-### Milestones (5 tools)
-- `list_milestones` - List milestones
-- `get_milestone` - Get milestone details
-- `create_milestone` - Create milestone
-- `update_milestone` - Update milestone
-- `delete_milestone` - Delete milestone
-
-### Environments (5 tools)
-- `list_environments` - List environments
-- `get_environment` - Get environment details
-- `create_environment` - Create environment
-- `update_environment` - Update environment
-- `delete_environment` - Delete environment
-
-### Shared Steps (5 tools)
-- `list_shared_steps` - List shared steps
-- `get_shared_step` - Get shared step details
-- `create_shared_step` - Create shared step
-- `update_shared_step` - Update shared step
-- `delete_shared_step` - Delete shared step
-
-### Shared Parameters (5 tools)
-- `list_shared_parameters` - List parameters
-- `get_shared_parameter` - Get parameter details
-- `create_shared_parameter` - Create parameter
-- `update_shared_parameter` - Update parameter
-- `delete_shared_parameter` - Delete parameter
-
-### Supporting Entities
-- **Attachments** (4 tools) - File management
-- **Authors** (2 tools) - Author information
-- **Custom Fields** (5 tools) - Custom field management
-- **System Fields** (1 tool) - System field info
-- **Configurations** (3 tools) - Configuration management
-- **Users** (2 tools) - User management
-
-### QQL Search (2 tools)
-- `qql_search` - Execute QQL query
-- `qql_help` - Get QQL syntax help
-
-**Total: 83 tools available**
-
-## Development
-
-### Building from Source
-
-```bash
-npm run build
-```
-
-### Running Tests
-
-```bash
-# Run all tests
-npm test
-
-# Run with coverage
-npm run test:coverage
-
-# Watch mode
-npm run test:watch
-```
-
-### Linting
-
-```bash
-# Check for issues
-npm run lint
-
-# Auto-fix issues
-npm run lint -- --fix
-```
-
-### Debugging
-
-Use the MCP Inspector for interactive debugging:
-
-```bash
-npm run inspector
-```
-
-Set your API token when prompted, then interact with tools in the inspector UI.
-
-### Transport Options
-
-The server supports multiple transport types for different use cases:
-
-#### Stdio Transport (Default)
-
-Used by MCP clients like Claude Desktop and Cursor:
-
-```bash
-npm start
-# or
-npm run start:stdio
-```
-
-#### SSE Transport
-
-Server-Sent Events for web-based clients:
-
-```bash
-npm run start:sse
-# Server runs on http://localhost:3000/sse
-# Health check: http://localhost:3000/health
-```
-
-#### Streamable HTTP Transport
-
-Full HTTP-based transport with session management:
-
-```bash
-npm run start:http
-# Server runs on http://localhost:3000/mcp
-# Health check: http://localhost:3000/health
-```
-
-#### Custom Configuration
-
-```bash
-# Custom port and host
-node build/index.js --transport streamable-http --port 8080 --host 0.0.0.0
-
-# Available options:
-# --transport: stdio | sse | streamable-http (default: stdio)
-# --port: Port number (default: 3000)
-# --host: Host address (default: 0.0.0.0)
-```
-
-## Troubleshooting
-
-### Authentication Errors
-
-**Error**: `Authentication failed: Please check your QASE_API_TOKEN`
-
-**Solution**:
-1. Verify your API token is correct: https://app.qase.io/user/api/token
-2. Ensure the token is set in your environment or config file
-3. Check for extra spaces or quotes in the token value
-
-### Connection Errors
-
-**Error**: `Network error` or `ECONNREFUSED`
-
-**Solution**:
-1. Check your internet connection
-2. Verify the API domain is correct (especially for enterprise customers)
-3. Check if Qase is accessible: https://api.qase.io/v1/
-
-### SSL Certificate Errors
-
-**Error**: `unable to get local issuer certificate`
-
-This error typically occurs in corporate environments with:
-- SSL-intercepting proxy servers
-- Self-signed certificates
-- Internal Certificate Authorities (CA)
-
-**Solution**: Add the `NODE_EXTRA_CA_CERTS` environment variable pointing to your CA certificate file:
-
-```json
-{
-  "mcpServers": {
-    "qase": {
-      "command": "npx",
-      "args": ["-y", "@qase/mcp-server"],
-      "env": {
-        "QASE_API_TOKEN": "your_api_token_here",
-        "NODE_EXTRA_CA_CERTS": "/path/to/your/certificate.pem"
-      }
-    }
-  }
-}
-```
-
-To find your certificate:
-- **Corporate environments**: Contact your IT department for the CA certificate
-- **macOS**: Export from Keychain Access (System Roots → your CA → Export as .pem)
-- **Windows**: Export from Certificate Manager (certmgr.msc)
-- **Linux**: Usually in `/etc/ssl/certs/` or `/etc/pki/tls/certs/`
-
-### Custom Domain Issues
-
-**Error**: `Invalid domain` or connection errors with custom domain
-
-**Solution**:
-1. Ensure `QASE_API_DOMAIN` is set to just the domain (e.g., `api.company.qase.io`)
-2. Don't include `https://` or `/v1` in the domain
-3. Verify with your Qase administrator
-
-### No Tools Showing in MCP Client
-
-**Error**: MCP client shows "no tools, prompts or resources" or 0 tools available
-
-**Solution**:
-1. Verify your MCP configuration has the correct command and arguments
-2. Check that `QASE_API_TOKEN` is set in the `env` section
-3. Restart your MCP client completely (close and reopen)
-4. Check the MCP client logs for connection errors
-5. Verify the server is built: `npm run build`
-
-### Tool Not Found
-
-**Error**: `Unknown tool: tool_name`
-
-**Solution**:
-1. Ensure you're using the latest version: `npm update -g @qase/mcp-server`
-2. Check the tool name spelling matches the documentation
-3. Restart your MCP client after updating
+- **[docs/connect.md](docs/connect.md)** — connect to the hosted Qase MCP (Claude, Cursor, Codex, other clients)
+- **[docs/self-run.md](docs/self-run.md)** — install and run the server yourself (config, clients, transports)
+- **[docs/tools.md](docs/tools.md)** — full tool reference, groups, and the discovery model
+- **[docs/troubleshooting.md](docs/troubleshooting.md)** — auth, OAuth/connector, and SSL issues
+- **[MIGRATION.md](MIGRATION.md)** — v1 → v2 tool mapping and migration guide
 
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and linting guidelines.
 
-### Development Guidelines
+## License
 
-- Follow TypeScript best practices
-- Add unit tests for new features
-- Update documentation for new tools
-- Ensure all tests pass: `npm test`
-- Ensure linting passes: `npm run lint`
-- Maintain code coverage above 70%
+MIT License — see [LICENSE](LICENSE) for details.
 
-## License
+## Support
 
-MIT License - see [LICENSE](LICENSE) file for details
+- **Documentation**: https://docs.qase.io/en/articles/14984302-qase-mcp-server
+- **Email**: support@qase.io
+- **GitHub Issues**: https://github.com/qase-tms/qase-mcp-server/issues
 
 ## Links
 
@@ -588,13 +122,3 @@ MIT License - see [LICENSE](LICENSE) file for details
 - **API Documentation**: https://developers.qase.io
 - **MCP Protocol**: https://modelcontextprotocol.io
 - **Issue Tracker**: https://github.com/qase-tms/qase-mcp-server/issues
-
-## Support
-
-- **Documentation**: https://help.qase.io
-- **Email**: support@qase.io
-- **GitHub Issues**: https://github.com/qase-tms/qase-mcp-server/issues
-
----
-
-Made with ❤️ by [Qase](https://qase.io)

package/build/auth/client-context.d.ts

@@ -0,0 +1,12 @@
+import { AsyncLocalStorage } from 'async_hooks';
+/**
+ * Per-request storage for the OAuth `/authorize` request's `redirect_uri`.
+ *
+ * The proxy is transparent: it echoes the incoming redirect_uri back through
+ * `getClient` so the MCP SDK's local redirect_uri check passes, then forwards
+ * the request to auth.qase.io, which is the authoritative validator of a
+ * client's registered redirect URIs. Empty/undefined when no redirect_uri is
+ * present on the request.
+ */
+export declare const authorizeRedirectUriStorage: AsyncLocalStorage<string | undefined>;
+//# sourceMappingURL=client-context.d.ts.map

package/build/auth/client-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-context.d.ts","sourceRoot":"","sources":["../../src/auth/client-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,uCAA8C,CAAC"}