npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@id3-clarity/mcp-server

v1.23.0

Published

CLARITY Test Management — MCP server for Claude Desktop / Cursor / Cline / Windsurf

Readme

@id3-clarity/mcp-server

CLARITY Test Management — Model Context Protocol server. Connect Claude Desktop, Cursor, Cline, or Windsurf to your CLARITY instance and manage test cases, suites, runs, and projects entirely through natural language.

npm Node.js License: MIT


Overview

@id3-clarity/mcp-server exposes 164 tools from the CLARITY REST API as an MCP (Model Context Protocol) server. Once connected, your AI client can:

  • Create and update test cases, folders, suites, runs, requirements, and releases without leaving your editor
  • Search and inspect existing tests, execution history, and failure patterns
  • Import test cases from JSON or from AI-generated suggestions
  • Track run progress and mark individual executions as pass/fail/blocked/skipped
  • Sync requirements with Jira bidirectionally (push, link, pull-sync, conflict detection)
  • Manage releases with readiness scoring, requirement scope, and test run links
  • Schedule recurring runs, attach evidence, comment with @-mentions, and read dashboard metrics
  • Safely delete resources with a 2-step confirmation + 30-day Trash recovery

All operations are tenant-isolated, fully audit-logged, and rate-limited on the CLARITY backend. The server itself is a lightweight stdio process — no extra ports, no background daemons.


Quick Start (2 minutes)

1. Get your API token

In CLARITY, go to: Settings → API Access → MCP Tokens → + New Token

  • Name: e.g. Claude Desktop - <your name>
  • Scopes: read + write (add delete only if needed)
  • Projects: select the projects you'll work on (leave blank for org-wide access)
  • Click Create, copy the clr_... token — it is shown only once

2. Add to your AI client

Pick your client and paste the configuration. Replace only the clr_... token; all other values are pre-filled.

Claude Desktop

Config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Test environment (clarity-test.id3.com.tr):

{
  "mcpServers": {
    "clarity": {
      "command": "npx",
      "args": ["-y", "@id3-clarity/mcp-server@latest"],
      "env": {
        "CLARITY_API_URL": "https://clarity-test-api.id3.com.tr",
        "CLARITY_API_TOKEN": "clr_PASTE_YOUR_TOKEN_HERE",
        "CLARITY_LANG": "tr"
      }
    }
  }
}

Production (clarity.id3.com.tr):

{
  "mcpServers": {
    "clarity": {
      "command": "npx",
      "args": ["-y", "@id3-clarity/mcp-server@latest"],
      "env": {
        "CLARITY_API_URL": "https://clarity-api.id3.com.tr",
        "CLARITY_API_TOKEN": "clr_PASTE_YOUR_TOKEN_HERE",
        "CLARITY_LANG": "tr"
      }
    }
  }
}

Cursor

Config file: ~/.cursor/mcp.json — same JSON structure as Claude Desktop above.

{
  "mcpServers": {
    "clarity": {
      "command": "npx",
      "args": ["-y", "@id3-clarity/mcp-server@latest"],
      "env": {
        "CLARITY_API_URL": "https://clarity-api.id3.com.tr",
        "CLARITY_API_TOKEN": "clr_PASTE_YOUR_TOKEN_HERE",
        "CLARITY_LANG": "en"
      }
    }
  }
}

Cline (VSCode)

VSCode → Cline extension → Settings → MCP Servers → "Edit in JSON" → paste the same config as above.

Windsurf

Config file: ~/.windsurf/mcp.json — same structure.

3. Restart your AI client

Quit and reopen Claude Desktop / Cursor / Cline / Windsurf. The status bar will show "clarity (20 tools)" — that is correct, and not all of them.

Why 19 and not 164

An LLM's ability to pick the right tool degrades as the catalogue grows: around 78% accuracy at ten tools, collapsing past a hundred. Every extra tool makes the others harder to choose. So the server advertises a read-only core plus whichever domains you switch on, and nothing was merged or removed to get there — the full catalogue is one setting away.

Ask the assistant "what can CLARITY do?" and it will call list_capabilities, which lists every domain and what it covers. To turn one on for the session it calls enable_domain. To make it permanent, add CLARITY_MCP_DOMAINS:

"env": {
  "CLARITY_API_URL": "https://clarity-api.id3.com.tr",
  "CLARITY_API_TOKEN": "clr_...",
  "CLARITY_MCP_DOMAINS": "testcases,runs,requirements"
}

| Domain | What it covers | |---|---| | testcases | Writing test cases, suites, folders; comments, attachments, bulk operations | | runs | Creating runs and writing results, scheduled runs, flaky tests, the discovery agent | | defects | Reporting defects, triage, the retest queue and verification, defect KPIs | | requirements | Writing requirements, linking test cases, traceability, Jira/Azure mapping | | releases | Creating releases, managing scope, readiness | | delivery | Code changes, pull request review, security scans, gates and approvals | | insights | Dashboards, analytics, executive summary, environment matrix | | workspace | Projects, folders, custom fields, users, tags | | platform | Pipelines, webhooks, quota, schema discovery |

