@uluops/ops-mcp 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,383 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-06-05
+
+First post-ship hardening pass. Driven by the run #1 ship pipeline (which
+failed Stage 3 public-interface at 56/100) and the run #2 anxiety reading
+(which surfaced two silent runtime failures the static gates missed:
+`tool-policies.json` never loaded by `npx` consumers, and `ULUOPS_API_KEY`
+format documented but unvalidated). All 7 ship gates now pass; 34 of the 39
+tracker findings closed (87%).
+
+### Security
+
+- **`tool-policies.json` now actually loaded.** The bundled policy file ships
+  in `files[]` but mcp-secure-server's resolution order (env var, then
+  `./tool-policies.json` in CWD, then `~/.config`) never found it for
+  `npx -y @uluops/ops-mcp` invocations — CWD is the MCP host's project
+  directory, not the package directory. Resolved via
+  `require.resolve('../tool-policies.json')` passed as `toolPoliciesPath`.
+  Without this fix every public consumer ran with default-level enforcement
+  and the `relaxedFields` that suppress UUID-as-credit-card false positives
+  were decorative.
+- **`ULUOPS_API_KEY` format validated at startup.** README documented the
+  `ulr_` prefix + 20-char minimum but `validateConfig` only checked for
+  non-empty. Mis-prefixed keys silently routed through `sessionToken` auth
+  and surfaced as opaque 401s. Now enforced via
+  `/^ulr_[A-Za-z0-9_-]{16,}$/` with an actionable error message.
+- **`NotFoundError` and `NetworkError` now pass through `sanitizeErrorMessage`.**
+  Closed a credential-redaction gap where 2 of 7 typed error branches
+  forwarded raw SDK error messages — low probability of leaking `ulr_*`
+  keys today, but the redaction layer is now consistent across all branches.
+- **402 tier-gating payload uses defensive type guards.** Previously cast
+  `details.definitions`, `details.currentTier`, `details.upgradeUrl` without
+  shape validation. Now `Array.isArray` + `typeof === 'string'` guards
+  with graceful fallback to `'above-tier definitions'` / `'unknown'` when
+  the API payload shape drifts.
+- **HTTPS-only base URL warning.** `loadConfig` now warns when
+  `ULUOPS_BASE_URL` uses a non-`https:` scheme outside `NODE_ENV=development`.
+  Closes CWE-319 cleartext-credential-transmission visibility gap.
+- **`ENABLE_DETAILED_ERRORS=false` env gate** for tightened production
+  deployments that want mcp-secure-server to suppress redacted error
+  reasons in `error.message`.
+- **`Number.isFinite` coercion guard.** `coerceNumericFields` now rejects
+  `Infinity` / `-Infinity` / `NaN` from string-typed numeric inputs.
+- **Input size bounds.** `delete_project.confirmation_phrase` and
+  `search_issues.query` now have `.max()` constraints (200 / 500 chars).
+
+### Changed
+
+- **Server protocol identity is now `@uluops/ops-mcp`.** Three call sites
+  still said `uluops-tracker-client` from before the package rename
+  (`SecureMcpServer.create` name, internal config default, startup log).
+  MCP host UIs now display the correct identity and bug reports can be
+  correlated to the npm package name.
+- **Verbose file logging defaults to `false`.** `ENABLE_FILE_LOGGING`,
+  `VERBOSE_LOGGING`, and `LOG_PERFORMANCE_METRICS` previously defaulted
+  to `true`, which created a `logs/` directory in every consumer's working
+  directory without opt-in. All three now default `false`; opt in
+  explicitly via env vars.
+- **README rewritten for npm/npx consumers.** Installation section was
+  the contributor `npm install` + `npm run build` workflow; now leads
+  with `npx -y @uluops/ops-mcp` and `npm install -g @uluops/ops-mcp`.
+  `.mcp.json` example uses the correct binary name (`uluops-ops-mcp`,
+  not the stale `uluops-tracker-client`). Quick Start field names
+  corrected (`agents`/`decision`/`agent`, not the pre-rename
+  `validators`/`status`/`validator`).
+- **Documentation parity with 48 registered tools.** README previously
+  documented 47 (off-by-one from `soft_delete_issue` addition) and
+  4 stale tool names from the validator→agent rename (`list_validators`,
+  `validate_features_list`, `get_validator_reliability`,
+  `get_validator_matrix`). All corrected; 10 previously-undocumented
+  tools added (the full Analysis Tools group plus `get_agent_lifecycle`,
+  `soft_delete_issue`, and renames).
+- **Six previously-undocumented environment variables documented**:
+  `ULUOPS_ORG_SLUG`, `ULUOPS_TRACKER_RETRIES`, `ENABLE_FILE_LOGGING`,
+  `LOG_DIR`, `VERBOSE_LOGGING`, `LOG_PERFORMANCE_METRICS`.
+- **Graceful shutdown awaits server close.** `SIGINT`/`SIGTERM` handlers
+  now `await Promise.race([server.close(), 2s timeout])` before
+  `process.exit(0)` so in-flight tool responses can flush back through
+  stdio.
+
+### Added
+
+- **API key fingerprint in startup log.** `apiKeyFingerprint(apiKey)`
+  emits `ulr_…XXXX` (last 4 chars) so operators can distinguish which
+  key the server loaded across multiple deployments without leaking
+  the secret.
+- **7 tests covering the 402 tier-gating error path** (`sdk-error-mapper.test.ts`)
+  including happy path, `?source=mcp` vs `&source=mcp` upgrade-URL tracking,
+  missing-details fallback, malformed-definitions tolerance,
+  non-array/non-string defensive handling, and credential-not-leaked check.
+- **`coerceNumericFields` boundary tests** verifying MCP JSON-RPC string-typed
+  numerics are coerced and `Infinity`/`NaN` rejected.
+- **`save_run` timestamp injection tests** verifying ISO-8601 timestamp is
+  injected when the caller omits one and caller-supplied timestamps are
+  preserved verbatim.
+
+### Removed
+
+- **Dead `config.server` stanza.** `ServerConfig` interface, the
+  `server: { name, version: '1.0.0' }` block in `loadConfig`, and the
+  matching test assertion. The static `'1.0.0'` was a pinned falsehood
+  (package was at 0.2.0); the dynamic version path at `src/index.ts:22`
+  reads from `package.json` and remains.
+- **`ValidatorResultSchema` / `ValidatorResult` deprecated aliases**
+  removed from `src/types/schemas.ts`. All consumers migrated to
+  `AgentResultSchema` / `AgentResult`. Deprecation introduced post-rename
+  in 0.2.0; alias dropped now to reduce surface.
+
+### Internal
+
+- 10 ESLint errors fixed (3× `restrict-template-expressions`,
+  3× `no-deprecated`, 3× `no-unnecessary-type-assertion`,
+  1× `no-unnecessary-type-assertion`). Lint now exits clean.
+- Shared run-related schemas extracted to `src/types/run-schemas.ts`
+  (`CategoryScoreSchema`, `ExplorationSectionSchema`,
+  `ExplorationMapSchema`, `AnalysisRecordBaseSchema`,
+  `AnalysisSummaryBaseSchema`). `save-run.ts` shrank 173 → 76 lines;
+  `update-run.ts` shrank 167 → 80 lines.
+- `main()` body extracted into `buildServerOptions()` plus
+  `STARTUP_TOOL_GROUPS` / `STARTUP_RESOURCES` constants. Function body
+  shrank 197 → 88 lines.
+- `EXPECTED_TOOLS` unified to a single fixture
+  (`src/__tests__/fixtures/expected-tools.ts`) consumed by both
+  `tools-integration.test.ts` and `tool-registry.test.ts`.
+- `createToolHandler` `preProcess` discriminates on a `Symbol`
+  marker (`shortCircuit()`) instead of `'content' in result`
+  duck-typing. Future tool schemas with top-level `content` fields
+  no longer trigger an accidental error-response interpretation.
+- `isNumericSchema` uses Zod's public `unwrap()` /
+  `removeDefault()` API instead of accessing `_def.innerType`
+  via `as any`. Stable across Zod minor versions.
+- `list_agents` handler now guards SDK return shape with
+  `Array.isArray` + a type predicate filter. Previously cast
+  `data as Array<{ name: string }>` blind.
+- `assertion` guarding `toolPoliciesPath` argument added to
+  `index.test.ts` — the fix above would otherwise have no test
+  coverage protecting it from refactor regression.
+- Stale `tool-policies.json` CWD-fallback comment in `src/index.ts`
+  replaced with an accurate description of the bundled-file lookup.
+- LICENSE file added (MIT, matching sibling `@uluops/*` packages)
+  and `LICENSE` added to `files[]`.
+- CHANGELOG `[Unreleased]` compare base corrected from `v1.21.0`
+  (pre-rename) to `v0.2.0` and `[0.2.0]` tag link added in 0.2.0
+  release; this release adds `[0.2.1]` link.
+
+### Test count
+
+655 passing (up from 645 in 0.2.0). Net +10: +7 tier-gating, +2
+`coerceNumericFields` boundary, +2 `save_run` timestamp, +2 ulr_
+format validation, −5 retired (one `loadConfig` server-defaults
+test deleted with the dead stanza, removed assertions migrated).
+
+## [0.2.0] - 2026-06-05
+
+First release under the scoped name `@uluops/ops-mcp`. Forward-ports the
+operational drift from the legacy `uluops-ops-mcp-client` 1.22.0 codebase
+and aligns the package with the broader UluOps supply-chain policy.
+
+### Added
+
+- **`soft_delete_issue` tool** — write-side tool for soft-deleting issues
+  with standard 10KB/10KB size budgets and 60/min, 1000/hr rate limits.
+  Brings total tool count to 48.
+- **`add_issue_note` size relaxation** — `maxArgsSize` 50→80 KB and
+  `maxEgressBytes` 20→100 KB. The MySQL `TEXT` content column tolerates
+  64KB; the prior 20KB egress was too tight for stack-trace-heavy notes.
+
+### Changed
+
+- **`@uluops/ops-sdk` bumped `^2.0.0` → `3.1.0`** (two major versions).
+  All tool source compiles unchanged against the new SDK surface.
+- **All runtime and dev dependencies pinned to exact versions** — removed
+  caret ranges across the board per the 2026-06-01 UluOps supply-chain
+  hardening policy.
+
+### Historical lineage (legacy `uluops-ops-mcp-client` versions below)
+
+## [1.21.0] - 2026-05-21
+
+### Changed
+- Score field now optional/nullable across MCP schemas to support generator/executor agents
+
+## [1.20.0] - 2026-05-20
+
+### Changed
+- `save_run` and `update_run` pass `{ _skipClientValidation: true }` to SDK — eliminates redundant double validation
+
+### Fixed
+- `edit_issue` tool aligned with SDK rename (`issues.edit()` → `issues.update()`)
+- `ConflictError` details (`nextAvailable`, `status`) forwarded to MCP response
+- Tool count assertions updated from 45 → 47
+
+## [1.19.0] - 2026-05-18
+
+### Fixed
+- `ExplorationSection` schemas aligned with API discriminated union type
+
+## [1.18.0] - 2026-05-11
+
+### Added
+- `get_agent_runs_analysis` MCP tool for per-agent analysis history
+- `exploration_maps` on `save_run` and `update_run` tool schemas
+- Per-agent analysis summary array on `save_run`
+
+## [1.17.0] - 2026-05-10
+
+### Added
+- Per-agent analysis attribution on `update_run` tool
+- `analysis_records` and `analysis_summary` exposed on `update_run` tool
+
+## [1.16.0] - 2026-05-06
+
+### Added
+- `high` priority level added to MCP schemas
+
+### Changed
+- Legacy `ULUOPS_TRACKER_API_KEY`/`ULUOPS_TRACKER_URL` env var support removed
+
+## [1.15.0] - 2026-05-03
+
+### Added
+- `get_agent_lifecycle` tool with `definition_version` on agent snapshots
+
+### Fixed
+- `save_features_list` references replaced with `save_run` in docs
+
+## [1.14.0] - 2026-05-01
+
+### Fixed
+- `classified_by` enum value renamed from `validator` to `agent` in MCP schema
+
+## [1.13.0] - 2026-04-28
+
+### Added
+- 402 `SubscriptionRequired` error handling with `source=mcp` tracking
+
+## [1.12.0] - 2026-04-19
+
+### Added
+- `definition_id` field on `save_run` MCP tool input schema
+
+## [1.11.0] - 2026-04-16
+
+### Added
+- `summary` field on `AgentResultSchema`
+
+### Fixed
+- `mcp-secure-server` upgraded to 0.0.13-security (UUID false-positive fix)
+
+## [1.10.0] - 2026-04-15
+
+### Added
+- Detailed error diagnostics from `mcp-secure-server`
+
+## [1.9.0] - 2026-04-12
+
+### Added
+- Session token authentication as alternative to API keys
+
+## [1.8.0] - 2026-04-10
+
+### Added
+- `observation` as first-class issue status
+
+### Changed
+- Divergent taxonomy resource replaced with SDK-fetched data
+
+## [1.7.0] - 2026-04-04
+
+### Added
+- Structured error context with tool name, type, and suggestions
+- `recommendations` field on `update_run` tool
+
+## [1.6.0] - 2026-03-29
+
+### Added
+- Org context support via `ULUOPS_ORG_SLUG` env var
+
+### Fixed
+- Error handling overhauled for actionable agent-facing messages
+- Analysis record type enum enforced at MCP layer on `save_run`
+
+## [1.5.0] - 2026-03-14
+
+### Added
+- Analysis query tools: `get_run_analysis`, `get_project_analysis`, `query_analysis_records`
+- `analysis_records` and `analysis_summary` fields on `save_run`
+
+### Fixed
+- `get_project_analysis` uses project name instead of UUID
+
+## [1.4.0] - 2026-03-08
+
+### Changed
+- `save_features_list` renamed to `save_run`
+- `validator` renamed to `agent` across Zod schemas, tool descriptions, and tracker tools
+
+### Fixed
+- Test data updated for validators→agents schema rename
+- String-typed numeric params coerced before Zod validation
+
+## [1.3.0] - 2026-03-01
+
+### Added
+- Definition metadata enrichment and background registry sync
+
+## [1.2.0] - 2026-02-15
+
+### Changed
+- `BackendApiClient` replaced with `@uluops/ops-sdk`
+- Production URL default added so users only need API key
+
+### Fixed
+- 9 DX validator issues resolved
+- 4 live-testing bugs in MCP tools fixed
+- Missing `get_discovery` and `get_validator_matrix` tool specs added
+- Deferred deprecation logging, `apiKey` validation, and tool description enrichment
+- Post-implementation validation issues resolved
+
+## [1.1.0] - 2026-02-07
+
+### Added
+- `false-positive` status added to issue lifecycle
+- `IssueType` classification on MCP tool schemas
+- Domain-specific issue types accepted
+- Discovery timeline and validator-matrix analytics tools
+- Burndown and velocity MCP tools
+
+### Fixed
+- `workflow_type` included in run update path
+- Null `line_number` allowed in recommendation and issue inputs
+- `type` field included in `createIssue` request body
+- `run_id` sent in `X-Confirm-Delete` header instead of `'true'`
+
+## [1.0.0] - 2026-01-19
+
+### Added
+- Core MCP tools (P0): `save_run`, `query_issues`, `update_status`, `get_project_summary`, `delete_project`
+- Extended MCP tools (P1): `get_issue_details`, `get_run_details`, `diff_runs`, `archive_runs`, `get_analytics`, `search_issues`
+- P2 MCP tools: 17 additional tools for full API coverage (projects, runs, issues, taxonomy)
+- MCP resources for `validation://` URI scheme
+- API client with retry logic and error mapping
+- Structured logging with optional file output
+- Configuration for `mcp-secure-server` framework
+- Initial project setup with TypeScript, ESLint, Prettier, and Vitest
+
+### Fixed
+- Security limits increased for large validation payloads
+- `id` field handling standardized in status update tools
+
+[Unreleased]: https://github.com/Uluops/ops-uluops-mcp/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/Uluops/ops-uluops-mcp/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.21.0...v0.2.0
+[1.21.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.20.0...v1.21.0
+[1.20.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.19.0...v1.20.0
+[1.19.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.18.0...v1.19.0
+[1.18.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.17.0...v1.18.0
+[1.17.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.16.0...v1.17.0
+[1.16.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.15.0...v1.16.0
+[1.15.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.14.0...v1.15.0
+[1.14.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.13.0...v1.14.0
+[1.13.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.12.0...v1.13.0
+[1.12.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.11.0...v1.12.0
+[1.11.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.10.0...v1.11.0
+[1.10.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.9.0...v1.10.0
+[1.9.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.8.0...v1.9.0
+[1.8.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.7.0...v1.8.0
+[1.7.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/Uluops/ops-uluops-mcp/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/Uluops/ops-uluops-mcp/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UluOps
+
+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,272 @@
+# @uluops/ops-mcp
+
+MCP (Model Context Protocol) server for the UluOps Platform API. Provides **48 tools** and **3 resources** (2 functional, 1 template placeholder) that enable Claude Code, Cursor, and other MCP hosts to interact with the UluOps Platform.
+
+## Design Philosophy
+
+**Thin Client Pattern**: This MCP server contains **zero business logic**. All data processing, validation, storage, and analytics are handled by the backend API. The server's sole responsibility is protocol translation between MCP's stdio-based JSON-RPC and the backend's REST API.
+
+## Installation
+
+Requires **Node.js 18** or later.
+
+**Option A — npx (no install):**
+
+```bash
+npx -y @uluops/ops-mcp
+```
+
+**Option B — global install:**
+
+```bash
+npm install -g @uluops/ops-mcp
+```
+
+This exposes the `uluops-ops-mcp` binary on your PATH.
+
+## Configuration
+
+Set environment variables in your MCP host configuration (see "Usage with Claude Code" below) or in a `.env` file when developing locally.
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `ULUOPS_BASE_URL` | Backend API URL | Yes |
+| `ULUOPS_API_KEY` | API authentication key (must start with `ulr_`, min 20 chars) | Yes |
+| `ULUOPS_ORG_SLUG` | Organization slug for multi-org contexts | No |
+| `ULUOPS_TRACKER_TIMEOUT` | Request timeout (ms) | No (default: 30000) |
+| `ULUOPS_TRACKER_RETRIES` | Number of retry attempts on failure | No (default: 3) |
+| `LOG_LEVEL` | Logging level (`debug`, `info`, `warn`, `error`) | No (default: info) |
+
+### Advanced Logging
+
+By default this server logs only to stderr at `info` level. To enable structured file logging, set:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ENABLE_FILE_LOGGING` | Write JSON logs to disk | `false` |
+| `LOG_DIR` | Directory for log files | `logs` |
+| `VERBOSE_LOGGING` | Include extra diagnostic detail | `false` |
+| `LOG_PERFORMANCE_METRICS` | Emit per-call timing metrics | `false` |
+
+When `ENABLE_FILE_LOGGING=true`, a `logs/` directory is created in the process's working directory.
+
+### Production Tightening
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ENABLE_DETAILED_ERRORS` | Propagate redacted error reasons in `error.message` so callers can diagnose failures without parsing the data envelope. Set to `false` to suppress in tightened production deployments. | `true` |
+
+## Usage with Claude Code
+
+Add to your Claude Code MCP configuration (`.mcp.json`):
+
+**Option 1: npx (lowest friction — no install)**
+```json
+{
+  "mcpServers": {
+    "uluops-ops": {
+      "command": "npx",
+      "args": ["-y", "@uluops/ops-mcp"],
+      "env": {
+        "ULUOPS_BASE_URL": "https://api.uluops.ai/api/v1",
+        "ULUOPS_API_KEY": "ulr_your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**Option 2: Globally installed binary**
+```json
+{
+  "mcpServers": {
+    "uluops-ops": {
+      "command": "uluops-ops-mcp",
+      "args": [],
+      "env": {
+        "ULUOPS_BASE_URL": "https://api.uluops.ai/api/v1",
+        "ULUOPS_API_KEY": "ulr_your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Quick Start Examples
+
+Once configured, Claude Code can use the uluops tracker tools:
+
+```typescript
+// Save validation results from a workflow run
+save_run({
+  project: "my-project",
+  workflow_type: "ship",
+  agents: [{ name: "code-validator", score: 85, decision: "PASS" }],
+  recommendations: [{ agent: "code-validator", title: "Fix lint error", priority: "suggested" }]
+})
+
+// Query open issues for a project
+query_issues({ project: "my-project", status: "open", priority: "critical" })
+
+// Get project summary with issue counts and trends
+get_project_summary({ project: "my-project" })
+```
+
+## Rate Limiting Configuration
+
+This server uses `mcp-secure-server` with configuration optimized for Claude Code's usage patterns.
+
+### Claude Code Usage Patterns
+
+| Operation | Typical Parallel Calls | Notes |
+|-----------|------------------------|-------|
+| Query context (summary, issues, runs) | 3-5 | Low burst |
+| Create issues from validation workflow | 10-30 | High burst |
+| Update agents with metrics | 6 | Medium burst |
+| Save recommendations | 1 (with array) | Single call |
+
+Claude Code issues tool calls in short, intense bursts (<2s) followed by "thinking" pauses. The default configuration accounts for this:
+
+```typescript
+{
+  securityLevel: 'basic',
+  maxRequestsPerMinute: 120,
+  burstThreshold: 15,        // Covers 90% of parallel operations
+  burstWindowMs: 5000,       // 5s window resets between thinking periods
+  automationDetection: {
+    enabled: false,          // Claude Code is trusted automation
+  },
+}
+```
+
+### Why These Settings
+
+- **`burstThreshold: 15`** - Handles typical validation workflow bursts (10-15 parallel issue creates or queries)
+- **`burstWindowMs: 5000`** - Short window resets between Claude's "thinking" periods, preventing false positives
+- **`automationDetection: disabled`** - Claude Code IS automation with consistent timing patterns; detecting it as a "bot" would block legitimate use
+
+## Available Tools
+
+### Core Tools (P0)
+| Tool | Description |
+|------|-------------|
+| `save_run` | Save validation pipeline output with issue correlation |
+| `query_issues` | Query issues with filtering by status, priority, validator |
+| `update_status` | Update issue status (completed, deferred, wontfix) |
+| `get_project_summary` | Get project overview with workflow and validator stats |
+| `delete_project` | Delete project data (requires confirmation) |
+
+### Extended Tools (P1)
+| Tool | Description |
+|------|-------------|
+| `create_issue` | Create a user-submitted issue directly (outside validation runs) |
+| `get_issue_details` | Full issue lifecycle with occurrences, notes, history |
+| `get_run_details` | Run information with all recommendations and stats |
+| `diff_runs` | Compare two validation runs (fixed, new, unchanged issues) |
+| `archive_runs` | Archive old runs without deletion |
+| `get_analytics` | Cross-project analytics (8 metric types available) |
+| `search_issues` | Search issues across projects with relevance ranking |
+| `list_agents` | List canonical agents from manifest |
+| `validate_run` | Preview save operation without modifying database |
+| `get_issue_history` | Full issue history with changes between runs |
+| `add_issue_note` | Add context, resolution, or blocker notes to issues |
+| `edit_issue` | Edit issue metadata (title, file_path, severity, etc.) |
+| `merge_issues` | Merge duplicate issues into a target issue |
+| `bulk_update_status` | Bulk update multiple issue statuses in one transaction |
+| `update_run` | Update run metadata post-hoc (tokens, scores, timestamps) |
+| `get_agent_reliability` | Analyze agent effectiveness and reliability scores |
+| `get_agent_lifecycle` | Lifecycle metrics for an agent across runs |
+
+### Project Tools (P2)
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all active projects |
+| `get_project` | Get a single project by ID or name |
+| `get_project_trends` | Get issue trends over time for a project |
+| `create_project` | Create a new project |
+| `update_project` | Update a project name |
+| `soft_delete_project` | Soft delete a project (can be restored later) |
+| `restore_project` | Restore a soft-deleted project |
+
+### Run Tools (P2)
+| Tool | Description |
+|------|-------------|
+| `get_run` | Get a run by UUID |
+| `list_runs` | List runs for a project |
+| `get_latest_run` | Get the latest run for a project |
+| `delete_run` | Delete a run (requires confirmation) |
+
+### Issue Tools (P2)
+| Tool | Description |
+|------|-------------|
+| `get_issue_by_fingerprint` | Get an issue by its SHA-256 fingerprint |
+| `update_issue_by_fingerprint` | Update an issue status by its fingerprint |
+| `restore_issue` | Restore a soft-deleted issue |
+| `soft_delete_issue` | Soft delete an issue (can be restored later) |
+| `undo_issue_status` | Undo the last status change on an issue |
+
+### Taxonomy Tools (P2)
+| Tool | Description |
+|------|-------------|
+| `get_taxonomy` | Get the failure taxonomy schema (domains, modes, severities) |
+| `get_full_taxonomy_analytics` | Get full taxonomy analytics with distribution by domain |
+| `get_burndown` | Get taxonomy burndown with time series and trend analysis per failure domain |
+| `get_velocity` | Get velocity metrics per failure mode with sparkline data and trend reliability |
+| `get_discovery` | Get discovery timeline showing new vs recurring issues over time |
+| `get_agent_matrix` | Get agent-taxonomy coverage matrix with blind spot detection |
+
+### Analysis Tools (P2)
+| Tool | Description |
+|------|-------------|
+| `get_run_analysis` | Structured analysis records for a single run (decision, scoring, findings) |
+| `get_project_analysis` | Aggregated analysis records across all runs in a project |
+| `query_analysis_records` | Query analysis records by type, classification, severity |
+| `get_agent_runs_analysis` | Per-run analysis records grouped by agent |
+
+## Available Resources
+
+MCP resources provide read-only access to validation data via the `validation://` URI scheme.
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| Projects | `validation://projects` | List all tracked projects |
+| Project Summary | `validation://projects/{project}` | Template placeholder (use `get_project_summary` tool) |
+| Taxonomy | `validation://taxonomy` | Failure taxonomy schema for classifying issues |
+
+### Resource Usage
+
+```typescript
+// List all projects (returns JSON array of project names)
+read_resource("validation://projects")
+
+// Get the failure taxonomy schema (domains, modes, severity codes)
+read_resource("validation://taxonomy")
+```
+
+**Note:** For project-specific data, use the `get_project_summary` tool instead of resources. MCP resource templates with parameters are not fully supported by the SDK.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Development mode with watch
+npm run dev
+
+# Run tests
+npm test
+
+# Type checking
+npm run typecheck
+
+# Linting
+npm run lint
+
+# Build for production
+npm run build
+```
+
+## License
+
+MIT