npm.io
1.9.1 • Published 2h agoCLI

@id3-clarity/mcp-server

Licence
MIT
Version
1.9.1
Deps
2
Size
141 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

@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 86 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 should show "clarity (69 tools)" or similar.

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: outdated clients get an upgradeNotice on every response, and unsupported versions are refused with a clear "please update" message. So if the AI mentions an available update, run the command above.

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

Available Tools (69)

Generated from src/tools/index.ts (v1.5.0). 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 with folderStrategy / 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 detail with execution results 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 (9)
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 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
unlink_requirement_from_test_case Removes a requirement test case link (idempotent no-op if absent) 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 (4)
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
Releases (9)
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
get_release_readiness Readiness score (60% pass rate + 40% coverage), gates and blockers read
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 read
get_test_type_info Test type enum values and descriptions (MANUAL/API/AUTOMATED etc.) read
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
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 folderStrategy: "find-or-create" and duplicateStrategy: "skip".

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
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

License

MIT — see LICENSE.

Keywords

mcpmodel-context-protocolclaritytest-managementclaudecursorclineai-tools