fastapi-mcp-neo 0.13.0__tar.gz

fastapi_mcp_neo-0.13.0/.github/workflows/ci-skip.yml

@@ -0,0 +1,25 @@
+# Companion to ci.yml. The real CI is path-filtered, so a PR that changes
+# only non-code files (README, CHANGELOG, Comparison, etc.) skips ci.yml
+# entirely — leaving the required "CI All Green" check stuck in "Expected"
+# forever and blocking the PR. This workflow runs on the INVERSE path filter
+# and reports the same "CI All Green" check as passing, so such PRs can
+# merge. On a mixed PR both workflows run; both report green, and a real
+# failure still fails the same-named check, so nothing is masked.
+name: Test
+
+on:
+  pull_request:
+    paths-ignore:
+      - 'src/fastapi_mcp_neo/**'
+      - 'tests/**'
+      - 'examples/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+
+jobs:
+  ci-all-green:
+    name: CI All Green
+    runs-on: ubuntu-latest
+    steps:
+      - name: No code paths changed
+        run: echo "No code paths changed — real CI skipped; reporting green."

fastapi_mcp_neo-0.13.0/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: Test
+
+on:
+  pull_request:
+    paths:
+      - 'src/fastapi_mcp_neo/**'
+      - 'tests/**'
+      - 'examples/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+  push:
+    branches: [master]
+    paths:
+      - 'src/fastapi_mcp_neo/**'
+      - 'tests/**'
+      - 'examples/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      # One version failing must not cancel the others: a canceled job shows
+      # as failed even when its tests passed (observed: 3.13 finished green,
+      # then got canceled by 3.10's failure with fail-fast's default true).
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linter
+        run: uv run ruff check src tests
+
+      - name: Run type checker
+        run: uv run mypy src
+
+      - name: Test with pytest (coverage gate 95%)
+        run: |
+          uv run pytest tests/ -v --cov=fastapi_mcp_neo \
+            --cov-report=term-missing --cov-fail-under=95
+
+  # Guards the demo (and examples' syntax) against framework API drift. The
+  # demo is the framework's first real consumer; if a public API is renamed or
+  # removed, this job fails on the PR instead of shipping a demo that only
+  # breaks at run time. Critical: uv sync installs the WORKING-COPY framework
+  # (editable), so the demo is verified against the code in this PR — not the
+  # PyPI release. examples/notes_oauth is a standalone project with its own
+  # dependency set, so it is guarded here by compileall (syntax) and by
+  # tests/test_example_public_api.py in the test job (public-API-only imports).
+  demo-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install working-copy framework + extras
+        run: uv sync --all-extras
+
+      - name: Demo app builds against working-copy framework
+        run: |
+          uv run python -c "import examples.shop.app; print(f'demo builds: {len(examples.shop.app.app.routes)} routes')"
+
+      - name: Compile all example sources
+        run: uv run python -m compileall -q examples
+
+  # Single required-status gate. Branch protection should require this ONE
+  # check ("CI All Green") instead of each job (the matrix makes per-job names
+  # awkward). It aggregates the real jobs and fails if any did not succeed.
+  # A mirror job of the same name lives in ci-skip.yml: when a PR touches no
+  # code paths this workflow is skipped entirely, so the mirror reports the
+  # same check as green and docs-only PRs are never blocked on a check that
+  # path filtering skipped.
+  ci-all-green:
+    name: CI All Green
+    if: always()
+    needs: [test, demo-guard]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify required jobs succeeded
+        run: |
+          echo "test=${{ needs.test.result }} demo-guard=${{ needs.demo-guard.result }}"
+          [ "${{ needs.test.result }}" = "success" ] && [ "${{ needs.demo-guard.result }}" = "success" ]

fastapi_mcp_neo-0.13.0/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish to PyPI via uv
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # gh release create needs it; PyPI steps need only read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Build the package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_PUBLISHER }}
+
+      - name: Create the GitHub release from the CHANGELOG section
+        # Same tag, notes extracted from CHANGELOG.md — the release entry
+        # must never be forgotten again (0.9.0 shipped to PyPI with no
+        # Releases-page entry and looked like a failed release).
+        # Idempotent: a re-run skips creation when the entry already exists.
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            echo "release $GITHUB_REF_NAME already exists — skipping"
+            exit 0
+          fi
+          VERSION="${GITHUB_REF_NAME#v}"
+          awk -v header="## $VERSION " '
+            index($0, header) == 1 { found = 1; next }
+            found && /^## / { exit }
+            found { print }
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "no CHANGELOG section for $VERSION — falling back to tag annotation"
+            git tag -l --format='%(contents)' "$GITHUB_REF_NAME" > release-notes.md
+          fi
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file release-notes.md \
+            --latest

fastapi_mcp_neo-0.13.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+dist/
+.DS_Store
+.claude/
+
+# consumer example: local env + resolved lock stay untracked
+examples/*/.env
+examples/*/uv.lock
+examples/*/.venv/
+Comparison/bench/*/uv.lock
+.coverage
+
+# Claude Code project MCP servers (e.g. notes-demo on localhost:8020) —
+# environment-local dev convenience, not project config
+.mcp.json

fastapi_mcp_neo-0.13.0/AGENTS.md

