<p align="center">
    <img src="https://i.ibb.co/d9HMQPc/conciliate-brand.png" alt="Conciliate - Live API contract layer for AI coding assistants" />
</p>

<p align="center">
    <a href="https://github.com/iv4n-ga6l/conciliate/blob/main/LICENSE" target="_blank" rel="noopener"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
    <a href="https://pypi.org/project/conciliate/" target="_blank" rel="noopener"><img src="https://img.shields.io/pypi/v/conciliate.svg" alt="PyPI version" /></a>
</p>

**Live API contract layer for AI coding assistants.**

Conciliate keeps Claude, Cursor, and VS Code Copilot in sync with your real microservices — across environments, specs, and code changes — so AI-generated code always matches your APIs.

## The Problem

- **AI suggests endpoints that don't exist** or are out of date
- **Frontend and backend assistants disagree** about what the API looks like
- **Microservice and third-party APIs change silently** — AI keeps using old shapes
- **No contract validation** between what AI generates and what the API actually accepts

## How Conciliate Solves This

Conciliate acts as a **live API contract layer** between your services and your AI tools:

1. **Extracts real API contracts** from your backend code (FastAPI, Flask, Express)
2. **Tracks multiple services** — local microservices, staging, production, third-party APIs
3. **Validates AI-generated requests** against actual API schemas
4. **Streams contract truth** to AI assistants via MCP protocol in real-time
5. **Detects breaking changes** across environments and narrates them for AI consumption

## Quick Start

```bash
pip install conciliate
cd /path/to/your/project
conciliate init          # Create .conciliate.yaml
conciliate mcp           # Run MCP server for AI assistants
```

## MCP Integration (AI Assistants)

Conciliate is MCP-native. Connect it to your AI assistant and it becomes the **single source of truth** for your API contracts.

### Claude Desktop

```json
{
  "mcpServers": {
    "conciliate": {
      "command": "conciliate",
      "args": ["mcp"],
      "cwd": "C:\\path\\to\\your\\project"
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "conciliate": {
      "command": "conciliate",
      "args": ["mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

### MCP Tools

| Tool | Description |
|------|-------------|
| `list_services` | List all registered microservices and their status |
| `list_endpoints` | List endpoints for a service, filterable by environment |
| `validate_request` | Validate a request payload against the live API contract |
| `explain_diff` | Explain API changes between environments or over time |
| `search_endpoints` | Search across all services by keyword |
| `get_endpoint_details` | Get full schema for a specific endpoint |
| `reload_api_spec` | Force-reload specs from all sources |

### MCP Resources

| Resource | Description |
|----------|-------------|
| `conciliate://api/spec` | Full OpenAPI specification |
| `conciliate://api/summary` | Human-readable API summary |
| `conciliate://api/diff` | Latest contract changes |

## Multi-Service Configuration

Track multiple API sources simultaneously — the core of Conciliate's contract layer:

```yaml
sources:
  - name: "Users API"
    type: local
    path: ./users-service
    framework: fastapi

  - name: "Auth Service"
    type: local
    path: ../auth-service
    framework: flask

  - name: "Staging API"
    type: url
    url: https://staging.example.com/openapi.json
    poll_interval: 300
    headers:
      Authorization: "Bearer ${STAGING_TOKEN}"

  - name: "Production API"
    type: url
    url: https://api.example.com/openapi.json
    poll_interval: 600

  - name: "Stripe API"
    type: url
    url: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
    poll_interval: 86400

server:
  port: 5678
```

**Source Types**: `local` (file watching) | `url` (HTTP polling)
**Environment Variables**: Use `${VAR}` syntax for secrets

## CLI Commands

| Command | Description |
|---------|-------------|
| `conciliate init` | Create config file |
| `conciliate mcp` | Run MCP server for AI assistants (recommended) |
| `conciliate watch` | Watch backend + serve REST API |
| `conciliate serve` | REST API only |
| `conciliate summary` | Display API summary |
| `conciliate diff` | Show recent contract changes |
| `conciliate status` | Show configuration and service status |

## VS Code Extension

### Features
- **Service Map**: Browse all microservices, their endpoints, and environments
- **Contract Issues**: Surface mismatches between code and API contracts
- **API Explorer**: Browse endpoints with method badges and full schema details
- **Changes View**: Real-time contract change tracking across all services
- **Search & Filter**: Find endpoints by path, method, or description
- **Code Generation**: Copy as cURL, TypeScript, or Python from any endpoint
- **Mock Server**: Generate fake API responses from contracts
- **Request Testing**: Postman-like interface to test endpoints directly

### Setup
1. Install VS Code extension from VSIX
2. Install Python package: `pip install conciliate`
3. Command Palette → `Conciliate: Initialize`
4. Edit `.conciliate.yaml` with your services
5. Command Palette → `Conciliate: Start`

## REST API

When running `conciliate watch` or `conciliate serve`:

| Endpoint | Description |
|----------|-------------|
| `GET /spec` | Full OpenAPI specification |
| `GET /summary` | Human-readable summary |
| `GET /diff` | Latest contract changes |
| `POST /reload` | Trigger spec regeneration |
| `GET /services` | List all services and status |
| `GET /services/{name}/endpoints` | Endpoints for a specific service |
| `POST /validate` | Validate a request against the contract |
| `GET /sources/aggregate` | Merged spec from all services |

## Roadmap

### Free Tier
- ✅ Auto-extraction from FastAPI, Flask, Express
- ✅ MCP server with live updates
- ✅ Multi-service registry (local + remote sources)
- ✅ Contract change detection and diff tracking
- ✅ VS Code extension (Service Map, API Explorer, Changes)
- ✅ Mock server mode
- ✅ Request validation against live contracts
- 🔜 Contract issue detection (mismatches between code and spec)
- 🔜 API-aware context budget optimization

### Pro Tier ($9-15/month)
- Enhanced AI diff narration (GPT-powered change descriptions)
- Cross-environment contract comparison
- Custom contract rules and policies

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Failed to generate spec" | Check `backend_path` in config, verify app file exists |
| "No .conciliate.yaml found" | Run `conciliate init` in your project directory |
| MCP not connecting | Restart AI assistant, verify `cwd` path in config |
| Framework not detected | Set `framework` explicitly in .conciliate.yaml |
| Extension not starting | Install Python package: `pip install conciliate` |

## License

MIT