conciliate 0.7.1

Live API contract layer for AI coding assistants — keeps Claude, Cursor, and VS Code in sync with your real microservices

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

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
conciliate optimize <query>	Generate query-scoped context shard and token savings

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
optimize_context	Build query-scoped shard under token budget

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
GET /contract/issues	Detect cross-service contract mismatches
POST /context/optimize	Build query-scoped shard under token budget
GET /context/metrics	View token-savings optimization metrics

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