CLARITY_MCP_DOMAINS=all advertises everything, which is what installations did before this existed. It is supported and it will make the assistant worse at choosing.

Write tools are off by default

The core is read-only: every tool that writes (create_requirement, create_test_case, create_run …) sits in a domain and is not advertised until that domain is on. A domain is visibility, not permission — every call is still bounded by the token's scopes, projects and the user's role, so enabling requirements with a read-only token still answers INSUFFICIENT_SCOPE.

enable_domain is not enough in every client. It switches the domain on for the session and sends notifications/tools/list_changed (the server declares tools.listChanged). Clients that honour the notification (Claude Code) show the new tools at once; Claude Desktop was observed not to re-read its tool list (CLAR-395), so the schema never loads. The durable fix is CLARITY_MCP_DOMAINS in the config plus a client restart (or a new chat). enable_domain's answer reports toolListChangedSent and the permanentSetting to use; calling a tool whose domain is off returns DOMAIN_DISABLED with the domain and that fix.

Which domain opens which tools (generated from src/tools/domains.ts; domains.test.ts fails if this table drifts — list_capabilities returns the same lists at runtime):

| Domain | Tools it opens (beyond the core) | |---|---| | testcases | add_test_case_attachment, add_test_case_comment, bulk_add_test_case_attachments, bulk_add_test_case_comments, bulk_create_suites, bulk_create_test_cases, bulk_move_test_cases, bulk_update_test_cases, create_suite, create_test_case, delete_suite, delete_test_case, generate_tests_from_document, generate_tests_from_requirement, get_suite, import_test_cases_json, list_suites, list_test_case_comments, update_suite, update_test_case | | runs | analyze_failure_root_cause, bulk_update_execution_results, create_run, create_scheduled_run, get_discovery_run, get_failing_cases, get_flaky_tests, get_run_triage, get_test_execution_history, list_discovery_findings, list_scheduled_runs, pause_scheduled_run, run_backfill, run_transition, start_discovery_run, update_execution_result | | defects | create_defect, get_defect, get_defect_kpis, get_defect_retest_queue, list_defects, push_defect_to_jira, record_defect_verification, set_defect_commitment, transition_defect | | requirements | add_requirement_to_release, bulk_add_requirements_to_release, bulk_create_requirements, bulk_remove_requirements_from_release, create_requirement, delete_requirement, get_requirement_traceability, import_requirements_from_jira, link_requirement_to_jira, link_requirement_to_test_case, link_requirement_to_test_runs, link_requirements, link_test_run_to_covered_requirements, list_requirement_link_types, list_requirement_statuses, list_requirement_types, push_requirement_to_jira, push_requirement_update_to_jira, remove_requirement_from_release, sync_requirement, transition_requirement_in_jira, unlink_requirement_from_test_case, unlink_requirement_from_test_runs, unlink_requirements, update_requirement | | releases | add_release_exit_criterion, add_release_gate, add_test_run_to_release, answer_release_exit_criterion, apply_release_exit_criteria_template, approve_release_gate, bulk_create_releases, create_release, create_release_scope_baseline, delete_release, evaluate_release_gates, generate_release_notes, get_release_platform_readiness, get_release_readiness, list_release_sign_offs, record_decision, record_release_sign_off, remove_test_run_from_release, update_release | | delivery | act_on_pull_request, attach_scan, auto_match_code_changes, delete_code_area, deploy_precheck, env_release, env_reserve, evaluate_quality_gate, gate_publish, generate_tests_for_change, get_approval_status, get_code_change, get_code_change_diff, get_code_change_review, get_ingest_status, get_requirement_code_changes, get_scan_debt, link_code_change_to_requirement, list_branches, list_code_areas, list_pull_requests, list_scan_jobs, list_scan_profiles, propose_merge, request_approval, request_scan, resolve_finding, review_code_change, review_requirement_implementation, suggest_code_areas, sync_requirement_code_changes, upsert_code_area | | insights | get_environment_matrix, get_executive_narrative, get_project_analytics, rank_tests_by_failure_risk | | workspace | create_custom_field, create_folder, create_folder_tree, create_project, delete_folder, get_folder_tree, get_project_stats, get_user, list_custom_fields, list_folders, list_tags, list_users, update_folder, update_project | | platform | ci_trigger, clarity_propose, get_my_quota, get_schema, get_test_type_info, list_ci_run_definitions, list_pipelines, list_webhooks |

4. Test the connection

