# nexus-convergence-mcp

MCP server wrapping the [Balanced Intelligence Convergence Pipeline](https://github.com/Gonzih/nexus-protocols).

Exposes the full pipeline as 4 MCP tools usable by any MCP-compatible client (Claude Code, Claude Desktop, etc.).

## Tools

### `converge_query`

Fan out a query to multiple LLMs, run consensus, return structured result.

```json
{
  "query": "Is this treatment effective?",
  "models": ["gpt-4o", "claude-3-5-sonnet-20241022", "gemini-1.5-pro"],
  "policy_set": "hipaa"
}
```

Returns: `run_id`, `agreement_score`, `stability`, `agreed_claims`, `disputed_claims`, `final_answer`.

### `get_evidence_ladder`

Return the full Evidence Ladder for a query — immutable audit trail of every pipeline step.

```json
{ "query_id": "run-uuid" }
```

Returns: ordered list of entries from `QUERY` → `DECOMPOSE` → `MODEL_EXECUTE` → `CONSENSUS` → `VERIFY` → `CONCLUDE`.

### `check_compliance`

Check content against HIPAA/EU_AI_ACT/NIST/CUSTOM policies.

```json
{
  "content": "Patient SSN is 123-45-6789",
  "categories": ["HIPAA"]
}
```

Returns: `passed`, `blocked`, `violations`, `warnings`, `logs`.

### `list_model_disagreements`

Return where models diverged — inversions (direct contradictions), disputed claims, low-similarity pairs.

```json
{ "query_id": "run-uuid" }
```

Returns: `inversions`, `disputed_claims`, `low_similarity_pairs`.

## MCP configuration

Add to your MCP config:

```json
{
  "mcpServers": {
    "nexus-convergence": {
      "command": "npx",
      "args": ["-y", "@gonzih/nexus-convergence-mcp"],
      "env": {
        "CONVERGENCE_SERVICE_URL": "http://your-convergence-service:3000",
        "CONSENSUS_SERVICE_URL": "http://your-consensus-service:3001",
        "EVIDENCE_SERVICE_URL": "http://your-evidence-service:3002",
        "COMPLIANCE_SERVICE_URL": "http://your-compliance-service:3003",
        "NEXUS_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Environment

```bash
CONVERGENCE_SERVICE_URL=http://localhost:3000
CONSENSUS_SERVICE_URL=http://localhost:3001
EVIDENCE_SERVICE_URL=http://localhost:3002
COMPLIANCE_SERVICE_URL=http://localhost:3003
NEXUS_API_KEY=your-api-key
```

## Development

```bash
npm ci
npm run build
npm start
npm test
```