ops-mcp
MCP server for the UluOps Platform API — 55 tools, 2 resources.
Overview
MCP client for the UluOps Platform API. Provides 55 tools and 2 resources for the tracker: runs, issues, the project log, analytics — zero business logic, pure protocol translation.
Installation
npm install @uluops/ops-mcpThis installs the uluops-ops-mcp binary. To install it globally instead, use npm install -g @uluops/ops-mcp.
Naming note — this one server wears a different name at each layer. The npm package is @uluops/ops-mcp; it installs a binary named uluops-ops-mcp; the recommended .mcp.json server key is uluops-tracker (that key is what produces the mcp__uluops-tracker__* tool names in Claude Code); and in prose we call it the Tracker. All four refer to the same component. The separate @uluops/registry-mcp (uluops-registry) server is a different thing — see MCP Clients.
Configuration
The server runs over stdio from npx, so the only things to set are the API key and, on native Windows, the launcher. Pick your platform — each block is ready to paste; replace ulr_your-api-key-here with a key from app.uluops.ai/settings/api-keys (see Setup → Your API key). This is the same entry npx @uluops/setup writes for you on macOS, Linux and WSL.
Where it goes (Claude Code): ~/.claude.json for every project on the machine (user scope), or .mcp.json in a repo root (project scope, shareable). On Windows the user-scope file is %USERPROFILE%\.claude.json. Other harnesses: OpenCode ~/.config/opencode/opencode.json, Gemini CLI ~/.gemini/settings.json, Codex ~/.codex/config.toml (TOML form below).
Linux / WSL
{
"mcpServers": {
"uluops-tracker": {
"command": "npx",
"args": ["-y", "@uluops/ops-mcp"],
"env": {
"ULUOPS_API_KEY": "ulr_your-api-key-here"
}
}
}
}Or let Claude Code write it (user scope; keep an option between --env and the server name, or the CLI reads the name as another pair):
claude mcp add --env ULUOPS_API_KEY=ulr_your-api-key-here --transport stdio --scope user uluops-tracker -- npx -y @uluops/ops-mcpmacOS
The JSON is identical to Linux. One macOS-specific gotcha: if Node comes from nvm or Homebrew and Claude Code was launched from the Dock rather than a terminal, it may not find npx on PATH. Use the absolute path (which npx) as the command:
{
"mcpServers": {
"uluops-tracker": {
"command": "/Users/you/.nvm/versions/node/v24.14.1/bin/npx",
"args": ["-y", "@uluops/ops-mcp"],
"env": {
"ULUOPS_API_KEY": "ulr_your-api-key-here"
}
}
}
}PowerShell (native Windows)
On Windows npx is a .cmd shim, so stdio servers are launched through cmd /c. Set the key for the session or persist it for your user, then reference it in the config:
$env:ULUOPS_API_KEY = "ulr_your-api-key-here" # this session
[Environment]::SetEnvironmentVariable("ULUOPS_API_KEY", "ulr_your-api-key-here", "User") # persisted{
"mcpServers": {
"uluops-tracker": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@uluops/ops-mcp"],
"env": {
"ULUOPS_API_KEY": "ulr_your-api-key-here"
}
}
}
}The Linux and macOS blocks are what @uluops/setup writes and are exercised daily. The Windows block follows the standard cmd /c npx pattern for stdio MCP servers but has not yet been exercised on a Windows machine by us — if it misbehaves, run cmd /c npx -y @uluops/ops-mcp in PowerShell with the key set and send us the first lines it prints.
Codex (~/.codex/config.toml)
[mcp_servers.uluops-tracker]
command = "npx"
args = ["-y", "@uluops/ops-mcp"]
[mcp_servers.uluops-tracker.env]
ULUOPS_API_KEY = "ulr_your-api-key-here"If you installed the package globally (npm install -g @uluops/ops-mcp), "command": "uluops-ops-mcp", "args": [] works in place of npx on every platform. Restart the harness after editing the config.
The server connects to https://api.uluops.ai/api/v1/ops by default. Override with ULUOPS_BASE_URL only if you're running a local or custom API instance.
| Variable | Description | Required |
|---|---|---|
ULUOPS_API_KEY | API key — must start with ulr_, min 20 chars | Yes |
ULUOPS_BASE_URL | Backend API URL | No (default: https://api.uluops.ai/api/v1/ops) |
ULUOPS_TRACKER_TIMEOUT | Request timeout in ms | No (default: 30000) |
LOG_LEVEL | Logging level | No (default: info) |
Quick Start
// Save a validation 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",
failure_code: "STR-MAL/M"
}]
})
// Query open critical issues
query_issues({ project: "my-project", status: "open", priority: "critical" })
// Get project summary with issue counts and trends
get_project_summary({ project: "my-project" })Tools Reference
Runs
| Tool | Description |
|---|---|
save_run | Save validation pipeline output with fingerprint-based issue correlation. Supports analysis_summary, analysis_records, and exploration_maps for structured agent output. |
update_run | Update run metadata post-hoc — add tokens, scores, recommendations, or analysis data after initial save |
validate_run | Preview what save_run would do without writing to the database |
preview_update_run | Preview an analysis-bearing update_run under the requested record_write_mode. Reports, per agent named in the payload, what the write would supersede, create, and — under replace — retire by omission (wouldRetireRecordIds; always empty under merge, which cannot retire). Nothing is written |
get_run | Get a run by UUID |
get_run_details | Run info with all recommendations, correlation stats (new/recurring/regression). Omit run_number for latest |
get_run_analysis | Get structured analysis records and summaries for a run — convention inventories, tension maps, system metrics |
get_latest_run | Get the most recent run for a project, optionally filtered by workflow type |
list_runs | List runs for a project with pagination |
diff_runs | Compare two runs — fixed, new, unchanged issues, and agent score changes |
delete_run | Delete a run (requires confirm: true) |
archive_runs | Archive old runs without deletion — by run number, date, or keep-last count |
Issues
| Tool | Description |
|---|---|
query_issues | Query issues by project, status, priority, agent, severity, failure domain/mode, persistence |
search_issues | Full-text search across projects with relevance ranking and multi-filter support |
create_issue | Create a user-submitted issue directly, outside of validation runs |
get_issue_details | Full issue lifecycle with occurrences, notes, regression history, and optionally related issues |
get_issue_history | Complete issue history — all occurrences, changes between runs, and notes |
get_issue_by_fingerprint | Look up an issue by its SHA-256 fingerprint |
update_status | Update issue status — identify by ID, fingerprint, or file_path+title |
update_issue_by_fingerprint | Update issue status by fingerprint |
bulk_update_status | Update multiple issue statuses in one transaction (max 100) |
undo_issue_status | Undo the last status change on an issue |
edit_issue | Edit issue metadata (title, file_path, category, severity, failure_code) without changing fingerprint |
add_issue_note | Add context, resolution, or blocker notes to an issue |
merge_issues | Merge duplicate issues into a target — migrates occurrences, marks sources as merged |
soft_delete_issue | Soft-delete an active issue. Sets deleted_at; reversible via restore_issue |
restore_issue | Restore a soft-deleted issue |
Projects
| Tool | Description |
|---|---|
list_projects | List all active projects (excludes soft-deleted) |
get_project | Get project by ID or name with metadata, run count, and issue stats |
create_project | Create a new project for tracking |
update_project | Rename a project |
get_project_summary | Project overview with workflow stats, agent performance, and issue counts |
get_project_trends | Issue trends over time for a project |
soft_delete_project | Soft-delete a project (can be restored). Requires confirmation |
restore_project | Restore a soft-deleted project with all associated data |
delete_project | Permanently delete all project data. Two-step confirmation required |
rehome_project | Move a project and its whole history (runs, issues, analytics) into another org. org is the source, target_org the destination; admin/owner in both. Reversible by moving it back |
get_project_log | The project's second history: runs (what was examined) and decisions (what was decided, with reasons) interleaved, newest first, plus what came back. One keyset-paged page of run / decision / regression events — the same read as ulu log |
get_log_stat | The log's rollup for a window: examined / found / decided (current status, completed = fixed) / cameBack (caught by a run vs reopened by decision) / activity. Project, or the resolved org with a per-project table — ulu log --stat / --orgs |
merge_projects | Merge one project into another: runs and issues are re-keyed into the target, colliding issues deduplicated by fingerprint, and the source soft-deleted. Pairwise only — chain calls to consolidate several. Run dry_run: true first; the merge is durable with no undo |
Analytics
| Tool | Description |
|---|---|
get_analytics | Cross-project analytics: agent_performance, resolution_rates, cross_project_patterns, file_hotspots, regression_analysis, trend_summary, cost_analysis, taxonomy_distribution |
get_agent_reliability | Agent effectiveness — false positive rates, resolution rates, reliability scores |
get_agent_matrix | Agent-taxonomy coverage matrix with blind spot detection and overlap analysis |
get_agent_lifecycle | Version lifecycle trajectory for an agent — performance per definition version |
get_agent_runs_analysis | Analysis summaries with run context for a specific agent across runs |
get_burndown | Taxonomy burndown with time series and trend analysis per failure domain |
get_velocity | Velocity metrics per failure mode with sparkline data and trend reliability |
get_discovery | Discovery timeline — new vs recurring issues over time |
Taxonomy
| Tool | Description |
|---|---|
get_taxonomy | Get the failure taxonomy schema (domains, modes, severities) |
get_full_taxonomy_analytics | Distribution analytics by domain, severity, mode, and agent |
Analysis Records
| Tool | Description |
|---|---|
get_project_analysis | Analysis summaries for a project — system metrics, category scores, epistemic assessments from cognitive lens runs |
query_analysis_records | Query analysis records across all projects — find calcified conventions, degraded tensions, decay vectors, and other structured findings |
list_agents | List canonical agents accepted by save_run |
Organizations
| Tool | Description |
|---|---|
get_org_audit_feed | An org's member-visible audit feed — today, projects that left the org for someone's personal org (who, when, where to). Any member may read it |
Account
| Tool | Description |
|---|---|
update_profile | Update the authenticated user's profile (username, name, bio, timezone, websiteUrl). Setting a username confirms it one-time and is required before creating or publishing registry definitions |
Resources
| Resource URI | Description |
|---|---|
validation://projects | List all tracked projects (JSON array) |
validation://taxonomy | Failure taxonomy schema — domains, modes, severity codes |
Resources vs Tools — For project-specific data, use the
get_project_summarytool rather than resources. MCP resource templates with parameters are not fully supported by the current SDK.
Issue Statuses
Issues support seven resolution statuses:
| Status | Meaning |
|---|---|
open | Active, unresolved |
completed | Genuine defect, fixed |
wontfix | Correct observation, not worth acting on (lifecycle mismatch) |
false-positive | Agent was factually wrong |
observation | Valid observation, tracked separately from defects |
deferred | Acknowledged, deferred to later |
merged | Merged into another issue |
Rate Limiting
Configured for Claude Code's burst-then-pause usage pattern:
| Setting | Value |
|---|---|
| maxRequestsPerMinute | 120 |
| burstThreshold | 15 |
| burstWindowMs | 5000 |
| automationDetection | disabled |
| Operation | Typical Parallel Calls |
|---|---|
| Query context (summary, issues, runs) | 3–5 |
| Create issues from validation workflow | 10–30 |
| Update agents with metrics | 6 |
| Save recommendations | 1 (array payload) |
Why automation detection is disabled — Claude Code is trusted automation with consistent timing patterns. Enabling bot detection would misidentify legitimate agent use as suspicious traffic.