Try: "List my CLARITY projects"

The AI calls list_projects and returns your accessible projects with IDs you can use in follow-up prompts.


Keeping up to date

The configs above pin @latest, so each cold start pulls the newest published version — restarting your AI client is usually enough to update.

If you installed globally (npm i -g @id3-clarity/mcp-server), update manually:

npm i -g @id3-clarity/mcp-server@latest
npm ls -g @id3-clarity/mcp-server   # verify the version

The CLARITY backend also tells you when you're behind: every response to an outdated client starts with a clientUpdate block (your version, the current one, and the exact steps — restart for npx …@latest, npm i -g for a global install), shown as a separate "⚠️" message from 1.19.0 on, and an old version's failures say they may be caused by the version. Unsupported versions are refused with the same steps. So if the AI mentions an update, follow it before reporting a problem.

Which version am I running?

  • Ask the AI: "Which CLARITY MCP version is running?" — from 1.20.0 it calls list_capabilities, whose first field (server) gives the running version, the latest release, whether you are current, and the update steps if not.
  • CLARITY → Settings → MCP Tokens: each token shows the version it last called from and whether it is current.
  • Terminal (global install): clarity-mcp-server --version.
  • Client log: the startup line reads @id3-clarity/mcp-server <version> ready (Claude Desktop: mcp-server-clarity.log).

Prerequisites

  • Node.js 18+ (used by npx to fetch and run the server)
  • A CLARITY API token — create one at CLARITY → Settings → API Access → MCP Tokens → New Token

Tokens look like clr_<32 alphanumeric characters>.


Installation

The recommended way is npx (no global install needed). The snippet in the Quick Start section is all you need.

If you prefer a global install:

npm install -g @id3-clarity/mcp-server

Then replace "command": "npx", "args": ["-y", "@id3-clarity/mcp-server@latest"] with "command": "clarity-mcp-server" in your config.


Authentication

Creating a token

  1. Log in to CLARITY and open Settings → API Access → MCP Tokens
  2. Click + New Token
  3. Fill in:
    • Name — a human-readable label (e.g. Cursor - kaan)
    • Scopes — read, write, and/or delete (grant only what you need)
    • Project access — specific projects, or leave blank for all accessible projects
    • Expiry — optional; recommended for shared/CI tokens
  4. Click Create and copy the token immediately — it will not be shown again

Token format

clr_<32 alphanumeric characters>

Rotating a token

Go to Settings → API Access → MCP Tokens, find the token, click Revoke, and create a new one. Update the CLARITY_API_TOKEN env var in your AI client config and restart.

Minimum required scopes

| Task | Required scopes | |------|----------------| | Read projects, folders, test cases, runs | read | | Create / update test cases, suites, runs | read + write | | Delete test cases / folders / suites | read + write + delete | | Admin operations | admin |


Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | CLARITY_API_URL | Yes | — | API base URL, e.g. https://clarity-api.id3.com.tr | | CLARITY_API_TOKEN | Yes | — | Token in clr_<32 alphanumeric> format | | CLARITY_LANG | No | en | tr or en — switches tool description language shown to the AI | | CLARITY_MCP_DOMAINS | No | (core only) | Comma-separated capability domains to advertise, e.g. requirements,runs; all for everything. Write tools are off until their domain is listed. See Write tools are off by default |


Available Tools (164)

Generated from src/tools/index.ts (v1.11.2). Scopes follow the pattern: read tools need read, mutating tools need write, destructive tools need delete.

Projects (5)

| Tool | Description | Required scope | |---|---|---| | list_projects | Lists CLARITY projects accessible to your token | read | | get_project | Returns details of a specific project | read | | get_project_stats | Project statistics (case count, last 30 days success rate) | read | | create_project | Creates a new project | write | | update_project | Updates project info | write |

Folders (4)

| Tool | Description | Required scope | |---|---|---| | list_folders | Lists folders in a project (flat) | read | | get_folder_tree | Returns folder hierarchy as a tree | read | | create_folder | Creates a folder; use parentId for nested | write | | update_folder | Updates folder name/parent | write |

Test Cases (7)

| Tool | Description | Required scope | |---|---|---| | list_test_cases | Lists test cases (paginated) with folderId/type/priority/status/tag/search filters | read | | get_test_case | Returns test case detail (steps + metadata + relations) | read | | search_test_cases | Full-text search by title in test cases | read | | create_test_case | Creates a test case; non-MANUAL/AUTOMATED types auto-coerce to MANUAL + testTypes | write | | update_test_case | Updates test case fields | write | | bulk_create_test_cases | Bulk create test cases (max 50); for more use import_test_cases_json | write | | import_test_cases_json | Bulk import via CLARITY JSON schema; folderPath found or created, duplicateStrategy | write |

Suites (4)

