foxxe-mcp 0.3.0__tar.gz

foxxe_mcp-0.3.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.pytest_cache/

foxxe_mcp-0.3.0/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+Semver, honestly (PRD §7): transport or auth behaviour changes are **major**,
+new helpers **minor**, SDK patch bumps that change no foxxe-mcp behaviour
+**patch**. Every release records the exact SDK bound it pins.
+
+## v0.3.0 — 2026-09-04
+
+**First PyPI release.** `pip install foxxe-mcp==0.3.0`.
+
+**SDK bound** — unchanged: `mcp>=1.29.1,<2`, `fastmcp>=2.14,<3` (extra).
+
+**Changed**
+
+- Distribution moves from a git dependency pinned by tag to PyPI, amending
+  PRD §7. Found by the first real deploy: the repo is private, so a Docker
+  build cannot clone it (`git clone ... exit code: 128`) — and no fleet
+  Dockerfile has GitHub credentials. The alternatives were threading a PAT
+  through eleven Dockerfiles or making the repo public, which would publish
+  `fleet.toml` and the internal audit with it. PyPI keeps the repo private and
+  publishes only the package. NG3 rules out a *private* index; this is not one.
+- The sdist is an explicit allowlist (`src/`, README, CHANGELOG, LICENSE,
+  pyproject). `fleet.toml`, `docs/` and `scripts/` carry internal topology and
+  are deliberately not published.
+
+## v0.2.1 — 2026-09-04
+
+**SDK bound** — unchanged.
+
+**Fixed**
+
+- `setup_logging()` now takes sole ownership of the root handlers. The SDK
+  calls its own `configure_logging()` from the server constructor, so a plain
+  handler is already installed by the time `serve()` runs; adding a second one
+  made ainm emit every line twice — once bare, once JSON — doubling log volume
+  and leaving the JSON stream unparseable. Caught by booting the converted
+  pilot, not by the unit tests.
+
+## v0.2.0 — 2026-09-04
+
+Found by the ainm pilot, which is what a pilot is for.
+
+**SDK bound** — unchanged: `mcp>=1.29.1,<2`, `fastmcp>=2.14,<3` (extra).
+
+**Added**
+
+- `serve(mcp, app=...)` runs an app already built by `build_app()` instead of
+  building a second one. ainm's tests reach for a module-level `server.app`, so
+  the object has to exist at import time *and* be the one `__main__` runs;
+  without this, `python server.py` left an inert second session manager behind.
+  Passing `app=` together with `build_app` keyword arguments is a `TypeError`
+  rather than a silent ignore.
+
+## v0.1.0 — 2026-09-03
+
+First release. Extracted from the ainm bootstrap, which had the cleanest
+hand-rolled `server.py` in the fleet (PRD §8.1).
+
+**SDK bound**
+
+| name | bound | resolved in CI |
+|---|---|---|
+| `mcp` | `>=1.29.1,<2` | 1.29.1 |
+| `fastmcp` (extra) | `>=2.14,<3` | not installed by default |
+
+PRD OQ1 answered: **hold at `<2` for the first release.** The fleet is entirely
+pre-2.0, and converting the plumbing and the tool-definition API surface in one
+step would double the blast radius of the ainm pilot. The `MCPServer` *name* is
+exported now, so the v1.0 pin flip is a change to this library and to no server.
+Verified against `mcp==2.1.1` by `scripts/verify_sdk2.py`.
+
+The floor is 1.29.1 — the newest 1.x — deliberately above every floor in the
+audit (`1.6.0`, `1.25`, `1.26.0`, `1.28.1`). Four floors across six apps was the
+drift; one floor ends it.
+
+**Added**
+
+- `MCPServer` / `FastMCP` / `Context` / `Image` — unwrapped SDK re-exports under
+  a name stable across the 1.x→2.x rename (`_sdk`).
+- `serve()` and `build_app()` — transport selection, Fly bind conventions,
+  allowed-host handling, lifespan wrapping, graceful shutdown.
+- `/health` (dependency-free) and `/version` → `{server, foxxe_mcp, sdk}`.
+- `check_sdk()` — boot-time enforcement of the bound on **both** names, which is
+  the only place the transitive `fastmcp` → `mcp>=2` case (PRD finding B) can be
+  caught.
+- `BearerAuthMiddleware` — pure-ASGI, probes exempt.
+- `ToolError`, `error_envelope()`, `error_json()`, `failing_to_json()`.
+- `setup_logging()` — JSON lines, level and format from env.
+- `taisce_fetch()` — service-token key reveal, never logs the value.
+- `sentinel_push()` — opt-in, fire-and-forget, cannot raise into the caller.
+- `foxxe-herd` — fleet drift report and herd redeploy (PRD §8.5, §11).
+
+**Open questions answered**
+
+- **OQ1** — hold at `<2`; export the 2.x name. See above.
+- **OQ2** — bearer only. The SDK already implements the OAuth resource-server
+  model and three servers pass `auth_server_provider=` / `auth=AuthSettings(...)`
+  to the constructor; `serve()` carries those through untouched. Reimplementing
+  OAuth here would be NG2 in a different costume and would leave two
+  implementations to reconcile instead of one.
+- **OQ3** — `sentinel_push()` is **opt-in**, off unless `SENTINEL_URL` is set. A
+  shared library that starts emitting to a central collector the moment it is
+  installed is a surprise, and a fleet migration is the worst moment for one.
+
+Still open: **OQ4** (`git_create_repo` in git-mcp) and **OQ5** (mnemos' duplicate
+root `requirements.txt` declaration) are fleet questions, not library ones.

