<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 the API
- Microservice and third-party APIs change silently
- No contract validation between AI-generated code and real APIs

## Features

- **Contract extraction**: Auto-generates OpenAPI specs from FastAPI, Flask, Express
- **Multi-service registry**: Track local microservices, staging, production, third-party APIs
- **Request validation**: Validate AI-generated requests against live contracts
- **MCP-native**: Built for Claude Desktop, Cursor, VS Code Copilot
- **Change detection**: Real-time diff tracking with AI-consumable narration
- **Local-first**: No cloud dependencies, runs entirely on your machine

## Quick Start

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

## 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 |

## MCP Tools

| Tool | Description |
|------|-------------|
| `list_services` | List all registered microservices |
| `list_endpoints` | List endpoints for a service |
| `validate_request` | Validate request against live contract |
| `explain_diff` | Explain API changes between environments |
| `search_endpoints` | Search across all services |
| `get_endpoint_details` | Get full schema for an endpoint |
| `reload_api_spec` | Force-reload specs |

## REST API

| 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 |
| `POST /validate` | Validate request against contract |

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Failed to generate spec" | Check `backend_path` in config |
| "No .conciliate.yaml found" | Run `conciliate init` |
| MCP not connecting | Restart AI assistant, verify `cwd` path |
| Framework not detected | Set `framework` explicitly in .conciliate.yaml |