Metadata-Version: 2.4
Name: api-contract-doctor
Version: 0.0.1
Summary: Validate OpenAPI (YAML/JSON) API contracts from the terminal.
Author: MAGESH ANAND U
License-Expression: MIT
Project-URL: Repository, https://github.com/mageshanand2007/api-contract-doctor
Keywords: openapi,swagger,yaml,validation,api,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: PyYAML>=6.0
Requires-Dist: openapi-spec-validator>=0.7.1
Dynamic: license-file

# API Contract Doctor

Validate [OpenAPI](https://www.openapis.org/) API contracts (YAML or JSON)
straight from your terminal, or via the bundled **MCP (Model Context
Protocol) server** for AI clients such as VS Code Copilot and Claude Desktop.

- Detects the contract version (`openapi: 3.0.x` / `3.1.x` / `swagger: 2.0`).
- Validates against the official OpenAPI schema using
  [`openapi-spec-validator`](https://github.com/python-openapi/openapi-spec-validator).
- Never crashes on bad input: missing files, YAML syntax errors, and
  non-object documents all come back as readable errors.

## Installation

```bash
pip install api-contract-doctor
```

Requires Python 3.9+.

## Command line interface

Check whether a contract file is valid:

```bash
api-contract-doctor validate contracts/sample.yaml
```

Valid contract:

```text
contracts/sample.yaml: VALID (OpenAPI 3.0.3, "Pet Store API")
```

Invalid contract (exit code 1):

```text
contracts/invalid_sample.yaml: INVALID
  1. 'version' is a required property (at $.info)
```

Examples in this README use files from the `contracts/` folder of this
repository.

## MCP server

The package also exposes a local MCP (Model Context Protocol) server that
lets AI clients validate contracts through the `validate_contract` tool.

Run it with:

```bash
python -m server
```

or, from a source checkout:

```bash
python server.py
```

The server starts and **prints nothing and just sits there** — that is
normal. It communicates over **stdio** (stdin/stdout) using the MCP
protocol, so it is designed to be launched by an MCP client, not typed at by
a human. Press `Ctrl+C` to stop it.

To verify the whole MCP round-trip (handshake + tool call) without a client:

```bash
python e2e_check.py
```

### Connect it to VS Code (Copilot agent mode)

VS Code (with GitHub Copilot in agent mode) reads MCP servers from
`.vscode/mcp.json`. Add this file to your workspace and reload VS Code:

```json
{
  "servers": {
    "api-contract-doctor": {
      "command": "${workspaceFolder}/.venv/Scripts/python.exe",
      "args": ["${workspaceFolder}/server.py"]
    }
  }
}
```

On macOS/Linux the interpreter path is
`${workspaceFolder}/.venv/bin/python` instead. After reloading, open Copilot
Chat in **agent mode**, and the `validate_contract` tool becomes available to
the model.

> A separate VS Code extension is bundled in this repository
> (`extension.js` + `package.json`), which registers the command
> "API Contract Doctor: Validate Contract". It reuses the exact same
> `tools.validator` logic through `validate_contract_cli.py` and can be
> packaged with `npx @vscode/vsce package`.

## Development

### Setup

```bash
python -m venv .venv
# Windows PowerShell:
.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate

pip install -r requirements.txt
```

### Build the Python package

```bash
pip install build
python -m build
python -m twine check dist/*
```

### Run the tests

```bash
python -m pytest tests -v
```

## Project structure

```text
api-contract-doctor/
├── cli.py                     # Command line entry point (validate command)
├── server.py                  # MCP server (stdio transport)
├── tools/
│   ├── __init__.py
│   └── validator.py           # OpenAPI validation logic (shared)
├── contracts/
│   ├── sample.yaml            # a VALID OpenAPI 3.0 contract
│   └── invalid_sample.yaml    # an intentionally BROKEN contract (for demos)
├── tests/
│   ├── test_validator.py      # pytest tests for the validator
│   └── test_cli.py            # pytest tests for the CLI
├── validate_contract_cli.py   # bridge used by the VS Code extension
├── extension.js               # VS Code extension (main)
├── package.json               # VS Code extension manifest
├── pyproject.toml             # Python package configuration
├── requirements.txt
├── LICENSE.md                 # MIT License
└── README.md
```

## How `validate_contract` works

1. Reads the file and parses it (JSON is tried first, then YAML, so both
   formats work).
2. Detects the contract version (`openapi` / `swagger`).
3. Validates the document against the official OpenAPI JSON Schema for that
   version.
4. Returns a structured result, e.g.:

```json
{
  "file": "contracts/invalid_sample.yaml",
  "valid": false,
  "openapi_version": "3.0.0",
  "title": "Broken API",
  "errors": [
    { "message": "'version' is a required property", "json_path": "$.info" }
  ]
}
```

Bad input never crashes: every failure mode is reported as `valid: false`
plus a human-readable entry in `errors`.

## License

[MIT](LICENSE.md)
