pydantic-mcp
# pydantic-mcp
`pydantic-mcp` is an MCP server for inspecting Pydantic models and Python type contracts. It is built for LLM workflows that need deterministic validation, serialization, schema generation, model explanations, and migration help.
## Features
- Discover Pydantic `BaseModel` classes across configured packages.
- Resolve targets from import paths, short model names, Python type expressions, or inline model snippets.
- Validate arbitrary payloads with `TypeAdapter` or model behavior.
- Serialize validated data in Python or JSON mode.
- Generate validation and serialization JSON Schema.
- Explain fields, defaults, aliases, decorators, constraints, and nested models.
- Generate valid and invalid example payloads.
- Infer candidate Pydantic models from sample JSON payloads.
- Compare strict/non-strict and Python-vs-JSON validation behavior.
- Analyze common Pydantic v1 to v2 migration issues.
- Parse partial JSON with `pydantic_core.from_json`.
- Expose MCP tools, resources, prompts, plus HTTP health/readiness routes.
## Tools
- `list_models`
- `inspect_type`
- `explain_model`
- `validate_data`
- `serialize_data`
- `generate_json_schema`
- `create_example_payload`
- `generate_model_from_json`
- `compare_validation_modes`
- `migrate_v1_to_v2`
- `parse_partial_json`
## Resources
- `pydantic://server/capabilities`
- `pydantic://project/settings`
- `pydantic://project/import-roots`
- `pydantic://project/errors/recent`
- `pydantic://project/models/changed`
- `pydantic://models/index`
- `pydantic://models/{qualified_name}`
- `pydantic://schemas/{qualified_name}?mode=validation|serialization`
- `pydantic://examples/{qualified_name}`
- `pydantic://migration/rules`
- `pydantic://reference/overview`
## Prompts
- `explain model`
- `generate api contract docs`
- `debug validation error`
- `design a model from example json`
- `review schema compatibility`
- `migrate to pydantic v2`
## Run
Install dependencies:
```bash
uv sync
```
Run over stdio:
```bash
uv run python mcp_server.py --transport stdio
```
Run over HTTP:
```bash
uv run python mcp_server.py --transport http --host 127.0.0.1 --port 8000
```
Health endpoints:
- `GET /healthz`
- `GET /readyz`
## Configuration
Important environment variables:
- `PYDANTIC_MCP_ALLOWED_IMPORT_ROOTS`
- `PYDANTIC_MCP_DEFAULT_SCAN_PACKAGES`
- `PYDANTIC_MCP_IMPORT_TIMEOUT_SECONDS`
- `PYDANTIC_MCP_ERROR_HISTORY_LIMIT`
- `PYDANTIC_MCP_TRANSPORT`
- `PYDANTIC_MCP_HOST`
- `PYDANTIC_MCP_PORT`
Example:
```bash
PYDANTIC_MCP_ALLOWED_IMPORT_ROOTS=your_app.models \
PYDANTIC_MCP_DEFAULT_SCAN_PACKAGES=your_app.models \
uv run python mcp_server.py --transport stdio
```
These values must point at importable application packages in the runtime environment. For local smoke tests, the repository ships an installable sample package at `pydantic_mcp_sample_app`, but production deployments should point at your own application modules.
## Testing
```bash
just test
```
TDQS
Scored across 11 tools
Each tool has a clearly distinct purpose with no overlap: compare_validation_modes analyzes validation behavior differences, create_example_payload generates test data, explain_model creates human-readable documentation, generate_json_schema produces JSON Schema, generate_model_from_json infers models from JSON, inspect_type resolves type annotations, list_models discovers available models, migrate_v1_to_v2 handles version migration, parse_partial_json processes incomplete JSON, serialize_data handles data serialization, and validate_data performs validation. The descriptions clearly differentiate their specific functions.
The naming follows a consistent verb_noun pattern throughout (e.g., compare_validation_modes, create_example_payload, explain_model) with all tools using snake_case. The only minor deviation is that 'list_models' uses a plural noun while others typically use singular nouns (e.g., 'explain_model'), but this is a small inconsistency that doesn't affect readability or predictability.
With 11 tools, this is well-scoped for a Pydantic-focused server. Each tool serves a distinct purpose in the Pydantic ecosystem (validation, schema generation, migration, serialization, etc.), and none feel redundant or unnecessary. The count aligns perfectly with providing comprehensive coverage for working with Pydantic models and validation.
The tool surface provides complete coverage for Pydantic operations: it includes model discovery (list_models), type inspection (inspect_type), schema generation (generate_json_schema), validation (validate_data, compare_validation_modes), serialization (serialize_data), migration support (migrate_v1_to_v2), example generation (create_example_payload), documentation (explain_model), and even specialized utilities like parsing partial JSON (parse_partial_json) and model inference (generate_model_from_json). No obvious gaps exist for typical Pydantic workflows.