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

• 7 investigation tools — process instances, 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.

Variable	Required	Description
CIB7_URL	Yes	CIB Seven REST API URL (e.g., http://localhost:6009/rest)
KEYCLOAK_URL	No	Keycloak server URL (e.g., https://keycloak.example.com)
KEYCLOAK_REALM	No	Keycloak realm name
KEYCLOAK_CLIENT_ID	No	Keycloak client ID
KEYCLOAK_CLIENT_SECRET	No	Keycloak client secret
CIB7_REDACT_PATTERNS	No	Comma-delimited regex patterns for variable redaction (e.g., password.*,secret.*,token.*)

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

Tool	Description
get_process_instance	Look up a process instance by ID — state, definition, business key
list_process_instances	Search process instances by definition key, business key, or state
list_incidents	List open incidents, optionally filtered by process instance
get_activity_history	Execution trace — every activity that ran, in order
get_process_variables	All variables for a process instance (with redaction)
get_process_definition_xml	BPMN XML model (diagram elements stripped for readability)
get_job_details	Job execution details — retries, exception messages

Prompts

Prompt	Description
diagnose_stuck_process	Step-by-step diagnostic for a stuck process instance
incident_report	Comprehensive report of all open incidents with root cause analysis

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"

Development

npm install
npm run build
npm test

Requires Node.js 18+.

License

MIT