@@ -0,0 +1,109 @@
+# Agent.md — release process and attention points
+
+Operating instructions for agents (and humans) releasing this repo.
+
+## Release flow
+
+Prerequisites: on `master`, in sync with origin, working tree clean, CI green
+(`gh run list`). The Unreleased section of `CHANGELOG.md` should carry the
+changes you are shipping.
+
+1. **Decide the version.** This repo is 0.x: breaking changes bump the minor
+   (0.1 → 0.2 → …), additive changes may too, fixes alone patch. Look at the
+   Unreleased entries: anything marked *(breaking)* forces a minor bump.
+2. **Bump the version in TWO places** — this is the classic miss:
+
+   | File | What to change |
+   |---|---|
+   | `pyproject.toml` | `version = "X.Y.Z"` (+ `uv lock` to refresh the self-entry) |
+   | `CHANGELOG.md` | `## Unreleased` → `## X.Y.Z (YYYY-MM-DD)` |
+
+   `__version__` needs NO hand-edit: since 0.6.0 it is **derived from
+   installed package metadata** (`importlib.metadata`), so pyproject is the
+   single source of truth. (0.5.0 shipped with a hardcoded `__version__`
+   still at 0.4.0 — the published package reported the wrong runtime
+   version; deriving removed that release step entirely.)
+   `tests/guards/test_version.py` fails the suite if `__version__` and pyproject
+   ever disagree again.
+
+   Verify before committing:
+
+   ```bash
+   grep '^version' pyproject.toml
+   uv run python -c "import fastapi_mcp_neo; print(fastapi_mcp_neo.__version__)"
+   # both must print the same X.Y.Z
+   ```
+
+3. **Commit**: `chore(release): X.Y.Z`, one-line summary of the wave.
+4. **Tag and push**:
+
+   ```bash
+   git tag vX.Y.Z
+   git push origin master vX.Y.Z
+   ```
+
+5. **Publish is automatic.** The `v*` tag triggers `.github/workflows/publish.yml`:
+   `uv build` → `uv publish` (token from the `PYPI_PUBLISHER` secret). No
+   GitHub Release is created — the CHANGELOG is the release notes. Watch it:
+
+   ```bash
+   gh run watch $(gh run list --workflow publish.yml --limit 1 --json databaseId -q '.[0].databaseId')
+   ```
+
+6. **Verify before announcing**:
+
+   ```bash
+   curl -s https://pypi.org/pypi/fastapi-mcp-neo/json | python3 -c \
+     "import sys,json; print(json.load(sys.stdin)['info']['version'])"
+   pip download fastapi-mcp-neo==X.Y.Z --no-deps -d /tmp/check && rm -rf /tmp/check
+   ```
+
+   Stronger check (used for 0.4.0): run the example off the published wheel —
+   from `examples/notes_oauth`, bypassing the editable source:
+
+   ```bash
+   OTEL_OTLP_ENDPOINT=http://localhost:4317 uv run --no-project \
+     --with 'fastapi-mcp-neo[mcp]==X.Y.Z' \
+     --with fastapi --with uvicorn --with python-dotenv --with asgi-lifespan \
+     --with opentelemetry-sdk --with opentelemetry-exporter-otlp \
+     python -c "import fastapi_mcp_neo; assert 'site-packages' in fastapi_mcp_neo.__file__; from app.__main__ import main; main()"
+   ```
+
+7. **After release**: new work goes under a fresh `## Unreleased` heading in
+   the CHANGELOG (Added / Fixed / Changed subsections).
+
+## Attention points
+
+- **Release only from `master`.** Feature branches merge (fast-forward when
+  linear) before any version bump.
+- **Test suite layers.** `tests/unit/` pins one module without handler
+  execution, `tests/integration/` goes through `RouterGraphQLHandler`,
+  `tests/e2e/` drives ASGI / fastmcp clients, `tests/guards/` holds meta
+  pins. Shared sample models, app factories, and protocol helpers live in
+  `tests/support/` — import via `from tests.support import apps, models`
+  (every directory keeps an `__init__.py`). New tests go where their
+  SUBJECT lives, not where the ticket came from; wave/ticket IDs belong in
+  docstrings, never in test names.
+- **The tag is the trigger.** Pushing the tag publishes to PyPI — a broken
+  release cannot be unpublished, only superseded by the next version. Never
+  move or delete a published tag.
+- **PyPI token**: `PYPI_PUBLISHER` in repo secrets. First release of a new
+  project name needs an account-wide token; afterwards rotate to a
+  project-scoped one. Also claim the project on PyPI after first publish.
+- **`__version__` consistency** is enforced by `tests/guards/test_version.py`
+  (derived from package metadata; pyproject is the single source) — the
+  wheel's runtime string must match the tag.
+- **CHANGELOG discipline**: entries land in Unreleased as they ship, not in
+  a batch at release time; each entry says *what changed and why*, breaking
+  changes are marked *(breaking)*.
+- **Commit hygiene**: conventional commits (`feat:`, `fix:`, `docs:`,
+  `chore(release):`); CHANGELOG hunks split into the commit they describe
+  when a release groups several commits.
+- **Coverage gate**: CI runs pytest with `--cov-fail-under=95` (baseline
+  96.7% after the layered-suite refactor); local `uv run pytest` stays
+  ungated for fast partial runs.
+- **Locks**: the repo-root `uv.lock` is committed; `examples/*` and
+  `comparison/bench/*` locks are ignored (they carry local path sources).
+- **Known trap**: port 8020 — check `lsof -nP -iTCP:8020 -sTCP:LISTEN`
+  before "the server won't start" debugging; yesterday's instance may still
+  be holding it (`python -c`-launched processes dodge `pkill -f "python -m app"`).