# IBM Concert MCP Server

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

A Model Context Protocol (MCP) server that connects AI agents and assistants to **IBM Concert** — enabling autonomous workflow health monitoring, incident diagnosis, auto-remediation, CVE triage, and Slack alerting through natural language.

## Overview

This repository contains two complementary MCP servers:

| Server | Module | Purpose |
|---|---|---|
| **concert-workflow-monitor** | `src/ibm_concert_mcp/server.py` | Live workflow health checks, auto-remediation, CVE queries, Slack alerts, incident tracking |
| **concert-knowledge** | `src/ibm_concert_mcp/knowledge/server.py` | Semantic RAG search over IBM Concert documentation (Supabase + pgvector) |

## Available Tools

### concert-workflow-monitor

| Tool | Description |
|---|---|
| `list_monitored_workflows` | List all Concert workflows being monitored |
| `check_workflow_health` | Run a live health check against one or all workflows |
| `get_failing_workflows` | Return only workflows currently in ERROR/WARNING state with diagnosis |
| `get_workflow_diagnosis` | Diagnose a workflow and auto-post an error alert to Slack |
| `remediate_workflow` | Auto-fix a failing workflow (soft re-invoke or `oc rollout restart`) |
| `get_concert_cve_summary` | Query Concert for top CVEs across your application inventory |
| `trigger_package_remediation` | Invoke Concert's built-in package remediation workflow (raises GitHub PR + ServiceNow ticket) |
| `upload_scan_to_concert` | Push an updated vulnerability/SBOM scan to Concert |
| `send_slack_alert` | Post a notification to the configured Slack channel |
| `get_incident_stats` | MTTR and incident statistics for the last N days |
| `get_recent_incident_log` | Most recent incidents from the incident database |
| `receive_webhook_event` | Process inbound Concert webhook events for zero-latency detection |
| `record_recommendation_feedback` | Record 👍/👎 engineer feedback to improve future diagnoses |
| `get_recommendation_learnings` | Show what the agent has learned from past feedback |

### concert-knowledge

| Tool | Description |
|---|---|
| `search_concert_docs` | Semantic similarity search over all ingested Concert documentation |
| `list_concert_sources` | List all documentation sources indexed in the knowledge base |

## Prerequisites

- Python 3.10 or higher
- `pip` or `uv`
- Access to an IBM Concert instance
- Slack Incoming Webhook URL (for alerting)
- *(Optional)* Supabase project for incident tracking and knowledge RAG
- *(Optional)* OpenShift CLI (`oc`) for the `oc rollout restart` remediation strategy

## Installation

```bash
git clone https://github.com/ibm-ai-platform/ibm-concert-mcp.git
cd ibm-concert-mcp

# Workflow monitor
pip install -r requirements.txt

# Knowledge server (separate — heavier ML dependencies)
pip install -r requirements-knowledge.txt
```

Or with `uv`:

```bash
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
```

## Configuration

Copy `.env.example` to `.env` and fill in your values:

```bash
cp .env.example .env
```

### Required environment variables

| Variable | Description |
|---|---|
| `CONCERT_API_KEY` | IBM Concert API key (base64-encoded `user:token`) |
| `SLACK_WEBHOOK_URL` | Slack Incoming Webhook URL |

### Optional environment variables

| Variable | Default | Description |
|---|---|---|
| `CONCERT_BASE_URL` | TechZone gateway | Concert Workflows gateway URL |
| `CONCERT_REST_BASE_URL` | TechZone host | Concert main host (for CVE/ingestion API) |
| `CONCERT_INSTANCE_ID` | — | Concert instance UUID (for CVE API) |
| `SUPABASE_URL` | — | Supabase project URL (incident DB + knowledge RAG) |
| `SUPABASE_PUBLISHABLE_KEY` | — | Supabase anon/publishable key |
| `OC_NAMESPACE` | `concert-workflows` | OpenShift namespace for `oc` remediation |
| `RUNBOOK_DIR` | `./runbooks` | Directory where auto-generated runbooks are written |
| `RECOVERY_TIMEOUT_SECONDS` | `90` | How long to wait for recovery after `oc restart` |
| `ALERT_ON_WARNING` | `false` | Also alert on HTTP 200 empty-body (warning) responses |
| `AUTO_SLACK` | `true` | Auto-post Slack alerts on diagnosis/resolution |
| `VERIFY_TLS` | `false` | Verify TLS certificates |
| `MCP_TRANSPORT` | `stdio` | `stdio` \| `sse` \| `streamable-http` |
| `MCP_HOST` | `127.0.0.1` | Host for SSE/HTTP transport |
| `MCP_PORT` | `8000` | Port for SSE/HTTP transport (workflow monitor) |