foxxe_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Todd McCaffrey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

foxxe_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: foxxe-mcp
+Version: 0.3.0
+Summary: Shared MCP plumbing for the FoxxeLabs server fleet: one SDK pin, one bootstrap, thin re-export.
+Project-URL: Homepage, https://github.com/todd427/foxxe-mcp
+Author: Todd McCaffrey
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp<2,>=1.29.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: starlette>=0.36.0
+Requires-Dist: uvicorn>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp<3,>=2.14; extra == 'fastmcp'
+Description-Content-Type: text/markdown
+
+# foxxe-mcp
+
+Shared MCP plumbing for the FoxxeLabs server fleet. One SDK pin, one bootstrap, thin re-export of the SDK server class — so a spec revision is one commit here, not eleven latent crash-loops.
+
+See [docs/PRD-foxxe-mcp.md](docs/PRD-foxxe-mcp.md) for why. See [docs/migration.md](docs/migration.md) for how to convert a server.
+
+**Status:** v0.1.0 — library built, fleet unmigrated.
+
+## The shape
+
+```python
+from foxxe_mcp import MCPServer, serve
+
+mcp = MCPServer("tomhas")
+
+@mcp.tool()
+def status() -> str:
+    """Report the current run state."""
+    ...
+
+if __name__ == "__main__":
+    serve(mcp)
+```
+
+`MCPServer` is the SDK's own class, re-exported unwrapped. The tool decorator is
+the SDK's, reached through the instance — foxxe-mcp never wraps the registration
+API (PRD NG2), so every SDK feature is available the day it ships.
+
+`serve()` owns what eleven servers currently hand-roll: transport, bind address,
+allowed host, `/health`, `/version`, logging, graceful shutdown.
+
+## Why the name is `MCPServer` on an SDK that calls it `FastMCP`
+
+v0.1 pins `mcp>=1.29.1,<2`, where the class is `FastMCP`. The export is named
+`MCPServer` anyway — that is the mcp 2.x name, and exporting it now means the
+eventual pin flip changes this library and no server code at all.
+
+That is a claim, so it is tested: `scripts/verify_sdk2.py` runs the same library
+against `mcp==2.1.1` and checks that `MCPServer` resolves to the renamed class,
+that a tool still registers, and that `/health`, `/version` and `/mcp` all still
+answer. Both majors, one codebase.
+
+```
+$ python scripts/verify_sdk2.py
+foxxe-mcp 0.1.0 against mcp 2.1.1
+  PASS  SDK major detected as 2 — mcp.server.mcpserver
+  PASS  MCPServer resolves to the renamed class
+  ...
+All checks passed — the v1.0 pin flip is a one-line change.
+```
+
+## The bound is enforced twice
+
+Once at install time, in `pyproject.toml`, and again at boot, in `check_sdk()`.
+The second one is not redundant. PRD finding B: rialu declares no `mcp` at all,
+only an unbounded `fastmcp`, and `fastmcp` 3.x pulls `mcp>=2` transitively — a
+declaration that binds only at install time cannot catch what a resolver did to
+a *transitive* dependency. `serve()` calls `check_sdk()` before the first tool
+call, so a wrong resolution fails at boot, next to its cause.
+
+`mcp` out of range is fatal. `fastmcp` out of range warns, and is fatal under
+`FOXXE_MCP_STRICT_SDK=1`.
+
+## Install
+
+```
+foxxe-mcp==0.3.0
+```
+
+Add the `fastmcp` extra only if the server actually uses the third-party
+`fastmcp` package: `foxxe-mcp[fastmcp]==0.3.0`. Never declare `mcp` or
+`fastmcp` directly in a server again — that is the whole point.
+
+Published to PyPI rather than installed as a git dependency, which is a
+deliberate amendment to PRD §7. The git-by-tag plan died on contact with the
+first real deploy: this repo is private, so `pip install git+https://...`
+inside a Docker build has no credentials and fails with exit 128. The
+alternatives were a build-time PAT threaded through eleven Dockerfiles, or
+making the repo public — which would publish `fleet.toml` and the internal
+audit along with it. PyPI keeps the repo private, publishes only the package,
+and makes every Dockerfile a plain `pip install` again. NG3 rules out a
+*private* index; this is the public one.
+
+## Fleet operations
+
+```
+foxxe-herd status              # poll every server's /version — who is on what
+foxxe-herd redeploy            # dry run
+foxxe-herd redeploy --yes      # fly deploy every migrated server
+```
+
+`fleet.toml` maps server name to Fly app name (verified against `flyer
+apps_list`, not guessed — the `-foxxelabs` suffix is inconsistent) and records
+which servers are migrated and which are still unbounded.
+
+## Environment
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `PORT` | `8080` | Port to bind |
+| `BIND_HOST` | `0.0.0.0` | Bind address (Fly requires all interfaces) |
+| `ALLOWED_HOST` | `$FLY_APP_NAME.fly.dev` | Public hostname for DNS-rebinding protection — **not** the bind address |
+| `MCP_TRANSPORT` | `http` | `http` or `stdio` |
+| `LOG_LEVEL` | `INFO` | Root log level |
+| `LOG_FORMAT` | `json` | `text` for human-readable |
+| `MCP_BEARER_TOKENS` | unset | Comma-separated; presence enables bearer auth |
+| `FOXXE_MCP_STRICT_SDK` | unset | `1` makes an out-of-range `fastmcp` fatal |
+| `TAISCE_SERVICE_TOKEN` | unset | Service token for `taisce_fetch()` |
+| `SENTINEL_URL` | unset | Presence enables `sentinel_push()` |
+
+## Development
+
+```
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest
+```

