@id3-clarity/mcp-server 1.5.0

package/EXAMPLES.md

@@ -0,0 +1,64 @@
+# Examples
+
+Sample prompts you can give to Claude Desktop / Cursor / Cline / Windsurf once `@id3-clarity/mcp-server` is connected. The AI picks the right tool — you don't have to call them by name.
+
+## 1. List your projects
+
+**Prompt:** "Show me my CLARITY projects."
+
+The AI calls `list_projects` and returns project names + IDs you can reference in later prompts.
+
+## 2. Generate test cases from a requirement
+
+**Prompt:** "Read this requirement and create 10 test cases in the `Auth/Backend` folder of project `E-commerce`:
+> *As a user, I want to log in with email and password so I can access my account. Validation: rate-limited at 5 attempts/min, password must be 8+ chars, lockout after 10 failed attempts.*"
+
+The AI drafts JSON internally (canonical CLARITY schema or the `suggestions[]` alias), then calls `import_test_cases_json` with `folderStrategy: "find-or-create"` and `duplicateStrategy: "skip"`.
+
+## 3. View failing tests
+
+**Prompt:** "Which test cases failed most often this month in project `E-commerce`?"
+
+The AI calls `get_failing_cases({ projectId, days: 30, limit: 10 })` and lists the top offenders.
+
+## 4. Check run progress
+
+**Prompt:** "How is the `Sprint-42 Smoke` run going?"
+
+The AI calls `list_runs` to find the run id, then `get_run_progress({ runId })` and reports pass/fail/skip/blocked counts.
+
+## 5. Mark an execution as failed
+
+**Prompt:** "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`."
+
+The AI resolves IDs via `search_test_cases` + `list_runs`, then calls `update_execution_result({ projectId, runId, caseId, status: "FAIL", comment: "..." })`.
+
+## 6. Delete a folder safely
+
+**Prompt:** "Delete the `legacy-api` folder from project `E-commerce`."
+
+The AI calls `delete_folder({ projectId, folderId })`. The first call returns `requiresConfirmation: true` plus a `confirmationToken` and a preview of what will be deleted. The AI shows you the preview, asks "are you sure?", and only then issues the second call with `confirmationToken` to actually perform the soft-delete.
+
+## 7. Search by title
+
+**Prompt:** "Find all test cases that mention `2FA` in project `E-commerce`."
+
+The AI calls `search_test_cases({ projectId, query: "2FA" })` and returns the matches.
+
+## 8. Update test case priority
+
+**Prompt:** "Bump priority of every test case tagged `payment` to `CRITICAL` in project `E-commerce`."
+
+The AI calls `list_test_cases({ projectId, tag: "payment" })`, then iterates with `update_test_case({ caseId, priority: "CRITICAL" })` for each result.
+
+## 9. Inspect your token
+
+**Prompt:** "What scopes does my CLARITY token have?"
+
+The AI calls `get_my_quota` and shows scopes, accessible projects, and current rate limit usage.
+
+## 10. Discover tool schemas
+
+**Prompt:** "What parameters does `import_test_cases_json` take?"
+
+The AI calls `get_schema({ toolName: "import_test_cases_json" })` and explains the fields, defaults, and enums.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CLARITY Test Management
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,538 @@
+# @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](https://img.shields.io/npm/v/@id3-clarity/mcp-server)](https://www.npmjs.com/package/@id3-clarity/mcp-server)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+---
+
+## Overview
+
+`@id3-clarity/mcp-server` (v1.5.0) exposes **68 tools** from the CLARITY REST API as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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):
+```json
+{
+  "mcpServers": {
+    "clarity": {
+      "command": "npx",
+      "args": ["-y", "@id3-clarity/mcp-server"],
+      "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):
+```json
+{
+  "mcpServers": {
+    "clarity": {
+      "command": "npx",
+      "args": ["-y", "@id3-clarity/mcp-server"],
+      "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.
+
+```json
+{
+  "mcpServers": {
+    "clarity": {
+      "command": "npx",
+      "args": ["-y", "@id3-clarity/mcp-server"],
+      "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 (68 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.
+
+---
+
+## 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:
+
+```bash
+npm install -g @id3-clarity/mcp-server
+```
+
+Then replace `"command": "npx", "args": ["-y", "@id3-clarity/mcp-server"]` 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 (68)
+
+> 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
+
+```bash
+git clone <repo>
+cd packages/clarity-mcp-server
+npm install
+npm run build
+```
+
+### Local linking (test before publish)
+
+```bash
+npm link
+# In your AI client config replace:
+#   "command": "npx", "args": ["-y", "@id3-clarity/mcp-server"]
+# with:
+#   "command": "clarity-mcp-server"
+```
+
+### Manual smoke test
+
+```bash
+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
+
+```bash
+npm test
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/client/clarity-api-client.d.ts

@@ -0,0 +1,19 @@
+import { ServerConfig } from '../config';
+export interface ToolResult {
+    success: boolean;
+    data?: unknown;
+    requiresConfirmation?: boolean;
+    confirmationToken?: string;
+    preview?: unknown;
+    replayedFromCache?: boolean;
+    meta?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export declare class ClarityApiClient {
+    private readonly http;
+    constructor(config: ServerConfig);
+    invokeTool(toolName: string, params: Record<string, unknown>): Promise<ToolResult>;
+}

package/dist/client/clarity-api-client.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClarityApiClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+class ClarityApiClient {
+    http;
+    constructor(config) {
+        this.http = axios_1.default.create({
+            baseURL: config.apiUrl,
+            timeout: 30000,
+            headers: {
+                Authorization: `Bearer ${config.apiToken}`,
+                'Accept-Language': config.lang,
+                'User-Agent': '@id3-clarity/mcp-server/1.5.0',
+            },
+            validateStatus: (s) => s < 500,
+        });
+    }
+    async invokeTool(toolName, params) {
+        try {
+            const res = await this.http.post(`/api/mcp/tools/${toolName}`, params);
+            return res.data;
+        }
+        catch (err) {
+            const e = err;
+            throw new Error(`MCP API error: ${e.message ?? 'unknown'}`);
+        }
+    }
+}
+exports.ClarityApiClient = ClarityApiClient;
+//# sourceMappingURL=clarity-api-client.js.map

package/dist/client/clarity-api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarity-api-client.js","sourceRoot":"","sources":["../../src/client/clarity-api-client.ts"],"names":[],"mappings":";;;;;;AAAA,kDAA6C;AAc7C,MAAa,gBAAgB;IACV,IAAI,CAAgB;IAErC,YAAY,MAAoB;QAC9B,IAAI,CAAC,IAAI,GAAG,eAAK,CAAC,MAAM,CAAC;YACvB,OAAO,EAAE,MAAM,CAAC,MAAM;YACtB,OAAO,EAAE,KAAK;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,MAAM,CAAC,QAAQ,EAAE;gBAC1C,iBAAiB,EAAE,MAAM,CAAC,IAAI;gBAC9B,YAAY,EAAE,+BAA+B;aAC9C;YACD,cAAc,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,GAAG;SAC/B,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,QAAgB,EAAE,MAA+B;QAChE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC;YACvE,OAAO,GAAG,CAAC,IAAkB,CAAC;QAChC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,GAA2B,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;CACF;AAzBD,4CAyBC"}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export interface ServerConfig {
+    apiUrl: string;
+    apiToken: string;
+    lang: 'tr' | 'en';
+}
+export declare function loadConfig(): ServerConfig;