| Tool | Description | Required scope | |---|---|---| | list_suites | Lists test suites | read | | get_suite | Returns suite detail with included cases | read | | create_suite | Creates a new test suite | write | | update_suite | Updates a suite; addCaseIds/removeCaseIds for case management | write |

Runs (5)

| Tool | Description | Required scope | |---|---|---| | list_runs | Lists test runs; supports status filter | read | | get_run | Returns run metadata only — not execution results (use get_run_progress for counts, get_failing_cases with runId for names) | read | | get_run_progress | Run progress statistics (pass/fail/skip/blocked/pending counts) | read | | create_run | Creates a test run; either testSuiteId OR testCaseIds[] required | write | | update_execution_result | Updates execution result for a case within a run (PASS/FAIL/SKIP/BLOCKED) | write |

Requirements (12)

| Tool | Description | Required scope | |---|---|---| | list_requirements | Lists requirements with type/status/priority/assignee/source/syncStatus/testable/search filters | read | | get_requirement | Returns full requirement detail incl. attachments and Jira/Azure sync status; for a Jira-linked requirement also its live Jira issue links (jiraLinks, null + reason if Jira is unreachable) | read | | create_requirement | Creates a requirement; accepts legacy type/status keys or typeId/statusId UUIDs | write | | update_requirement | Updates requirement fields; linked items auto-flip syncStatus to pending | write | | link_requirement_to_test_case | Links a requirement to up to 100 test cases per call (idempotent) | write | | link_requirement_to_test_runs | Links a requirement to up to 100 existing test runs of its project per call (idempotent) | write | | link_test_run_to_covered_requirements | Links a run to every requirement in its project whose covering test cases it executed (idempotent) | write | | unlink_requirement_from_test_case | Removes a requirement ↔ test case link (idempotent no-op if absent) | write | | unlink_requirement_from_test_runs | Removes up to 100 requirement ↔ test run links per call; reports removed / notLinked (idempotent) | write | | get_requirement_traceability | Requirement → test case → last execution traceability matrix with coverage % | read | | list_requirement_types | Lists requirement types (system defaults + project overrides) | read | | list_requirement_statuses | Lists requirement statuses (system defaults + project overrides) | read |

Jira Sync (7)

| Tool | Description | Required scope | |---|---|---| | push_requirement_to_jira | Pushes a manually-created requirement to Jira as a new issue | write | | link_requirement_to_jira | Links a requirement to an existing Jira issue (fields overwritten from Jira) | write | | sync_requirement | One-way pull-sync from Jira/Azure DevOps to local; reports conflicts | write | | push_requirement_update_to_jira | Pushes CLARITY changes up to the linked Jira issue (last-write-wins + conflict detection) | write | | list_requirement_link_types | Jira issue link types of the project's Jira with their outward / inward phrases (CLAR-314) | read | | link_requirements | Creates Jira issue links between requirements' issues (or to a raw key in the bound Jira project); single pair or up to 25 under one confirmation; all pairs validated before any write; existing links answered already_exists; verified by reading Jira back | write | | unlink_requirements | Deletes one Jira issue link from a requirement's issue; always its own confirmation | write |

Releases (21)

| Tool | Description | Required scope | |---|---|---| | list_releases | Lists releases; auto-computed coveragePercent / overallPassRate / readinessScore | read | | get_release | Release detail — merged test runs (direct + inherited via requirements) | read | | create_release | Creates a release; optional Jira fixVersion/sprint scope binding | write | | update_release | Partial update; status="released" auto-sets actualDate | write | | add_requirement_to_release | Links a requirement to a release; related runs auto-inherited | write | | remove_requirement_from_release | Unlinks a requirement from a release (idempotent) | write | | bulk_remove_requirements_from_release | Bulk-unlink up to 500 requirements from a release | write | | add_test_run_to_release | Directly attaches a test run with a runType classification | write | | remove_test_run_from_release | Detaches a directly attached test run; an inherited-only run is reported with its requirement(s) and a pointer to unlink_requirement_from_test_runs (idempotent) | write | | get_release_readiness | Readiness score (40% pass rate + 25% coverage + 20% execution progress + 15% gates), gates and blockers; muted failures are discounted but cap the release below READY | read | | get_release_platform_readiness | Readiness per platform (Web, iOS, Android, Smart TV, Set-Top Box, Apple TV …): runs, executed/total, pass rate, failed/blocked, requirement coverage, last run and status per platform, plus the verdict over the release's required platforms (CLAR-368) | read | | apply_release_exit_criteria_template | Seeds exit criteria from the template of the release's own type; additive (existing keys skipped) | write | | add_release_exit_criterion | Adds one derived (metric/operator/threshold) or manual exit criterion | write | | answer_release_exit_criterion | Answers a manual criterion met / not_met; null withdraws the answer | write | | add_release_gate | Adds an auto (with condition) or manual quality gate; the token owner is the requester | write | | evaluate_release_gates | Re-evaluates auto gates against current metrics; needs release:execute | write | | approve_release_gate | Approves a manual gate; self-approval needs a reason (four-eyes); needs release:execute | write | | record_release_sign_off | Records go / conditional_go / no_go, append-only, evidence sealed; needs release:execute | write | | list_release_sign_offs | Every recorded go/no-go, newest first, with seal and scope-drift status | read | | record_decision | Writes to the project's decision log (rationale required, append-only) | write | | generate_release_notes | Markdown release-notes draft; save: true stores it on the release | write | | create_release_scope_baseline | Freezes the release's current requirement scope as a baseline (drift is measured against it) | write |