foxxe_mcp-0.3.0/README.md

@@ -0,0 +1,116 @@
+# foxxe-mcp
+
+Shared MCP plumbing for the FoxxeLabs server fleet. One SDK pin, one bootstrap, thin re-export of the SDK server class — so a spec revision is one commit here, not eleven latent crash-loops.
+
+See [docs/PRD-foxxe-mcp.md](docs/PRD-foxxe-mcp.md) for why. See [docs/migration.md](docs/migration.md) for how to convert a server.
+
+**Status:** v0.1.0 — library built, fleet unmigrated.
+
+## The shape
+
+```python
+from foxxe_mcp import MCPServer, serve
+
+mcp = MCPServer("tomhas")
+
+@mcp.tool()
+def status() -> str:
+    """Report the current run state."""
+    ...
+
+if __name__ == "__main__":
+    serve(mcp)
+```
+
+`MCPServer` is the SDK's own class, re-exported unwrapped. The tool decorator is
+the SDK's, reached through the instance — foxxe-mcp never wraps the registration
+API (PRD NG2), so every SDK feature is available the day it ships.
+
+`serve()` owns what eleven servers currently hand-roll: transport, bind address,
+allowed host, `/health`, `/version`, logging, graceful shutdown.
+
+## Why the name is `MCPServer` on an SDK that calls it `FastMCP`
+
+v0.1 pins `mcp>=1.29.1,<2`, where the class is `FastMCP`. The export is named
+`MCPServer` anyway — that is the mcp 2.x name, and exporting it now means the
+eventual pin flip changes this library and no server code at all.
+
+That is a claim, so it is tested: `scripts/verify_sdk2.py` runs the same library
+against `mcp==2.1.1` and checks that `MCPServer` resolves to the renamed class,
+that a tool still registers, and that `/health`, `/version` and `/mcp` all still
+answer. Both majors, one codebase.
+
+```
+$ python scripts/verify_sdk2.py
+foxxe-mcp 0.1.0 against mcp 2.1.1
+  PASS  SDK major detected as 2 — mcp.server.mcpserver
+  PASS  MCPServer resolves to the renamed class
+  ...
+All checks passed — the v1.0 pin flip is a one-line change.
+```
+
+## The bound is enforced twice
+
+Once at install time, in `pyproject.toml`, and again at boot, in `check_sdk()`.
+The second one is not redundant. PRD finding B: rialu declares no `mcp` at all,
+only an unbounded `fastmcp`, and `fastmcp` 3.x pulls `mcp>=2` transitively — a
+declaration that binds only at install time cannot catch what a resolver did to
+a *transitive* dependency. `serve()` calls `check_sdk()` before the first tool
+call, so a wrong resolution fails at boot, next to its cause.
+
+`mcp` out of range is fatal. `fastmcp` out of range warns, and is fatal under
+`FOXXE_MCP_STRICT_SDK=1`.
+
+## Install
+
+```
+foxxe-mcp==0.3.0
+```
+
+Add the `fastmcp` extra only if the server actually uses the third-party
+`fastmcp` package: `foxxe-mcp[fastmcp]==0.3.0`. Never declare `mcp` or
+`fastmcp` directly in a server again — that is the whole point.
+
+Published to PyPI rather than installed as a git dependency, which is a
+deliberate amendment to PRD §7. The git-by-tag plan died on contact with the
+first real deploy: this repo is private, so `pip install git+https://...`
+inside a Docker build has no credentials and fails with exit 128. The
+alternatives were a build-time PAT threaded through eleven Dockerfiles, or
+making the repo public — which would publish `fleet.toml` and the internal
+audit along with it. PyPI keeps the repo private, publishes only the package,
+and makes every Dockerfile a plain `pip install` again. NG3 rules out a
+*private* index; this is the public one.
+
+## Fleet operations
+
+```
+foxxe-herd status              # poll every server's /version — who is on what
+foxxe-herd redeploy            # dry run
+foxxe-herd redeploy --yes      # fly deploy every migrated server
+```
+
+`fleet.toml` maps server name to Fly app name (verified against `flyer
+apps_list`, not guessed — the `-foxxelabs` suffix is inconsistent) and records
+which servers are migrated and which are still unbounded.
+
+## Environment
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `PORT` | `8080` | Port to bind |
+| `BIND_HOST` | `0.0.0.0` | Bind address (Fly requires all interfaces) |
+| `ALLOWED_HOST` | `$FLY_APP_NAME.fly.dev` | Public hostname for DNS-rebinding protection — **not** the bind address |
+| `MCP_TRANSPORT` | `http` | `http` or `stdio` |
+| `LOG_LEVEL` | `INFO` | Root log level |
+| `LOG_FORMAT` | `json` | `text` for human-readable |
+| `MCP_BEARER_TOKENS` | unset | Comma-separated; presence enables bearer auth |
+| `FOXXE_MCP_STRICT_SDK` | unset | `1` makes an out-of-range `fastmcp` fatal |
+| `TAISCE_SERVICE_TOKEN` | unset | Service token for `taisce_fetch()` |
+| `SENTINEL_URL` | unset | Presence enables `sentinel_push()` |
+
+## Development
+
+```
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest
+```

