cib7-mcp

MCP tool for investigating CIB Seven process instances. Gives Claude comprehensive knowledge of CIB Seven REST APIs with live execution and Keycloak authentication.

Features

• Investigation tools — process instances, counts, daily/weekly/monthly stats, incidents, activity history, variables, BPMN XML, jobs

• Semantic descriptions — Claude understands what each field means operationally, not just raw endpoint data

• BPMN introspection — fetch process definition XML, Claude reasons about expected vs actual execution path

• Keycloak auth — OIDC client credentials flow with automatic token refresh

• Variable redaction — configurable regex patterns to hide sensitive data

• Diagnostic prompts — diagnose_stuck_process and incident_report workflows

Installation

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "cib7": {
      "command": "npx",
      "args": ["cib7-mcp"],
      "env": {
        "CIB7_URL": "http://localhost:6009/rest"
      }
    }
  }
}

Claude Code

claude mcp add cib7-mcp -- npx cib7-mcp

Then set the environment variable CIB7_URL to your CIB Seven instance.

Configuration

All configuration is via environment variables.

If any KEYCLOAK_* variable is set, all four must be provided. If none are set, the tool runs in unauthenticated mode.

With Keycloak

{
  "mcpServers": {
    "cib7": {
      "command": "npx",
      "args": ["cib7-mcp"],
      "env": {
        "CIB7_URL": "https://your-instance.com/rest",
        "KEYCLOAK_URL": "https://your-keycloak.com",
        "KEYCLOAK_REALM": "your-realm",
        "KEYCLOAK_CLIENT_ID": "mcp-client",
        "KEYCLOAK_CLIENT_SECRET": "your-secret",
        "CIB7_REDACT_PATTERNS": "password.*,secret.*,token.*,creditCard.*"
      }
    }
  }
}

Tools

Response views

Four of the list-shaped tools accept a view parameter to control which per-row fields are returned. The top-level response is always a bare array of rows — only the field set per row changes.

view: "summary" is the default and typically drops 40–60% of the response size compared to the raw engine shape. Pass view: "full" when you need a field that isn't in the summary list above (e.g., processDefinitionName, startUserId, executionId, causeIncidentId, jobDefinitionId, tenant IDs).

Prompts

Statistics & counting

Three tools work together for volume questions without pulling back rows:

• list_process_instances — when you actually need the records. Supports filtering by definition key (single or multi), definition name, business key, startedBy, active/suspended/completed state, startedAfter/startedBefore, finishedAfter/finishedBefore, withIncidents, incidentStatus, plus sortBy/sortOrder and pagination via maxResults/firstResult.

• count_process_instances — same filter surface, returns just { count: N }. Use this for "how many?" questions so the engine never has to serialize rows.

• process_instance_stats — daily / weekly / monthly histogram of started instances over a date range. Takes from, to, and periodUnit (day, week, or month). Internally loops count_process_instances over date windows in parallel, so a 30-day daily histogram is 30 cheap count calls, not a row fetch.

process_instance_stats returns each bucket plus a summary with total, average-per-bucket, and the busiest/quietest bucket:

{
  "from": "2025-03-01T00:00:00.000Z",
  "to":   "2025-03-31T00:00:00.000Z",
  "periodUnit": "day",
  "bucketCount": 30,
  "summary": {
    "total": 4820,
    "average": 160.67,
    "max": { "period": "2025-03-17", "count": 412 },
    "min": { "period": "2025-03-09", "count": 3 }
  },
  "periods": [
    { "period": "2025-03-01", "start": "...", "end": "...", "count": 145 },
    { "period": "2025-03-02", "start": "...", "end": "...", "count": 160 }
  ]
}

A few things to know:

• Windows are right-open [start, nextStart), so no bucket double-counts the boundary instant.

• Week windows advance by 7 days from from. They are not aligned to Monday unless from is itself a Monday — pick your from accordingly if you want ISO weeks.

• Month windows advance by calendar month (handles variable-length months correctly).

• A safety cap of 500 buckets protects against runaway queries. Raise it with maxBuckets if you genuinely need a longer range, or use a coarser periodUnit.

Example Usage

Ask Claude:

• "Is process abc-123 stuck?"

• "Show me all open incidents"

• "What's the BPMN definition for process definition orderProcess:1:456?"

• "Generate an incident report"

• "How many instances of orderProcess are running right now?"

• "How many orderProcess instances finished with incidents last week?"

• "Show me daily volume for orderProcess over the last 30 days — which day was busiest?"

• "Give me a monthly histogram of all process starts this year."

Development

npm install
npm run build
npm test

Requires Node.js 18+.

License

MIT