@qase/mcp-server 1.1.7 → 2.0.0

package/docs/self-run.md

@@ -0,0 +1,270 @@
+# Self-Run Guide (Local / stdio)
+
+Run the Qase MCP Server yourself, using your own `QASE_API_TOKEN`. This is the local/stdio path: you install the package (or build from source) and your MCP client launches it as a subprocess.
+
+Prefer zero-install? Connect to the Qase-hosted MCP server instead — no local setup, no API token. See [Connect to the hosted Qase MCP](connect.md).
+
+## Prerequisites
+
+- Node.js 20+
+- Qase account with API token ([Get your token](https://app.qase.io/user/api/token))
+
+## Installation
+
+### Option 1: Install from NPM (Recommended)
+
+```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
+```
+
+## Client Setup (stdio)
+
+### 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"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+> Prefer no install and no API token? Connect Cursor to the hosted server instead — see [Connect to the hosted Qase MCP](connect.md).
+
+To run the server locally with your own token:
+
+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:
+
+```bash
+claude mcp add qase -- npx -y @qase/mcp-server
+```
+
+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:
+
+```bash
+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`).
+
+## Transports
+
+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
+# Metrics: http://localhost:3000/metrics
+```
+
+### 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
+# Metrics: http://localhost:3000/metrics
+```
+
+### 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)
+```
+
+### Monitoring
+
+When using SSE or Streamable HTTP transport, a Prometheus-compatible `/metrics` endpoint is available:
+
+```bash
+curl http://localhost:3000/metrics
+```
+
+Metrics include:
+- `qase_mcp_cache_hits_total` / `qase_mcp_cache_misses_total` - Cache hit/miss rates by tier (l1/l2)
+- `qase_mcp_cache_errors_total` - Cache errors by tier
+- `qase_mcp_circuit_breaker_state` - Redis circuit breaker state (0=closed, 1=half_open, 2=open)
+
+> **Note:** This page covers running the server yourself with your own `QASE_API_TOKEN` (self-run). It does not cover operating the hosted OAuth proxy — that is internal operator documentation, not part of this guide.
+
+## Troubleshooting
+
+Server not starting, authentication errors, or connection issues? See [Troubleshooting](troubleshooting.md).

package/docs/tools.md

@@ -0,0 +1,109 @@
+# Tool Reference
+
+The Qase MCP Server exposes **30 tools** across 6 groups: Read, QQL, Write, Composite, Escape hatch, and Meta.
+
+## Discovery model
+
+To keep context-token usage low, tools are split into two visibility tiers:
+
+- **`core`** — always listed to the MCP client, no activation needed (13 tools).
+- **`discoverable`** — hidden by default; the LLM finds and activates them on demand via `qase_discover_tools`, which searches tool names/descriptions and activates matches for the rest of the session (17 tools, mostly deletes and secondary write operations).
+
+If a tool you need isn't showing up in your client's tool list, call `qase_discover_tools` with a query (e.g. `"delete"`, `"milestone"`, `"attachment"`) to activate it first.
+
+Every tool's schema uses "label or numeric ID" strings for Qase's configurable enum fields (`priority`, `severity`, `type`, `layer`, `behavior`, `status`, `automation` on cases); the server resolves labels against the workspace's actual system-field configuration at call time. See [Case enum values](#case-enum-values) below.
+
+## Read tools
+
+| Tool | Description | Key params | Visibility |
+| --- | --- | --- | --- |
+| `qase_get` | Get any Qase entity by type and ID. Supports field projection via `fields`. `code` is required for project-scoped entities (case, suite, run, result, plan, defect, milestone, environment, shared_step, shared_parameter, configuration); optional for global entities (user, author, attachment, custom_field). | `entity` (enum: case, suite, run, result, plan, defect, milestone, environment, shared_step, shared_parameter, configuration, attachment, author, user, custom_field), `code` (optional), `id` (number or hash string), `fields` (optional string array — pass `["*"]` for all) | core |
+| `qase_project_context` | Get full project context in one call: project details, suites tree, milestones, environments, custom fields, and users. Cached for 5 minutes. Recommended as the first call when starting work with a project. | `code` | core |
+
+## QQL tools
+
+| Tool | Description | Key params | Visibility |
+| --- | --- | --- | --- |
+| `qql_search` | Search entities using Qase Query Language (QQL) with powerful filtering and cross-project queries. | `query` (1-1000 chars, QQL expression), `limit` (optional, max 100, default 10), `offset` (optional) | core |
+| `qql_help` | Get help and examples for QQL syntax. | `topic` (optional enum: syntax, entities, operators, functions, examples — omit for general overview) | core |
+
+## Write tools
+
+<details>
+<summary>Write tools (21)</summary>
+
+| Tool | Description | Key params | Visibility |
+| --- | --- | --- | --- |
+| `qase_case_upsert` | Create or update a test case. If `id` is provided, updates the existing case; if omitted, creates a new one. Enum fields (priority, severity, type, etc.) accept both labels ("high", "blocker") and numeric IDs — the server normalizes automatically. | `code`, `id` (optional), `title` (1-255 chars), `description`, `preconditions`, `postconditions`, `severity`, `priority`, `type`, `layer`, `behavior`, `automation`, `status` (all label-or-ID strings), `is_flaky`, `suite_id`, `milestone_id`, `steps` (array, supports nesting), `steps_type` (enum: classic, gherkin), `tags`, `attachments`, `custom_field` | core |
+| `qase_case_delete` | Delete a test case by project code and case ID. | `code`, `id` | discoverable |
+| `qase_defect_upsert` | Create or update a defect. If `id` is provided, updates (including status changes and resolve). If omitted, creates a new defect. Set `status: "resolved"` to resolve an existing defect. | `code`, `id` (optional), `title` (1-255 chars), `actual_result`, `severity` (enum, see [below](#case-enum-values)), `status` (enum: open, in_progress, resolved, invalid), `tags`, `attachments`, `custom_field` | core |
+| `qase_defect_delete` | Delete a defect by project code and defect ID. | `code`, `id` | discoverable |
+| `qase_run_upsert` | Create or update a test run. If `id` is provided, updates; if omitted, creates. | `code`, `id` (optional), `title` (1-255 chars), `description`, `environment_id`, `milestone_id`, `plan_id`, `cases` (case ID array), `tags`, `is_autotest`, `start_time`/`end_time` (RFC3339), `custom_field` | core |
+| `qase_run_complete` | Mark a test run as complete. | `code`, `id` | discoverable |
+| `qase_run_delete` | Delete a test run. | `code`, `id` | discoverable |
+| `qase_result_record` | Record one or more test results into a run. A single entry uses the single-result API, multiple entries use bulk. Each result must include a status; `case_id` is recommended. | `code`, `run_id`, `results` (array, min 1) — each result: `case_id` (optional), `status` (enum: passed, failed, blocked, skipped, invalid), `comment`, `stacktrace`, `time_ms`, `defect` (bool), `steps` (array with `position`, `status`, `comment`, `attachments`), `attachments`, `custom_field` | core |
+| `qase_result_delete` | Delete a test result by run ID and result hash. | `code`, `run_id`, `hash` | discoverable |
+| `qase_suite_upsert` | Create or update a test suite. If `id` is provided, updates the existing suite; if omitted, creates a new one. | `code`, `id` (optional), `title` (1-255 chars), `description`, `preconditions`, `parent_id` (for nesting) | discoverable |
+| `qase_suite_delete` | Delete a test suite. If `delete_cases` is true, removes all cases in the suite; if false or omitted, cases are moved to the parent suite. | `code`, `id`, `delete_cases` (optional bool) | discoverable |
+| `qase_milestone_upsert` | Create or update a milestone. If `id` is provided, updates the existing milestone; if omitted, creates a new one. | `code`, `id` (optional), `title` (1-255 chars), `description`, `status` (enum: active, completed), `due_date` (Unix timestamp) | discoverable |
+| `qase_milestone_delete` | Delete a milestone by project code and milestone ID. | `code`, `id` | discoverable |
+| `qase_plan_upsert` | Create or update a test plan. If `id` is provided, updates the existing plan; if omitted, creates a new one. | `code`, `id` (optional), `title` (1-255 chars), `description`, `cases` (case ID array) | discoverable |
+| `qase_plan_delete` | Delete a test plan by project code and plan ID. | `code`, `id` | discoverable |
+| `qase_shared_step_upsert` | Create or update a shared step. If `hash` is provided, updates the existing shared step; if omitted, creates a new one. Shared steps are reusable steps included in multiple test cases. | `code`, `hash` (optional), `title` (1-255 chars), `steps` (array: `action`, `expected_result`, `data`, `attachments`) | discoverable |
+| `qase_shared_step_delete` | Delete a shared step by project code and hash. | `code`, `hash` | discoverable |
+| `qase_environment_upsert` | Create or update a test environment. If `id` is provided, updates the existing environment; if omitted, creates a new one. | `code`, `id` (optional), `title` (1-255 chars), `description`, `slug`, `host` | discoverable |
+| `qase_environment_delete` | Delete a test environment by project code and environment ID. | `code`, `id` | discoverable |
+| `qase_attachment_upload` | Upload a file attachment. Accepts the file as a base64 encoded string or an absolute path. Returns the attachment hash that can be referenced in test cases and results. | `code`, `file` (base64 string or absolute path), `filename` | discoverable |
+| `qase_attachment_delete` | Delete an attachment by its hash. | `hash` | discoverable |
+
+</details>
+
+## Composite tools
+
+Composite tools chain several underlying operations into one call, so an agent avoids multi-step round-trips for common workflows.
+
+| Tool | Description | Key params | Visibility |
+| --- | --- | --- | --- |
+| `qase_ci_report` | Report CI/CD test results in one call: creates a run, records all results, and optionally completes the run. Replaces the 3-4 step manual workflow of create_run → bulk_create_results → complete_run. Designed for CI pipeline integration. | `code`, `title` (1-255 chars), `environment_id` (optional), `results` (array, min 1: `case_id`, `status` (enum: passed, failed, blocked, skipped, invalid), `comment`, `time_ms`, `stacktrace`, `defect`, `attachments`), `complete` (default true), `is_autotest` (default true) | core |
+| `qase_regression_run` | Set up a regression test run in one call. Accepts case selection by suite IDs, explicit case IDs, or plan ID. Creates the run and adds all matching cases. Replaces the multi-step workflow of find cases → create run → add cases. | `code`, `title` (1-255 chars), `description`, `environment_id`, `milestone_id`, `plan_id`, `suite_ids` (array), `include_cases` (array) | core |
+| `qase_triage_defect` | Create a defect from a test failure and optionally link it to failed results. Streamlines the triage workflow: create defect → link to failing tests. | `code`, `title` (1-255 chars), `severity` (enum, see [below](#case-enum-values)), `actual_result`, `description`, `run_id` (optional, informational), `failed_result_ids` (result hashes, optional), `tags`, `attachments`, `custom_field` | core |
+
+## Escape hatch
+
+| Tool | Description | Key params | Visibility |
+| --- | --- | --- | --- |
+| `qase_api` | Direct Qase REST API call for endpoints not covered by other tools. Pass the HTTP method, path (starting with `/v1/`), and optional body/query. Use this when the dedicated tools do not cover your use case. See [developers.qase.io](https://developers.qase.io) for the API reference. | `method` (enum: GET, POST, PUT, PATCH, DELETE — default GET), `path` (e.g. `/v1/project/DEMO/run`), `body` (optional object, for POST/PUT/PATCH), `query` (optional object) | core |
+
+## Meta
+
+| Tool | Description | Key params | Visibility |
+| --- | --- | --- | --- |
+| `qase_discover_tools` | Search for and activate additional Qase tools. By default, only core tools are visible. Use this to find tools for specific needs: deletions, milestone management, attachments, etc. Found tools are automatically activated and become available for use. | `query` (optional, matches tool name/description), `category` (optional enum: read, write, delete, composite, all), `activate` (optional bool, default true) | core |
+
+## Case enum values
+
+Test case enum fields (`priority`, `severity`, `type`, `layer`, `behavior`, `status`, `automation`) are **workspace-configurable system fields**, not fixed literals in the tool schema — each Qase workspace can rename/reorder its own options. Tool calls accept either the field's label (e.g. `"high"`, `"blocker"`), its slug, or its numeric ID as a string; the server resolves the value against the workspace's live system-field configuration (fetched from the Qase API and cached for 5 minutes — see `src/utils/case-enums.ts`) before sending the request.
+
+The `automation` field is the one exception with a fixed, documented mapping (translated internally to the API's `isManual`/`isToBeAutomated` fields):
+
+| Value | Meaning |
+| --- | --- |
+| `0` | Manual (not automated) |
+| `1` | To be automated |
+| `2` | Automated |
+
+`priority` has a conventional (but still workspace-configurable) numeric mapping:
+
+| Value | Meaning |
+| --- | --- |
+| `0` | Not set |
+| `1` | High |
+| `2` | Medium |
+| `3` | Low |
+
+Two tools use **fixed** (non-configurable) Zod enums instead of workspace system fields:
+
+- **Defect `severity`** (`qase_defect_upsert`, `qase_triage_defect`): `undefined`, `blocker`, `critical`, `major`, `normal`, `minor`, `trivial`.
+- **Defect `status`** (`qase_defect_upsert`): `open`, `in_progress`, `resolved`, `invalid`.
+- **Result `status`** (`qase_result_record`, `qase_ci_report`): `passed`, `failed`, `blocked`, `skipped`, `invalid` (result *steps* use the same set minus `invalid`).
+- **Milestone `status`** (`qase_milestone_upsert`): `active`, `completed`.

package/docs/troubleshooting.md

@@ -0,0 +1,144 @@
+# Troubleshooting
+
+Issues are grouped by how you're connecting: the [hosted connector](connect.md) (OAuth, no local install) or a [self-run](self-run.md) server (your own `QASE_API_TOKEN`). If you're not sure which applies, most people using the hosted server at `https://mcp.qase.io/mcp` should look at the **Hosted Connector / OAuth** section first.
+
+## Authentication Errors (Self-Run)
+
+**Error**: `Authentication failed: Please check your QASE_API_TOKEN`
+
+This means the server is running locally (self-run) and rejected the token it was given.
+
+**Solution**:
+1. Verify your API token is correct: https://app.qase.io/user/api/token
+2. Ensure `QASE_API_TOKEN` is set in your environment or MCP client config's `env` section
+3. Check for extra spaces or stray quotes around the token value
+4. If you're on the hosted connector instead (no `QASE_API_TOKEN` involved), see [Hosted Connector / OAuth](#hosted-connector--oauth) below
+
+## Hosted Connector / OAuth
+
+These apply when connecting to the Qase-hosted server (`https://mcp.qase.io/mcp`) — see [Connect to the hosted Qase MCP](connect.md). There's no `QASE_API_TOKEN` here; authentication is a browser-based OAuth sign-in to your Qase account.
+
+### Access denied / Enterprise plan required
+
+The hosted Qase MCP is available on the **Enterprise** plan in Qase. If your workspace is on another plan, requests are rejected with an access/plan error — the connector may sign in but tool calls fail with a plan-related message.
+
+**Solution**: upgrade to the Enterprise plan, or [run the server yourself](self-run.md) with your own `QASE_API_TOKEN` (works on any plan).
+
+### Connector doesn't appear, or won't connect
+
+**Solution**:
+1. Confirm the server URL is exactly `https://mcp.qase.io/mcp` — no trailing slash variations, no surrounding quotes (see the clean-URL footgun below)
+2. Confirm your MCP client supports remote (HTTP) servers with OAuth 2.1 — older clients or stdio-only integrations can't connect to a hosted URL
+3. Restart your MCP client completely (close and reopen) after adding the server
+4. Check that your network/firewall allows outbound HTTPS to `mcp.qase.io`
+
+### "Auth required" or empty tool list after connecting
+
+If you completed the browser sign-in but the client still reports the connector needs authorization, or shows zero tools:
+
+**Solution**:
+1. Make sure you actually completed the sign-in flow in the browser tab/window it opened — some clients silently fail if that tab is closed early
+2. Try disconnecting and reconnecting the connector (not just refreshing the client)
+3. If reconnecting doesn't help, follow the full remove-and-re-add steps below — a stale or partially-completed OAuth session is a common cause
+4. Confirm you're signed in to the correct Qase account/workspace in your browser — if you have multiple Qase sessions, the wrong one may be active
+
+### Clean-URL footgun: stray quote or `%22` breaks OAuth
+
+A very common cause of persistent auth failures: the server URL got saved with an extra quote character around it, e.g. `"https://mcp.qase.io/mcp"` or its URL-encoded form `https://mcp.qase.io/mcp%22`. This can happen from copy-pasting a URL out of JSON, a table, or a chat message that included the quotes.
+
+That stray character poisons the OAuth callback — it changes the client's registered redirect/resource identifiers, so the authorization server and the client end up disagreeing about the URL, and sign-in fails (or appears to succeed but leaves an empty tool list).
+
+**This is not fixable by editing the URL in place.** Once a client has registered or cached an OAuth session against the bad URL, editing the field to remove the quote isn't enough — the client may still replay the old (poisoned) auth request from its cache.
+
+**Solution**:
+1. Fully **remove** the server entry from your MCP client (don't just edit it)
+2. Re-**add** it as a new entry
+3. Type the URL by hand: `https://mcp.qase.io/mcp` — no surrounding quotes, no extra characters
+4. Complete the browser sign-in again from this fresh entry
+
+### Browser sign-in is required
+
+The hosted connector authenticates via OAuth in your default browser — there's no token to paste in. If your MCP client is running in an environment without a browser available (e.g. certain headless or remote setups), the sign-in step can't complete. Use a client/environment that can open a browser, or fall back to the [self-run guide](self-run.md) with your own `QASE_API_TOKEN`.
+
+### Session expires after 7 days of inactivity
+
+An active hosted-connector session stays valid for **7 days**. As long as you use the connector within any 7-day window, it keeps working with no re-authorization. If a full week passes with no activity, the session expires and you'll be asked to sign in again.
+
+**Solution**: when the client reports that authorization is needed, re-run the sign-in flow — it opens your browser; complete the Qase login and the connector resumes. No need to remove and re-add the server.
+
+## 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 (self-run) or the correct URL (hosted)
+2. For self-run: check that `QASE_API_TOKEN` is set in the `env` section
+3. For the hosted connector: check the [Hosted Connector / OAuth](#hosted-connector--oauth) section above, especially the clean-URL footgun
+4. Restart your MCP client completely (close and reopen)
+5. Check the MCP client logs for connection errors
+6. For self-run from source, 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` (self-run) — the hosted connector always runs the latest version
+2. If upgrading from v1, tool names have changed — see [MIGRATION.md](../MIGRATION.md)
+3. Restart your MCP client after updating
+
+## Still stuck?
+
+- **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qase/mcp-server",
-  "version": "1.1.7",
+  "version": "2.0.0",
   "mcpName": "io.qase/mcp-server",
   "description": "Official MCP server for Qase Test Management Platform",
   "type": "module",
@@ -54,6 +54,7 @@
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "test:integration": "REDIS_TEST_URL=${REDIS_TEST_URL:-redis://localhost:6379} jest src/cache/layered.integration.test.ts",
     "inspector": "npx @modelcontextprotocol/inspector node build/index.js",
     "start": "node build/index.js",
     "start:stdio": "node build/index.js --transport stdio",
@@ -70,9 +71,11 @@
     "axios": "^1.13.5",
     "express": "^4.18.2",
     "form-data": "^4.0.5",
+    "jose": "^6.1.3",
+    "lru-cache": "^11.3.5",
     "neverthrow": "^8.2.0",
-    "npm": "^11.12.1",
-    "qase-api-client": "^1.1.7",
+    "npm": "^12.0.1",
+    "qase-api-client": "^1.1.10",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.24.3"
   },
@@ -80,8 +83,10 @@
     "@types/express": "^4.17.21",
     "@types/jest": "^29.5.12",
     "@types/node": "^20.11.24",
+    "@types/supertest": "^6.0.3",
     "@typescript-eslint/eslint-plugin": "^8.26.1",
     "@typescript-eslint/parser": "^8.26.1",
+    "axios-mock-adapter": "^2.1.0",
     "eslint": "^9.22.0",
     "eslint-config-prettier": "^10.1.1",
     "eslint-plugin-prettier": "^5.2.3",
@@ -89,10 +94,14 @@
     "jest": "^29.7.0",
     "lint-staged": "^16.2.3",
     "prettier": "^3.4.2",
+    "supertest": "^7.2.2",
     "ts-jest": "^29.1.2",
     "typescript": "^5.3.3"
   },
   "overrides": {
     "js-yaml@3": "3.14.2"
+  },
+  "optionalDependencies": {
+    "ioredis": "^5.10.1"
   }
 }

package/server.json

@@ -8,12 +8,12 @@
     "url": "https://github.com/qase-tms/qase-mcp-server",
     "source": "github"
   },
-  "version": "1.1.7",
+  "version": "2.0.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@qase/mcp-server",
-      "version": "1.1.7",
+      "version": "2.0.0",
       "transport": {
         "type": "stdio"
       },
@@ -33,6 +33,12 @@
       ]
     }
   ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.qase.io/mcp"
+    }
+  ],
   "_meta": {
     "io.modelcontextprotocol.registry/publisher-provided": {
       "privacyPolicyUrl": "https://qase.io/privacy"

package/build/operations/attachments.d.ts

@@ -1,8 +0,0 @@
-/**
- * Attachments Operations
- *
- * Implements all MCP tools for managing attachments in Qase.
- * Attachments are files associated with test cases, steps, and results.
- */
-export {};
-//# sourceMappingURL=attachments.d.ts.map

package/build/operations/attachments.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../src/operations/attachments.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}