foxxe_mcp-0.3.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "foxxe-mcp"
+version = "0.3.0"
+description = "Shared MCP plumbing for the FoxxeLabs server fleet: one SDK pin, one bootstrap, thin re-export."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Todd McCaffrey" }]
+
+# ── The fleet's single SDK pin (PRD G1) ──────────────────────────────────────
+# This is the ONLY place in the fleet that may depend on `mcp` or `fastmcp`.
+# v0.1 holds at the 1.x API surface (PRD OQ1): the fleet is entirely pre-2.0,
+# and converting plumbing and the tool-definition API in one step would double
+# the blast radius of the ainm pilot. `foxxe_mcp.MCPServer` already exports the
+# 2.x *name*, so the v1.0 pin flip is a lib bump, not a fleet-wide edit.
+dependencies = [
+    "mcp>=1.29.1,<2",
+    "starlette>=0.36.0",
+    "uvicorn>=0.27.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+# PRD finding B: bounding one name is insufficient — rialu declares no `mcp` at
+# all, only unbounded `fastmcp`, and fastmcp 3.x pulls mcp>=2 transitively.
+# A server that needs the third-party fastmcp takes it from HERE, bounded, and
+# `foxxe_mcp.check_sdk()` enforces the bound at runtime whether or not the
+# resolver honoured it.
+fastmcp = ["fastmcp>=2.14,<3"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/todd427/foxxe-mcp"
+
+[project.scripts]
+foxxe-herd = "foxxe_mcp.herd:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/foxxe_mcp"]
+
+# The repo is private and the package is public, so the sdist is an explicit
+# allowlist rather than "everything not gitignored". fleet.toml, docs/ and
+# scripts/ carry internal topology — Fly app names, which servers are broken,
+# the audit — and must not be published.
+[tool.hatch.build.targets.sdist]
+include = ["src/foxxe_mcp", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

foxxe_mcp-0.3.0/src/foxxe_mcp/__init__.py

@@ -0,0 +1,86 @@
+"""foxxe-mcp — shared MCP plumbing for the FoxxeLabs fleet.
+
+A choke point, not a framework (PRD §5). A server reads as if it were written
+directly against the SDK, with two differences: the import comes from
+``foxxe_mcp``, and ``serve()`` replaces the hand-rolled transport wiring::
+
+    from foxxe_mcp import MCPServer, serve
+
+    mcp = MCPServer("tomhas")
+
+    @mcp.tool()
+    def status() -> str:
+        ...
+
+    if __name__ == "__main__":
+        serve(mcp)
+
+``MCPServer`` is the SDK's own class, re-exported unwrapped. The tool
+decorator is the SDK's, reached through the instance — foxxe-mcp never wraps
+the registration API (NG2), so every SDK feature is available the day it ships,
+with no wrapper lag.
+
+The name ``MCPServer`` is the mcp 2.x name, exported regardless of which SDK
+major is installed. On the current 1.x pin it is ``FastMCP`` underneath. That
+is the whole trick: when the fleet moves to 2.x, the pin changes here and
+server code does not change at all.
+"""
+
+from __future__ import annotations
+
+from ._sdk import (
+    FASTMCP_VERSION,
+    SDK_MAJOR,
+    SDK_MODULE,
+    SDK_VERSION,
+    Context,
+    FastMCP,
+    Image,
+    MCPServer,
+    SdkReport,
+    check_sdk,
+)
+from .auth import BearerAuthMiddleware, tokens_from_env
+from .errors import ToolError, error_envelope, error_json, failing_to_json
+from .health import health_route, version_payload, version_route
+from .logging import setup_logging
+from .secrets import TaisceError, taisce_fetch
+from .serve import build_app, resolve_allowed_host, resolve_bind, serve
+from .telemetry import sentinel_enabled, sentinel_push
+from .version import __version__
+
+__all__ = [
+    # ── SDK re-exports (unwrapped) ──────────────────────────────────────────
+    "MCPServer",
+    "FastMCP",
+    "Context",
+    "Image",
+    # ── Bootstrap (PRD G2) ──────────────────────────────────────────────────
+    "serve",
+    "build_app",
+    "resolve_bind",
+    "resolve_allowed_host",
+    # ── Shared plumbing (PRD G3) ────────────────────────────────────────────
+    "BearerAuthMiddleware",
+    "tokens_from_env",
+    "ToolError",
+    "error_envelope",
+    "error_json",
+    "failing_to_json",
+    "setup_logging",
+    "taisce_fetch",
+    "TaisceError",
+    "sentinel_push",
+    "sentinel_enabled",
+    "health_route",
+    "version_route",
+    "version_payload",
+    # ── Drift visibility (PRD G4) ───────────────────────────────────────────
+    "__version__",
+    "SDK_VERSION",
+    "SDK_MAJOR",
+    "SDK_MODULE",
+    "FASTMCP_VERSION",
+    "SdkReport",
+    "check_sdk",
+]