conciliate 0.2.0

AI context synchronization and propagation between dev environments

Unified context for smarter AI decisions.

Conciliate automatically extracts API specifications from your backend, detects changes, and streams context to AI coding assistants in real-time. Keep your AI in sync across separate IDE sessions—no more manual copy-pasting.

Features

• Auto-extraction: Monitors backend files, generates OpenAPI specs automatically
• Live updates: Real-time synchronization via MCP protocol
• Three access modes: MCP server, REST API, or CLI
• Framework support: FastAPI (Flask, Express coming soon)
• AI-native: Built for Claude Desktop, Cursor, VS Code Copilot
• Local-first: No cloud dependencies, runs entirely on your machine

Quick Start

Install

pip install conciliate

Setup

cd /path/to/your/project
conciliate init
# Edit .conciliate.yaml to set backend_path

Run

conciliate mcp      # For AI assistants (recommended)
conciliate watch    # REST API + file watching
conciliate serve    # REST API only

CLI Commands

Command	Description
conciliate init	Create config file
conciliate watch	Watch backend + serve REST API
conciliate mcp	Run MCP server for AI assistants
conciliate summary	Display API summary
conciliate diff	Show recent changes
conciliate status	Show configuration

Configuration

Create .conciliate.yaml in your project root:

backend_path: ../backend    # Path to your backend
framework: fastapi          # Backend framework (auto-detected if omitted)
port: 5678                  # Server port
output_dir: .conciliate     # Output directory

Copy from .conciliate.yaml.template for all available options.

� MCP Integration (AI Assistants)

Claude Desktop

Edit claude_desktop_config.json:

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

VS Code

Create .vscode/mcp.json:

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

Then: Restart your AI assistant → Ask: "What API endpoints are available?"

Features

• 📚 Resources: Full spec, summaries, diffs
• 🛠️ Tools: Reload, search, get endpoint details
• ⚡ Live Updates: Auto-detects backend changes, no manual reload
• 🎯 Cross-session: Keep frontend/backend AI assistants synchronized

Full guide: docs/MCP_INTEGRATION.md

� REST API

When running conciliate watch or conciliate serve:

Endpoint	Description
GET /spec	Full OpenAPI specification
GET /summary	Human-readable summary
GET /diff	Latest changes
POST /reload	Trigger spec regeneration

🧪 Example

# Start example backend
cd example/backend && python main.py

# In another terminal
cd ../.. && conciliate init
# Edit .conciliate.yaml: backend_path: ./example/backend

conciliate watch
# Visit http://localhost:5678/summary

🔮 Roadmap

• v0.1.0 ✅ Core engine (watcher, spec gen, diff, REST API)
• v0.2.0 ✅ MCP integration with live updates
• v0.3.0 - VS Code extension (status bar, API explorer, inline docs)
• v0.4.0 - Multi-backend support (microservices, aggregated specs)
• v0.5.0 - Flask/Express framework support

Troubleshooting

Issue	Solution
"Failed to generate spec"	Check backend_path in config, verify FastAPI app exists
"No .conciliate.yaml found"	Run conciliate init in your project directory
MCP not connecting	Restart AI assistant, verify cwd path in config

See full troubleshooting guide in docs/.

License

MIT License - see LICENSE for details.