Lucid Observability Agent

MCP server and OpenClaw plugin for monitoring, diagnosing, and auto-correcting observability issues across platform services. Connects to Sentry for error tracking, PostgreSQL for OpenMeter billing pipeline health, and ships with AI-powered diagnosis, incident runbooks, and cross-service correlation.

Unlike the official Sentry MCP server (which is a pure API wrapper), this agent adds:

• Root cause analysis --- pattern matching against error titles, stack traces, and platform-specific knowledge

• Cross-service correlation --- traces errors across multiple services via trace_id / run_id

• Billing pipeline monitoring --- outbox health, dead letter recovery, usage anomaly detection

• Incident runbooks --- 10 error categories with 5-phase playbooks (triage -> diagnose -> mitigate -> resolve -> postmortem)

• Alert rule generation --- suggests Sentry alert rules based on actual error patterns

• Production readiness auditing --- validates env vars, conventions, and configuration

v3.0.0 --- Dual entry point architecture: works as both an MCP server (Claude Code / Claude Desktop) and an OpenClaw plugin with slash commands and heartbeat support.

Quick Start

As MCP Server (Claude Code)

Install from npm and run directly:

npx lucid-obs-agent

Or add to your MCP config (~/.claude.json or Claude Desktop settings):

{
  "mcpServers": {
    "observability": {
      "command": "npx",
      "args": ["lucid-obs-agent"],
      "env": {
        "SENTRY_AUTH_TOKEN": "sntrys_...",
        "SENTRY_ORG": "your-org",
        "DATABASE_URL": "postgresql://..."
      }
    }
  }
}

Or run from source:

{
  "mcpServers": {
    "observability": {
      "command": "npx",
      "args": ["tsx", "/path/to/lucid-observability-agent/src/bin.ts"],
      "env": {
        "SENTRY_AUTH_TOKEN": "sntrys_...",
        "DATABASE_URL": "postgresql://..."
      }
    }
  }
}

As OpenClaw Plugin

1. Install the package:

npm install lucid-observability-agent

2. Add to your openclaw.json:

{
  "plugins": [
    {
      "id": "lucid-observability",
      "package": "lucid-observability-agent",
      "config": {
        "sentryAuthToken": "sntrys_...",
        "sentryOrg": "your-org",
        "databaseUrl": "postgresql://..."
      }
    }
  ]
}

The plugin registers all 16 tools, 3 resources, 3 prompts, and 2 slash commands automatically.

Related MCP server: Cost Management MCP

Environment Variables

Tools (16)

Sentry (6)

Diagnosis (2)

OpenMeter (4)

Configuration (2)

Auto-Fix (2)

Resources (3)

Prompts (3)

These prompts are also documented with full workflows in SKILL.md.

Commands (OpenClaw)

When running as an OpenClaw plugin, two slash commands are available:

OpenClaw Heartbeat

OpenClaw supports autonomous monitoring via a HEARTBEAT.md file. The agent runs the checks on a schedule and reports findings without manual prompting.

Add a HEARTBEAT.md to your project root (or reference the checklist in SKILL.md):

## Observability Checks
- Run `openmeter_outbox_health` — alert if dead letters > 0 or stuck leases
- Run `sentry_list_issues` sorted by freq — flag issues with count > 100
- Run `check_config_health` — warn if any critical checks failing
- If issues found, run `diagnose_issue` and suggest resolution

The heartbeat runs these checks periodically and surfaces warnings or critical findings through OpenClaw's notification system.

Configuration

The agent ships with Lucid platform defaults (config/lucid.json). Override by setting AGENT_CONFIG_PATH:

AGENT_CONFIG_PATH=./my-config.json npx lucid-obs-agent

When using the OpenClaw plugin, pass the config path via plugin config:

{
  "configPath": "./config/my-config.json"
}

See config/example.json for a minimal config template.

Development

git clone https://github.com/daishizenSensei/lucid-observability-agent
cd lucid-observability-agent
npm install
npm run typecheck   # Verify types
npm run dev         # Start with tsx (hot reload)
npm run build       # Build with tsup to dist/
npm run start       # Run built output

Project Structure

src/
  bin.ts            # CLI entry point (MCP stdio server)
  index.ts          # Package re-export (core + mcp + openclaw)
  mcp.ts            # MCP server setup (tools, resources, prompts)
  openclaw.ts       # OpenClaw plugin entry (tools, commands, skills)
  core/
    tools/          # 16 tool definitions (ToolParamDef format)
    resources/      # 3 resource data providers
    commands/       # /obs-status, /obs-check handlers
    config/         # Config loading and defaults
    helpers/        # Sentry API, DB client, shared utils
    types/          # TypeScript type definitions

License

MIT