Defects (8)

| Tool | Description | Required scope | |---|---|---| | list_defects | Lists defects, filterable by release, status, severity and openOnly | read | | get_defect | One defect with its links, full status history and allowedTransitions | read | | get_defect_retest_queue | Claimed fixes nobody has re-tested (verificationState=awaiting) | read | | get_defect_kpis | Open / escaped / awaiting-retest / unclassified counts, each with its own state | read | | create_defect | Reports a defect (always born new); detectedPhase required | write | | transition_defect | Moves a defect through the state machine — the only door to status. On a CLARITY defect linked to Jira (status push on) it also transitions the Jira issue, and prompts for confirmation first (CLAR-391) | write | | record_defect_verification | Writes a retest result; needs defect:execute | write | | set_defect_commitment | Release-commitment decision: targeted (needs a release), under_review, not_planned (needs a reason) | write | | push_defect_to_jira | Creates the Jira issue (Bug by default) for a CLARITY defect, links it and attaches execution evidence; status, priority and comments then sync both ways. Prompts for confirmation (CLAR-366) | write |

Three things an agent must not get wrong here. openOnly is not "not closed" — an unclassified (unmapped) defect is neither, and get_defect_kpis is where you find out how many there are. A KPI with state: "unknown" is NOT zero: it means the measurement did not happen, and reporting it as "0 open defects" turns "hold this release" into "ship it". And record_defect_verification does not close anything — it writes the evidence that MAKES resolved → closed legal for a fixed resolution; the close is a separate transition_defect call.

Users (2)

| Tool | Description | Required scope | |---|---|---| | list_users | Lists users assigned to a project (id, email, name, role) | read | | get_user | Returns user details — role, department, last login, membership count | read |

Tags (1)

| Tool | Description | Required scope | |---|---|---| | list_tags | Lists all unique tags used in a project's test cases, alphabetically | read |

Custom Fields (1)

| Tool | Description | Required scope | |---|---|---| | list_custom_fields | Lists tenant-scoped custom field definitions | read |

Webhooks (1)

| Tool | Description | Required scope | |---|---|---| | list_webhooks | Lists webhooks scoped to the project or tenant-wide | read |

Pipelines (1)

| Tool | Description | Required scope | |---|---|---| | list_pipelines | Lists CI/CD pipelines with their most recent run status | read |

Dashboard (1)

| Tool | Description | Required scope | |---|---|---| | get_dashboard_metrics | Analytics digest (cases, runs, pass rate, recent failures, flaky, avg execution time) | read |

Attachments (1)

| Tool | Description | Required scope | |---|---|---| | add_test_case_attachment | Attaches external evidence to a test case via URL (no file upload) | write |

Comments (1)

| Tool | Description | Required scope | |---|---|---| | add_test_case_comment | Adds a markdown comment; mentions[] triggers @-mention notifications | write |

Scheduled Runs (3)

| Tool | Description | Required scope | |---|---|---| | list_scheduled_runs | Lists scheduled test runs; status filter (active/paused/completed/failed) | read | | create_scheduled_run | Creates a scheduled run for a suite (cron or interval schedule) | write | | pause_scheduled_run | Pauses an active scheduled run (status=paused) | write |

Reports & Insights (2)

| Tool | Description | Required scope | |---|---|---| | get_failing_cases | Top failing test cases in the last N days; with runId, that run's failed/blocked executions with an explicit truncated flag | read | | get_test_type_info | Test type enum values and descriptions (MANUAL/API/AUTOMATED etc.) | read |

AI generation, root cause, risk and triage (5) — since 1.22.0

What CLARITY's own AI and ML do, for an agent. The two generation tools and the root-cause tool send text to the organization's AI provider and spend its AI quota, so both of their modes ask for confirmation (C2). Ranking and triage are reads.

