Metadata-Version: 2.4
Name: delimit-mcp
Version: 3.2.1
Summary: Unify Claude Code, Codex, Cursor, and Gemini CLI with persistent context, governance, and multi-model debate.
License: MIT
Project-URL: Homepage, https://delimit.ai
Project-URL: Repository, https://github.com/delimit-ai/delimit-gateway
Project-URL: Issues, https://github.com/delimit-ai/delimit-gateway/issues
Project-URL: Documentation, https://delimit.ai
Keywords: mcp,mcp-server,openapi,api,governance,breaking-changes,lint,diff,claude,cursor,codex,gemini,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: packaging>=23.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: google-api-python-client>=2.0; extra == "dev"
Requires-Dist: google-auth-oauthlib>=1.0; extra == "dev"
Dynamic: license-file

# Delimit MCP Server

**Unify Claude Code, Codex, Cursor, and Gemini CLI with persistent context, governance, and multi-model debate.**

API governance, persistent ledger, multi-model deliberation, security audit, and test verification — all shared across AI coding assistants.

[![CI](https://github.com/delimit-ai/delimit-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/delimit-ai/delimit-mcp-server/actions)
[![PyPI](https://img.shields.io/pypi/v/delimit-mcp)](https://pypi.org/project/delimit-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.0%2B-green)](https://www.openapis.org/)
[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Delimit-blue)](https://github.com/marketplace/actions/delimit-api-governance)

## Quick Install (10 seconds)

```yaml
- uses: delimit-ai/delimit-action@v0
```

## What Delimit Catches

```
Breaking Change Detected in Pull Request

+-------------+----------------------------------------+-----------------+
| Severity    | Change                                 | Location        |
+-------------+----------------------------------------+-----------------+
| HIGH        | Field removed: email                   | User schema     |
| HIGH        | Type changed: age (integer -> string)  | User.age        |
| HIGH        | Endpoint removed                       | GET /users/{id} |
+-------------+----------------------------------------+-----------------+
```

## Why Delimit

APIs evolve, but your consumers depend on stability. One accidental breaking change can cascade into hours of debugging and frustrated users. Delimit catches these changes before they reach production.

---

## Installation

### GitHub Action (CI)

Add this workflow to `.github/workflows/api-check.yml`:

```yaml
name: API Contract Check
on: pull_request

jobs:
  delimit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: delimit-ai/delimit-action@v0
```

Zero configuration required. Delimit auto-detects your OpenAPI specs.

> **No broken builds on day one** -- Delimit never fails on existing issues, only new violations in pull requests.

### CLI

```bash
npm install -g delimit-cli
delimit lint openapi.yaml
```

### MCP Server (for AI Assistants)

Install from PyPI:

```bash
pip install delimit-mcp
```

#### Claude Code / Claude Desktop

Add to your MCP config (`.mcp.json` or Claude Desktop settings):

```json
{
  "mcpServers": {
    "delimit": {
      "command": "delimit-mcp"
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "delimit": {
      "command": "delimit-mcp"
    }
  }
}
```

#### Codex CLI

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "delimit": {
      "command": "delimit-mcp"
    }
  }
}
```

The server communicates over stdio. No API keys or external services required.

---

## MCP Tools

| Tool | Description |
|------|-------------|
| `delimit_lint` | Diff + policy evaluation in one call. Returns pass/fail with violations. |
| `delimit_diff` | Structural diff between two OpenAPI specs. 23 change types detected. |
| `delimit_policy` | Evaluate changes against configurable rule sets. |
| `delimit_impact` | Business and technical impact assessment of detected changes. |
| `delimit_ledger` | Audit trail of governance decisions. |

Example agent usage:

```
> delimit_lint(old_spec="api/v1.yaml", new_spec="api/v2.yaml")

{
  "passed": false,
  "violations": [
    {"type": "endpoint_removed", "severity": "error", "path": "GET /users/{id}"},
    {"type": "field_removed", "severity": "error", "path": "User.email"}
  ],
  "summary": "2 breaking changes detected"
}
```

---

## Detected Breaking Changes

Delimit identifies 23 change types across these categories:

- **Removed endpoints** -- Endpoints that existed but are now gone
- **Type changes** -- Fields that changed type (string -> integer)
- **Removed required fields** -- Required response fields that were removed
- **New required parameters** -- Request parameters that became required
- **Method removals** -- HTTP methods removed from endpoints
- **Schema changes** -- Incompatible modifications to request/response schemas

> The action automatically compares your PR API spec against the base branch.

## What Happens on First Run

1. **Auto-detection** (2 seconds): Scans for OpenAPI/Swagger files
2. **Baseline creation** (3 seconds): Establishes current state without failing
3. **Analysis** (5 seconds): Compares changes and evaluates policies
4. **Feedback**: Posts clear, actionable comments on your PR

First run output:
```
Auto-detected: api/openapi.yaml
Baseline established
Running in advisory mode (non-blocking)
```

## Supports

- OpenAPI 3.0, 3.1
- Swagger 2.0
- Multiple specs in monorepos
- JSON and YAML formats

## Advanced Usage

### Configure Detection

If auto-detection does not work for your setup:

```yaml
- uses: delimit-ai/delimit-action@v1
  with:
    old_spec: api/v1/openapi.yaml
    new_spec: api/v2/openapi.yaml
    mode: enforce  # Fail CI on breaking changes
```

### Custom Policies

Create `.delimit/policies.yml` to define custom governance rules:

```yaml
rules:
  - id: no_endpoint_removal
    change_types: [endpoint_removed]
    severity: error
    message: "Endpoints cannot be removed without deprecation"
```

### Policy Presets

Three built-in presets:

| Preset | Behavior |
|--------|----------|
| `strict` | All detected changes are errors |
| `default` | Breaking changes are errors, others are warnings |
| `relaxed` | All changes are warnings only |

```bash
delimit lint --policy strict openapi.yaml
```

## Examples

| Example | Description | Key Learning |
|---------|-------------|--------------|
| [breaking-change-demo](examples/breaking-change-demo) | How Delimit catches breaking changes | Endpoint removal, field deletion |
| [safe-change-demo](examples/safe-change-demo) | Backward-compatible changes | Adding fields, new endpoints |
| [monorepo-demo](examples/monorepo-demo) | Multi-service API validation | Matrix builds, service isolation |

## Support

- [Documentation](https://github.com/delimit-ai/delimit)
- [Report Issues](https://github.com/delimit-ai/delimit/issues)
- [Discussions](https://github.com/delimit-ai/delimit/discussions)
- [Website](https://delimit.ai)

## License

MIT
