Quickstart

Install

For package usage:

pip install oas2mcp

For local development:

pdm install -G test -G docs -G cli

The cli group includes the in-memory LangGraph API server extras required for langgraph dev.

Environment

Copy the example env file and set the values you need:

cp .env.example .env

Required for the agent pipeline:

  • OPENAI_API_KEY

Optional for LangSmith tracing and LangGraph deployment:

  • LANGSMITH_TRACING=true

  • LANGSMITH_API_KEY

  • LANGSMITH_PROJECT

  • LANGSMITH_WORKSPACE_ID

  • LANGSMITH_DEPLOYMENT_NAME

  • LANGSMITH_ENDPOINT for self-hosted LangSmith only

Optional for live upstream FastMCP calls:

  • UPSTREAM_BEARER_TOKEN

  • UPSTREAM_API_KEY

  • UPSTREAM_API_KEY_HEADER

Test

pdm run pytest

Manual smoke checks

Formal coverage now lives in tests/. The scripts remain available for interactive inspection:

pdm run python scripts/test_catalog_surface_planner_agent.py
pdm run python scripts/test_orchestrator.py
pdm run python scripts/test_fastmcp_bootstrap.py
pdm run python scripts/test_fastmcp_server.py
pdm run python scripts/test_fastmcp_client.py

LangGraph deployment

The repository includes deployable graph entrypoints in src/oas2mcp/deploy/langgraph_app.py and a deployment config at config/langgraph.json.

Run the LangGraph CLI commands from the repository root so the config’s ./src and ./.env paths resolve correctly.

Install the CLI group:

pdm install -G cli

Run the LangGraph dev server locally:

pdm run langgraph dev --config config/langgraph.json --no-browser

The configured graphs are:

  • enhance_catalog for the in-memory summarize/enhance/surface-planning pipeline

  • enhance_and_export_catalog for the export pipeline that returns written artifact paths

Validate the deployment config:

pdm run langgraph validate --config config/langgraph.json

Build or deploy with the LangGraph CLI:

pdm run langgraph build --config config/langgraph.json -t oas2mcp
pdm run langgraph deploy --config config/langgraph.json

Release workflow

The publishing flow is tag-driven. The local helper cuts a verified release commit and annotated tag; the GitHub Actions release workflow then validates, builds, publishes to PyPI, and creates the GitHub Release.

Cut the next local release in one command:

pdm run release_cut_patch

You can replace patch with minor or major. The helper:

  • requires a clean worktree before starting

  • updates the tracked version files together

  • refreshes pdm.lock

  • runs pdm run release_check

  • creates the release commit

  • creates the annotated vX.Y.Z tag

Push the commit and tag explicitly after the helper succeeds:

git push origin main
git push origin vX.Y.Z

Pushing the tag triggers .github/workflows/release.yml, which:

  • verifies the tag matches pyproject.toml

  • runs tests

  • builds docs

  • builds distributions

  • publishes to PyPI

  • creates the GitHub Release and attaches dist/*