For the knowledge server, also set:

| Variable | Description |
|---|---|
| `SUPABASE_URL` | Supabase project URL |
| `SUPABASE_PUBLISHABLE_KEY` | Supabase anon/publishable key |

## Usage

### stdio transport (AI agent / IDE use)

Add the following to your MCP client configuration (e.g. `~/.bob/settings/mcp_settings.json`, Claude Desktop `claude_desktop_config.json`, or VS Code `mcp.json`):

```json
{
  "mcpServers": {
    "concert-workflow-monitor": {
      "command": "uvx",
      "args": [
        "concert-workflow-monitor"
      ],
      "env": {
        "CONCERT_API_KEY": "<your-concert-api-key>",
        "SLACK_WEBHOOK_URL": "<your-slack-webhook-url>",
        "MCP_TRANSPORT": "stdio"
      }
    },
    "concert-knowledge": {
      "command": "uvx",
      "args": [
        "--from",
        "ibm-concert-mcp[knowledge]",
        "python",
        "-m",
        "ibm_concert_mcp.knowledge.server"
      ],
      "env": {
        "SUPABASE_URL": "<your-supabase-url>",
        "SUPABASE_PUBLISHABLE_KEY": "<your-supabase-key>",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

### SSE / HTTP transport (shared/remote deployment)

Run the server centrally so colleagues can point their MCP clients at a URL — no local Python install required:

```bash
export CONCERT_API_KEY=<your-key>
export SLACK_WEBHOOK_URL=<your-webhook>
export MCP_TRANSPORT=sse
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
python -m ibm_concert_mcp.server
```

Colleagues add this to their MCP client config:

```json
{
  "mcpServers": {
    "concert-workflow-monitor": {
      "type": "sse",
      "url": "http://<your-server>:8000/sse"
    }
  }
}
```

A `/health` HTTP endpoint is also available at `http://<host>:<port>/health` for dashboard integration.

## Typical incident-response loop

Once connected to an AI agent (e.g. IBM Bob, Claude), you can drive the full loop with natural language:

```
"Check if any Concert workflows are failing"
→ get_failing_workflows()

"Diagnose the akshay-test-fail workflow"
→ get_workflow_diagnosis("akshay-test-fail")

"Try to fix it automatically"
→ remediate_workflow("akshay-test-fail", strategy="auto")

"Post the result to Slack"
→ send_slack_alert(...)
```

## CVE remediation loop

```
"Show me the top Priority 1 CVEs"
→ get_concert_cve_summary(priority="1")

"Trigger package remediation for my-app, assign to jsmith"
→ trigger_package_remediation(application_name="my-app", git_repo="...", github_assignee="jsmith")

"Upload the updated SBOM"
→ upload_scan_to_concert(scan_type="package_sbom", ...)
```

## Learning loop

The server accumulates 👍/👎 feedback from engineers to improve future diagnoses:

```
"The recommendation didn't help — what actually fixed it was restarting the gateway pod"
→ record_recommendation_feedback("akshay-test-fail", vote="down", actual_fix="restart gateway pod")

"What has the agent learned so far?"
→ get_recommendation_learnings()
```

## Registering Concert workflows to monitor

Edit the `WORKFLOWS` list near the top of [`src/ibm_concert_mcp/server.py`](src/ibm_concert_mcp/server.py):

```python
WORKFLOWS = [
    # (adapter_name, environment, workflow_name, display_name)
    ("my-adapter", "prod", "my-workflow", "My Workflow Display Name"),
]
```

## Architecture

```
AI Agent (Bob / Claude / etc.)
        │
        │  MCP (stdio or SSE)
        ▼
concert-workflow-monitor ──► IBM Concert Workflows API
        │                ──► OpenShift (oc rollout restart)
        │                ──► Slack (Incoming Webhook)
        │                ──► Supabase (incident DB)
        │
concert-knowledge ──────────► Supabase pgvector (Concert docs RAG)
```

## License

Apache License 2.0 — see [LICENSE](LICENSE).

## Contributing

Pull requests welcome. See [CONTRIBUTING.md](https://github.com/ibm/mcp/blob/main/CONTRIBUTING.md) for guidelines.