| Tool | Description | Required scope | |---|---|---| | generate_tests_from_requirement | Proposes test cases for a requirement (requirementId, or requirementText ≤ 20,000 chars). With accept (≤ 12 proposals, named one by one) saves them, linked to the requirement. Without accept nothing is written. Domain testcases | write | | generate_tests_from_document | Same, from a document: source: {text ≤ 60,000, title?} or {url, kind: openapi \| documentation} (read server-side, public addresses only). Only the first 4000 characters reach the model — basis.truncated says when it was cut. Domain testcases | write | | analyze_failure_root_cause | AI root cause of one failed execution (executionId; the test case is derived from it). generatedBy is ai, or the keyword stand-in with fallbackReason. Domain runs | write | | rank_tests_by_failure_risk | Ranks testCaseIds / a suiteId / a runId by chance to fail on the next run. source: ml_model (project model passed its gate) or heuristic; modelAvailable: false with an empty list when the prediction service is down — never zeros. Domain insights | read | | get_run_triage | A finished run's automatic triage: summary, per failure category, source (rule / ai / rules_fallback), status, linked defect. summary: null = not triaged yet. Domain runs | read |

Suggest → accept: call once without accept, confirm, read suggestions, then call again with accept: [the ones to keep] and confirm. Suggestions derived from a Jira/Azure requirement, a fetched document or a failure's output come back inside <untrusted> blocks; after reading those, a session's outward writes (these C2 tools included) go through clarity_propose, where a person approves them in CLARITY.

get_impacted_tests also takes rankBy: "risk" (default "evidence") to list the impacted cases most likely to fail first; the order is applied before paging.

Discovery agent (3) — since 1.23.0

The discovery agent explores a project's configured environment read-only and proposes defect candidates (rule-based, accessibility, AI) and untested screens. An agent can start one and read the results; accepting or dismissing a finding stays a human decision in the CLARITY UI.

| Tool | Description | Required scope | |---|---|---| | list_discovery_findings | Findings of a project (open by default), filterable by status, kind, category, runId. Page-derived text comes back inside <untrusted> blocks | read | | get_discovery_run | One discovery (latest when runId is omitted): status, progress against the caps, stop reason, counters, the exploratory test run it was recorded as | read | | start_discovery_run | Queues a discovery of the configured environment; needs pipeline:execute, refused when off on the server or project, while another runs, or after 5 in 24 hours | write |

Meta (2)

| Tool | Description | Required scope | |---|---|---| | get_my_quota | Shows your token's scopes, accessible projects, and rate limits | read | | get_schema | Returns list of all tools or schema of a specific tool | read |

Code Changes & the Change Gate (7)

Reading what was actually built, and whether it is safe to merge.

| Tool | Description | Required scope | |---|---|---| | list_code_changes | Commits and pull requests ingested for a project. statsMeasured: false = file/line counts unknown (null), not zero; includeFiles adds the changed paths (first 50) | read | | get_code_change | One change with its risk factors and linked tests | read | | get_code_change_files | The files a change touched | read | | get_code_change_diff | The unified diff, read live from the provider | read | | get_code_change_review | Approval state and reviewers, normalised across providers | read | | get_change_gate | The merge verdict and the evidence behind it | read | | attach_scan | Attaches a SARIF security scan and classifies it against the baseline | write |

Change impact & code areas (6)

"These changes landed — what do I re-test, and where are tests missing?" get_change_impact and get_impacted_tests are in the always-visible core; the four area tools are in delivery.

| Tool | Description | Required scope | |---|---|---| | get_change_impact | For 1–50 changes (codeChangeIds) or a since/until/branch window of a project: code areas touched (with files), existing test cases to re-test (why: file / requirement / area, 0–100 confidence), areasWithoutTests, unmatchedFiles, changesWithoutStats, a ready suggestedRun and nextSteps. Measures up to 20 unmeasured changes first | read | | get_impacted_tests | The same for one change (codeChangeId), per-channel availability in byFile / byRequirement / byArea | read | | list_code_areas | The project's code areas: path globs → test-case folders and tags, with testCaseCount and recentChangeCount | read | | suggest_code_areas | Proposes areas from where recent changes cluster, with name-similar folders/tags. Saves nothing | read | | upsert_code_area | Creates an area (name + pathPatterns) or updates one by areaId | write | | delete_code_area | Soft-deletes an area (2-step confirmation); tests, folders and tags are untouched | write |

Recommended workflow:

  1. get_change_impact { projectId, since: "<last release date>", branch: "develop" } (or pass codeChangeIds).
  2. Re-test the listed cases — suggestedRun already holds create_run's arguments (runs domain). Highest confidence first.
  3. For areasWithoutTests, call generate_tests_for_change (asks for confirmation; spends AI quota) and accept the useful proposals.
  4. If unmatchedFiles is large, or byArea.reason is NO_CODE_AREAS, call suggest_code_areas, review with the user, and save with upsert_code_area. The next impact call maps those files to areas.

