mcp-wizard-generators
Pluggable OpenAPI IR → MCP project generators for MCP Wizard.
PyPI / dist name: mcp-wizard-generators · Import: mcp_wizard_generators · Org: agentic-ai-tools (Trusted Publisher when configured)
This package is a library + CLI. It does not run HTTP servers or workers.
mcp-wizard-api owns jobs, entitlements, zip/GitHub delivery, and invokes this package offline.
Near-term slice: local + python — runnable Anthropic-style MCP server zip + Cursor config.
Also registered: agentcore + python scaffold (AgentCore deploy stubs; expand later).
Community
- License: MIT © 2026 Agentic AI Tools LLC
- Contributing: CONTRIBUTING.md
- Code of Conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
SDK choice (generated Python MCP)
Generated servers use the official MCP Python SDK (mcp on PyPI) 2.x:
| SDK line | High-level class | Import |
|---|---|---|
| 2.x (pinned) | MCPServer | from mcp.server.mcpserver import MCPServer |
| 1.x (legacy) | FastMCP | from mcp.server.fastmcp import FastMCP |
Fresh zips pin mcp>=2.0.0,<3 and import MCPServer (with an optional FastMCP fallback). Transport is stdio for Cursor local MCP. Upstream HTTP calls use httpx against API_BASE_URL. Generated READMEs include a short OS matrix for venv activate (bin vs Scripts, including Git Bash on Windows).
Layout
src/mcp_wizard_generators/
models.py # IntermediateRep, ToolMap, FileTree, GenerateContext
toolmap.py # IR ops → MCP tool names / JSON Schema inputs
pipeline.py # generate(): IR → tool map → rules hooks → plugin → tree
python_mcp.py # generate_python_mcp() — stable API for mcp-wizard-api
registry.py # Plugin registry keyed by (target, language)
cli.py # mcp-wizard-gen / python -m mcp_wizard_generators
packaging/ # zip helper for Artifact Service
plugins/python_mcp/ # Local Python MCP (stdio) emitter
plugins/agentcore/ # AWS Bedrock AgentCore scaffold (deploy stubs)
rules/ # Cursor + Anthropic hooks (not enforced in local slice)
tests/
fixtures/ # tiny pets OpenAPI + IR
goldens/ # expected file trees
How mcp-wizard-api should invoke this
Library (preferred in workers) — Python MCP zip
from pathlib import Path
from mcp_wizard_generators import generate_python_mcp
# Prefer this stable contract for the near-term generate slice:
workdir = Path("workdir") # or tempfile.mkdtemp() — avoid hard-coded /tmp on Windows
out = generate_python_mcp(
spec, # IntermediateRep | IR dict | {title, servers, ...}
operations=["listPets", "showPetById"], # ids — or list of simple op dicts
out_dir=workdir / "pets-mcp",
zip_path=workdir / "pets-mcp.zip", # optional
package_name="pets_tiny_mcp", # validated: ^[a-z][a-z0-9_]{0,62}$
# Experience API SecurityConfig JSON, or a SecurityConfig instance:
security={"authMode": "api_key", "apiKey": {"location": "header", "name": "X-API-Key"}},
# URL the OpenAPI document was fetched from (resolves relative servers):
source_url="https://petstore3.swagger.io/api/v3/openapi.json",
)
# out → Path(out_dir) if out_dir set, else Path(zip_path)
source_url (0.4.1): the http(s) URL the OpenAPI document was fetched from. Many specs
declare a relative server such as servers: [{url: "/api/v3"}], which OpenAPI defines as
relative to the document's location. With source_url set, relative server URLs resolve
against it (/api/v3 → https://petstore3.swagger.io/api/v3), so the generated
API_BASE_URL in .env.example and .cursor/mcp.json is absolute. Server {variables}
use their default values; a missing servers array means the document's origin, and a
Swagger 2 spec without host uses the document's host. Without source_url (for example an
uploaded file), relative URLs are kept as written and you set API_BASE_URL yourself.
Workers should always pass the import URL.
Untrusted specs (0.4.2): treat every OpenAPI document as hostile input. Generated code
escapes spec values (names, paths, titles, descriptions, server URLs) and never pastes them
into source as code. Parameter names become safe Python identifiers but keep their original
wire names, and path arguments are URL-encoded at runtime. File paths that would leave the
project (.., absolute, drive letters) raise ValueError, as do tool-name overrides that
aren't slugs and unknown HTTP methods. tests/test_generated_code_hardening.py covers this.
Hardened python-mcp output (0.5.0, ADR-023):
- Secret exposure:
operation_findings(spec)flags operations that send a secret where it can be logged, such as a password in the URL. A query or path parameter is medium severity, a cookie is low. The API uses the result to warn and untick those operations, and zips that include them getSECURITY-NOTES.md, a warning in the tool description, and afindingslist in the manifest. - Typed tools: each tool argument is
Annotated[<type>, Field(...)], withLiteralenums, numeric and length limits, patterns, and a description of where the value goes. Tools returnJsonValue. - Client:
API_BASE_URLand the auth settings are checked at startup.- One shared httpx client; redirects are not followed.
- Responses over
MAX_RESPONSE_BYTES(1 MiB by default) are refused. - Errors say what to check, and credentials in them are replaced with
***. - mcp 2.x only (no FastMCP fallback).
- Dependencies and tests: every zip includes a hash-pinned
requirements.lock, upper bounds on its dependencies, and atests/folder (tool regression, auth failures, HTTP status handling, redaction) that runs without network.
security (ADR-017): pass the session's saved SecurityConfig JSON as-is. Every mode is
honored in the generated client.py; invalid or unsupported settings raise ValueError
before anything is written (never a silent downgrade to no auth).
authMode |
Required fields | Generated behavior |
|---|---|---|
none |
— | No credentials (dev / public APIs only) |
api_key |
apiKey.location (header | query), apiKey.name |
Sends env API_KEY as that header or query param; fails if unset |
oauth2 |
oauth.tokenUrl (https); optional scopes, audience |
Client credentials grant with env OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET (HTTP Basic); caches the token, refreshes before expiry, retries once on 401; fails if credentials are unset |
mcpAuth: true and mtls are rejected: generated servers are stdio-only in MVP-1.
The CLI takes the same JSON via --security path/to/security.json.
The legacy auth_mode="none" keyword still works for the none mode.
package_name: must match ^[a-z][a-z0-9_]{0,62}$. Python keywords and a small denylist
(os, sys, mcp, …) are rejected. Invalid names raise before any tree/zip is written.
Reuse validate_package_name from this package if the API needs the same predicate.
operations semantics:
| Input | Behavior |
|---|---|
None / omit |
All IR operations (CLI convenience) |
| Non-empty ids / op dicts | Only those operations |
Explicit [] |
Raises ValueError (does not mean all) |
Hosted generate should always pass a non-empty id list.
Simple operations JSON (no full IR) is also accepted:
generate_python_mcp(
{"title": "Pets", "servers": ["https://petstore.example.com/v1"]},
operations=[
{
"operationId": "listPets",
"method": "get",
"path": "/pets",
"summary": "List all pets",
"params": [{"name": "limit", "type": "integer"}],
}
],
out_dir="out",
)
In-memory result (manifest / tool map / tree) without writing:
from mcp_wizard_generators import generate_python_mcp_result
result = generate_python_mcp_result(spec, operations=["listPets"])
zip_bytes = pack_file_tree_to_zip(result.tree) # from mcp_wizard_generators.packaging
Generic plugin pipeline
from mcp_wizard_generators import generate, IntermediateRep
from mcp_wizard_generators.packaging import pack_file_tree_to_zip
ir = IntermediateRep.from_dict(job_snapshot["ir"])
result = generate(
ir,
target=job_snapshot.get("targetArchitecture", "local"),
language=job_snapshot.get("language", "python"),
selected_operation_ids=job_snapshot["selectedOperationIds"],
tool_name_overrides=job_snapshot.get("toolNameOverrides"),
package_name="generated_mcp",
)
zip_bytes = pack_file_tree_to_zip(result.tree)
Pin a released version of this package from the API deployable / Lambda layer.
Do not vendor template trees inside mcp-wizard-api PRs (ADR-005).
CLI
Prefer relative output paths (portable on macOS and Windows). Full shell matrix: docs/local-dev.md.
# macOS / Linux / WSL / Git Bash
make bootstrap # or: sh scripts/bootstrap.sh
python -m mcp_wizard_generators list-targets
python -m mcp_wizard_generators generate-python \
--ir tests/fixtures/pets_tiny.ir.json \
--select listPets \
--select showPetById \
--package-name pets_tiny_mcp \
--out-dir .smoke-out \
--zip .smoke-out.zip
# Equivalent via generic generate (default target=local)
python -m mcp_wizard_generators generate \
--ir tests/fixtures/pets_tiny.ir.json \
--target local \
--language python \
--select listPets \
--select showPetById \
--out-dir .smoke-out \
--zip .smoke-out.zip \
--manifest .smoke-out/manifest.json
# Windows PowerShell
.\scripts\bootstrap.ps1
python -m mcp_wizard_generators generate-python `
--ir tests/fixtures/pets_tiny.ir.json `
--select listPets `
--select showPetById `
--package-name pets_tiny_mcp `
--out-dir .smoke-out `
--zip .smoke-out.zip
Console script (after install): mcp-wizard-gen … (Windows: .venv\Scripts\mcp-wizard-gen.exe).
Generated artifact (local Python MCP)
| Path | Purpose |
|---|---|
pyproject.toml / requirements.txt |
mcp + httpx deps |
README.md |
SDK choice, run + Cursor setup |
.env.example |
API_BASE_URL + auth env vars for the chosen mode (placeholders only, never secrets) |
.cursor/mcp.json |
Cursor MCP snippet (command/args/env) |
src/<pkg>/server.py |
FastMCP/MCPServer tools (1:1 with ops) |
src/<pkg>/client.py |
httpx → upstream API, applying the configured auth (API key / OAuth2 client credentials) |
src/<pkg>/__main__.py |
python -m <pkg> stdio entry |
src/<pkg>/verify.py |
python -m <pkg>.verify — tool count and metadata (<dist>-verify after install) |
generation-manifest.json |
tools + generator metadata |
Out of scope in this slice: AgentCore cloud deploy scaffolding, Agent Rules enforcement/embedding, non-Python languages, GitHub repo write delivery.
Tests & local scripts
make bootstrap && make test # or: sh scripts/test.sh
make lint # ruff (required before commit per AGENTS.md)
make dist # wheel + sdist → dist/
make cli-smoke # portable generate smoke
make e2e # install + stdio + tool call (needs network; not part of make test)
make tox # optional isolated envs
make e2e generates the pets server, installs it in a fresh virtualenv, starts it, and calls listpets through an MCP client. It needs network access and is not part of make test.
Windows PowerShell twins: .\scripts\bootstrap.ps1, .\scripts\test.ps1, .\scripts\e2e.ps1, .\scripts\dist.ps1, .\scripts\cli-smoke.ps1.
Details and the macOS / WSL / Git Bash / PowerShell matrix: docs/local-dev.md.
Golden coverage: tests/fixtures/pets_tiny.ir.json →
tests/goldens/python_mcp_pets_tiny/ (+ zip member assertions) for listPets + showPetById.
AgentCore scaffold golden remains under tests/goldens/agentcore_pets_tiny/.
Publish
Distribution name mcp-wizard-generators (import mcp_wizard_generators).
Publishing target: PyPI org agentic-ai-tools (OIDC Trusted Publisher stub in CI).
GitHub Packages does not support a Python/PyPI registry (roadmap closed as not planned).
Do not use *.pypi.pkg.github.com / upload.pypi.pkg.github.com — twine uploads fail with 404 or SSL hostname mismatch. There is no GitHub Packages PyPI upload workflow in this repo.
Install
Preferred (once the first PyPI release is live):
pip install mcp-wizard-generators
Interim (until that release): install from a git tag or a Release asset:
pip install git+https://github.com/agentic-ai-tools/mcp-wizard-generators.git@v0.3.0
Or download the wheel/sdist from the GitHub Release assets for that tag.
Local / sibling path (development):
pip install -e ../mcp-wizard-generators
# or pin a path/Compose mount via MCP_WIZARD_GENERATORS_PATH
Build wheel + sdist
make bootstrap # .[dev] includes build + twine + pytest-cov
make dist # → dist/mcp_wizard_generators-<version>-py3-none-any.whl (+ .tar.gz)
.\scripts\bootstrap.ps1
.\scripts\dist.ps1
CI quality gates
| Check | Workflow | Notes |
|---|---|---|
| Lint + tests + coverage + Semgrep | .github/workflows/ci.yml → reusable .github/workflows/quality.yml |
Coverage floor 80% (tool.coverage.report.fail_under); uploads XML/LCOV via codecov/codecov-action. Set CODECOV_TOKEN (or install the Codecov GitHub App). Push CI also covers release/**. |
| Semgrep (schedule / standalone) | .github/workflows/semgrep.yml |
Install the Semgrep GitHub App on the agentic-ai-tools org and/or set SEMGREP_APP_TOKEN. Uses official semgrep/semgrep + semgrep ci when the token is present; otherwise OSS rules with --error. |
PR CI does not require PyPI tokens. Publish runs the same quality.yml gate before any index upload.
Tag release (GitHub Release assets)
Push a SemVer git tag matching pyproject.toml (for example v0.3.0) to run
.github/workflows/publish-github-release.yml:
python -m buildtwine check- Attach
dist/*as GitHub Release assets (GITHUB_TOKEN)
workflow_dispatch is build + check only (no Release upload). Tags are for GitHub Release assets; PyPI channel publish is branch-based (below).
TestPyPI / PyPI (Trusted Publisher)
.github/workflows/publish-pypi.yml publishes with OIDC (pypa/gh-action-pypi-publish) — no TWINE_PASSWORD / API token secrets. Versions are computed by scripts/compute_pep440_version.py (PEP 440; no +local segments).
| Branch | PEP 440 form | Index |
|---|---|---|
Feature (anything except main / release/*) |
{base}.dev{N} developmental |
TestPyPI only |
Default main |
{base}rc{N} release candidate |
TestPyPI only |
release/X.Y.Z |
final X.Y.Z only |
TestPyPI then PyPI |
{base}is the static[project].versioninpyproject.toml(today0.5.0) for.dev/rcbuilds.- Feature
Ncombines a crc32 band of the normalized branch name withGITHUB_RUN_NUMBERso re-publishes get a new developmental version. mainusesN = GITHUB_RUN_NUMBER→{base}rc{N}.- Final releases: cut a branch named
release/X.Y.Z, withpyproject.tomlandsrc/mcp_wizard_generators/__init__.__version__equal to that exact public version; quality must pass, then the workflow uploads to TestPyPI and PyPI.
Triggers: push to any branch (skips dependabot[bot]) and workflow_dispatch. Quality must succeed before build/publish on every channel.
Trusted Publisher should be configured for project mcp-wizard-generators → this repo + publish-pypi.yml, with GitHub Environments testpypi and pypi.
OIDC upload is opt-in: set repository variable ENABLE_PYPI_PUBLISH=true only after Trusted Publisher claims match (workflow + environments). When unset, push still runs version → quality → build (dry-run) but skips upload so feature-branch PR checks stay green. Unset or set ENABLE_PYPI_PUBLISH=false to kill-switch publishing after it is enabled. No pull_request trigger on this workflow.
Non-goals (this repo)
- Experience API / HTTP / auth / billing
- Postgres / object storage
- Long-running MCP or wizard servers
- LangGraph (register later via the same plugin registry)
Metadata
Release files for mcp-wizard-generators 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_wizard_generators-0.5.0.tar.gz | 179.0 kB | With provenance | Details for mcp_wizard_generators-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_wizard_generators-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for mcp_wizard_generators-0.5.0-py3-none-any.whl |
Total release size: 269.5 kB
Release files / mcp_wizard_generators-0.5.0.tar.gz
| Download URL | mcp_wizard_generators-0.5.0.tar.gz |
|---|---|
| Size | 179.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1385440613554dc4c6b9bd8e8a156201eeb60282430cc3c2360d8b384b67bda9
|
|
BLAKE2b-256 checksum How to use checksums |
e7f74c558427bad0a207caf1b14d4b956dced90d5a0fd630c1ad353d89855e36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / mcp_wizard_generators-0.5.0-py3-none-any.whl
| Download URL | mcp_wizard_generators-0.5.0-py3-none-any.whl |
|---|---|
| Size | 90.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
43d8d5b12b96188cd126349cc6023a65c369a344bb5f9d5c59e34d0b1eb9b365
|
|
BLAKE2b-256 checksum How to use checksums |
9b3975631e9acb6ad861f4894eec2a04e080947b0dacf1f5adf846cbdc346b09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for mcp-wizard-generators 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mcp_wizard_generators-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.