UluOps · Operating Intelligence as Infrastructure

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

Table of Contents

• Design Philosophy
• Installation
• Configuration
• Usage with Claude Code
• Quick Start Examples
• Rate Limiting Configuration
• Available Tools
• Available Resources
• Development
• License

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

npx -y @uluops/ops-mcp

Option B — global install:

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_API_KEY | API authentication key (must start with ulr_, min 20 chars). Create and manage keys at app.uluops.ai/settings/api-keys | 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) |

The backend URL is handled automatically by @uluops/ops-sdk — production by default, no configuration needed.

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)

{
  "mcpServers": {
    "uluops-ops": {
      "command": "npx",
      "args": ["-y", "@uluops/ops-mcp"],
      "env": {
        "ULUOPS_API_KEY": "ulr_your-api-key-here"
      }
    }
  }
}

Option 2: Globally installed binary

{
  "mcpServers": {
    "uluops-ops": {
      "command": "uluops-ops-mcp",
      "args": [],
      "env": {
        "ULUOPS_API_KEY": "ulr_your-api-key-here"
      }
    }
  }
}

Quick Start Examples

Once configured, Claude Code can use the uluops tracker tools. These are MCP tool invocations (issued by the MCP host), not runnable 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:

{
  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; cross_project_patterns returns [] — placeholder until pattern aggregation ships) | | 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 | Merged audit-event stream (occurrences, status, notes) as an envelope {issueId, events[], totalEvents, truncated} — includes undo tombstones (v0.4.0+) | | 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

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

# 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