changesWithoutStats lists changes whose file list is still unknown — their impact is unknown, not empty. tests.state: "unknown" likewise never means "nothing is impacted".

SCM (4)

Live reads against GitHub, Bitbucket, Azure DevOps and GitLab.

| Tool | Description | Required scope | |---|---|---| | list_branches | Branches across a project's repositories | read | | list_pull_requests | Pull requests, optionally filtered by state | read | | get_ingest_status | Why changes are — or are not — arriving on their own | read | | run_backfill | Imports the history that predates the webhook (safe to re-run) | write |

These tools distinguish "could not look" from "nothing found." Every one of them reads a third-party system over a credential that can expire or lose a scope, so failures are reported next to the data rather than instead of it: failedRepositories, skipped[].reason, available: false. An empty list from a repository CLARITY could not read is not evidence that nothing is happening — and an agent that reports it as such has been misled by a 401.

Scan Orchestration (4)

| Tool | Description | Required scope | |---|---|---| | list_scan_profiles | The scan profiles a project can run | read | | request_scan | Create a scan job and try to run it | write | | list_scan_jobs | Scan jobs and what became of them | read | | get_scan_debt | Outstanding findings from earlier scans, and what has been paid down | read |

blockedReason is the field that matters on request_scan. A job with no CI connection and no runner is queued, not running. An agent that reports it as "scan started" has told its user something untrue that nothing will correct later. Likewise queued, failed and expired on list_scan_jobs all mean no result arrived — and get_scan_debt reports neverScanned rather than zero, because zero debt and a clean project look identical and are opposites.

Delete (5)

| Tool | Description | Required scope | |---|---|---| | delete_test_case | Soft-deletes a test case (restorable for 30 days), 2-step confirmation | delete | | delete_folder | Soft-deletes a folder + cases inside, 2-step confirmation | delete | | delete_suite | Deletes a suite (cases remain), 2-step confirmation | delete | | delete_requirement | Soft-deletes a requirement (test case links removed), 2-step confirmation | delete | | delete_release | Soft-deletes a release (linked runs/requirements intact), 2-step confirmation | delete |

Delete tools (delete_test_case, delete_folder, delete_suite, delete_requirement, delete_release) require a 2-step confirmation flow: the first call returns requiresConfirmation: true with a confirmationToken and a preview of what will be deleted; the second call passes the token to confirm. The confirmation window expires after 60 seconds.


Examples

Here are prompts you can paste directly into your AI client. The AI picks the correct tool(s) automatically.

1. List your projects

Show me my CLARITY projects.

Calls list_projects.

2. Generate test cases from a requirement

Read this requirement and create 10 test cases in the "Auth/Login" folder of project "E-commerce":
> Users must log in with email and password. Rate-limited to 5 attempts per minute.
> Lockout after 10 failed attempts. Password minimum 8 characters.

Calls import_test_cases_json with duplicateStrategy: "skip" (the folder path in the JSON is found or created).

3. Find failing tests

Which test cases failed most often this month in project "E-commerce"?

Calls get_failing_cases({ projectId, days: 30, limit: 10 }).

4. Check run progress

How is the "Sprint-42 Smoke" run going?

Calls list_runs to resolve the run ID, then get_run_progress.

5. Mark an execution as failed

Mark the case "User can checkout with VISA" in the "Sprint-42 Smoke" run as FAIL
with comment: "payment-service returned 502 — see incident #4521"

Calls search_test_cases + list_runs to resolve IDs, then update_execution_result.

6. Bulk-create test cases

Create 5 test cases for the password-reset flow in the "Auth" folder of project "E-commerce".
Cover: request email, invalid email, expired link, successful reset, and password reuse rule.

Calls bulk_create_test_cases with up to 50 cases in a single request.

7. Safe folder deletion

Delete the "legacy-api" folder from project "E-commerce".

First call returns a preview and a confirmationToken. The AI shows you the preview and asks for confirmation before proceeding with the second call.


Troubleshooting

