# midos-mcp-sync

<!-- Badges -->
[![PyPI version](https://img.shields.io/pypi/v/midos-mcp-sync)](https://pypi.org/project/midos-mcp-sync/)
[![Python](https://img.shields.io/pypi/pyversions/midos-mcp-sync)](https://pypi.org/project/midos-mcp-sync/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Stop editing JSON files. Start building.**

Detect, validate, and synchronize MCP server configurations across all your AI tools — Claude Desktop, Cursor, VS Code Copilot, Windsurf, and more.

## The Problem

Using 2+ MCP clients? Every new MCP server means manually editing 3-6 separate config files in different locations and formats. Configs drift between machines and teammates. `midos-mcp-sync` fixes this.

## Install

```bash
pip install midos-mcp-sync
```

## Quick Start

```bash
# 1. Detect all MCP configs on your machine
midos-mcp-sync detect

# 2. Validate a config file
midos-mcp-sync validate

# 3. Preview what sync would change (dry-run by default)
midos-mcp-sync sync

# 4. Apply sync across all clients
midos-mcp-sync sync --apply
```

## Commands

### `detect` — Find all MCP configs

Auto-discovers configs from Claude Desktop, Cursor, VS Code Copilot, Windsurf, and project-level `.mcp.json` files.

```bash
midos-mcp-sync detect
midos-mcp-sync detect --project ./my-project
midos-mcp-sync detect --json
```

### `validate` — Check config correctness

Validates structure, server entries, transport types, and best practices.

```bash
midos-mcp-sync validate
midos-mcp-sync validate path/to/.mcp.json
```

### `sync` — Synchronize across clients

Merges all detected configs using union strategy. Conflicts resolved by newest-file-wins.

```bash
# Preview changes (dry-run, default behavior)
midos-mcp-sync sync
midos-mcp-sync sync --dry-run

# Apply changes
midos-mcp-sync sync --apply

# Output sync plan as JSON
midos-mcp-sync sync --json
```

### `diff` — Compare two configs

```bash
midos-mcp-sync diff config-a.json config-b.json
```

### `merge` — Combine configs

```bash
midos-mcp-sync merge base.json overlay.json
midos-mcp-sync merge base.json overlay.json -o merged.json
```

### `init` — Create template config

```bash
midos-mcp-sync init
midos-mcp-sync init path/to/.mcp.json
midos-mcp-sync init --force  # overwrite existing
```

### `export` — Export in different formats

```bash
midos-mcp-sync export .mcp.json --format json
midos-mcp-sync export .mcp.json --format yaml
```

### `list` / `register` — Local config registry

```bash
midos-mcp-sync register .mcp.json --name my-project
midos-mcp-sync list
```

## Supported Surfaces

| Client | Config Location | Status |
|--------|----------------|--------|
| Claude Desktop | `~/.config/claude/claude_desktop_config.json` | Detected |
| Cursor | `~/.cursor/mcp.json` | Detected |
| VS Code Copilot | `.vscode/settings.json` (mcp section) | Detected |
| Windsurf | `~/.windsurf/mcp.json` | Detected |
| Claude Code | `.mcp.json` (project root) | Detected |
| Custom | Any `.mcp.json` via register | Supported |

## How Sync Works

1. **Detect** all MCP configs across installed AI clients
2. **Merge** servers using union strategy (all servers from all configs)
3. **Resolve conflicts** — same server name with different settings: newest file wins
4. **Preview** changes in dry-run mode (default)
5. **Apply** writes the merged config back to each client's config file

## Optional Dependencies

```bash
# For YAML export support
pip install midos-mcp-sync[yaml]
```

YAML export works without `pyyaml` using a built-in minimal formatter.

## Development

```bash
git clone https://github.com/midos-community/midos-mcp-sync.git
cd midos-mcp-sync
pip install -e ".[dev]"
pytest
```

## License

MIT