"Connected to clarity (0 tools)" or no tools listed

  • Check CLARITY_API_URL — must include the scheme and no trailing slash (e.g. https://clarity-api.id3.com.tr)
  • Verify CLARITY_API_TOKEN starts with clr_
  • Restart the AI client after editing the config file

A new version was published but the old one keeps running

npx runs a command of that name already on PATH before it consults the registry, so a global install silently pins you to an old version with no error:

which clarity-mcp-server            # a path means a global install exists
npm ls -g --depth=0 | grep clarity  # shows which version
npm uninstall -g @id3-clarity/mcp-server

npm view @id3-clarity/mcp-server version is the authority on what is current; the npmjs.com package page is cached and can lag behind a publish.

create_requirement (or another write tool) cannot be called

Its domain is off — write tools are not advertised by default. Add the domain to the config, comma-separated with any others, and restart the client (or open a new chat):

"CLARITY_MCP_DOMAINS": "requirements,runs"

In the SAME chat the model can call enable_domain({ domain }); clients that honour notifications/tools/list_changed (e.g. Claude Code) then show the domain's tools, and a write tool is called directly. Clients that ignore the notification (observed in Claude Desktop) need the setting above and a restart for write tools: call_tool({ name, arguments }) carries read-only tools only and refuses one that changes data (CALL_TOOL_READ_ONLY), because through it the client could not show the user which change is about to happen or ask first. If a write tool answers INSUFFICIENT_SCOPE, the token lacks the write scope.

INVALID_TOKEN

The token has been revoked or never existed. Create a new one at CLARITY → Settings → API Access → MCP Tokens → New Token.

INSUFFICIENT_SCOPE

The token lacks the scope the tool needs. Edit the token at Settings → API Access → MCP Tokens and enable the required scope (read, write, or delete).

PROJECT_NOT_ACCESSIBLE

The token is scoped to specific projects and the requested project is not in its allowlist. Either expand the token's project access or use a different token.

RATE_LIMIT_EXCEEDED

CLARITY enforces 60 requests/minute per token by default. Wait a few seconds and retry. For bulk operations, use bulk_create_test_cases instead of looping over create_test_case.

CONFIRMATION_EXPIRED

The 60-second confirmation window for a destructive operation expired. Retry the delete call to receive a fresh confirmationToken.

TENANT_CONTEXT_MISSING

The API token has no tenant association. This usually means the token was created before a tenant was configured. Create a new token after verifying your CLARITY workspace is fully set up.

The server starts but the AI can't find a project

Use list_projects first to confirm the project ID. Project names are case-sensitive in search filters; use projectId (UUID) in tool calls for reliability.


Privacy & Security

Tenant isolation

Every API call is executed under the tenant associated with your token. The server cannot access data from other tenants, even if you supply a cross-tenant ID. This isolation is enforced at the CLARITY backend, not only in the MCP layer.

Audit logging

Every tool call — including the initiating token ID, source IP, tool name, parameters, and result — is written to CLARITY's immutable audit log. Administrators can review this log at Settings → Audit Log.

Least-privilege tokens

Grant only the scopes your workflow actually needs:

  • Read-only monitoring / dashboards → read scope only
  • Content creation (AI-generated tests) → read + write
  • Cleanup / migrations → read + write + delete

IP allowlist

For production tokens, navigate to Settings → API Access → MCP Tokens → [token] → IP Allowlist and restrict the token to specific CIDR ranges.

Token soft-lock

If a token triggers more than 5 destructive operations within 60 seconds, it is automatically soft-locked for 1 hour as a safety net against runaway automation. An administrator can unlock it at Settings → API Access → MCP Tokens.

Treat tokens like passwords

  • Never paste a token into a chat, issue, or screenshot
  • Never commit tokens to source control
  • Rotate tokens whenever a team member leaves or a device is compromised
  • Use short-lived tokens (set an expiry) for CI pipelines

Key rotation procedure

  1. Create a new token at Settings → API Access → MCP Tokens → New Token
  2. Update CLARITY_API_TOKEN in your AI client config
  3. Restart the AI client
  4. Revoke the old token at Settings → API Access → MCP Tokens → [old token] → Revoke

Development

git clone <repo>
cd packages/clarity-mcp-server
npm install
npm run build

Local linking (test before publish)

npm link
# In your AI client config replace:
#   "command": "npx", "args": ["-y", "@id3-clarity/mcp-server@latest"]
# with:
#   "command": "clarity-mcp-server"

Manual smoke test

CLARITY_API_URL=https://clarity-api.id3.com.tr \
CLARITY_API_TOKEN=clr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
CLARITY_LANG=en \
node dist/index.js
# Expect on stderr: "@id3-clarity/mcp-server ready (lang=en)"

Running unit tests

npm test

The script collects files with find and passes them to node --test individually. Two shorter forms do not work and both fail in ways that look like something else:

  • node --test "dist-test/**/*.test.js" — the glob is quoted, so the shell does not expand it and Node has to. Node only learned to expand globs for --test in v21, and this package declares engines: >=18. On Node 18 or 20 it prints Could not find '.../dist-test/**/*.test.js' — which reads like a missing build, not an unsupported flag. It passed locally on v22 and failed in CI.
  • node --test dist-test/ — Node treats the directory as one unit and executes its entry point, so the MCP server starts and dies with Fatal: CLARITY_API_URL env var required. That looks like a missing environment variable in the test harness, and it is not.

The [ -n "$F" ] guard is not decoration: with no files, node --test falls back to searching the working directory and hits the second failure above.


License

MIT — see LICENSE.