mcp-server-kit 0.1.0__tar.gz

mcp_server_kit-0.1.0/.forgejo/workflows/security-gate.yml

@@ -0,0 +1,29 @@
+# Secret scan on every push and PR: the public snickery/secret-gate action. A
+# short ref, so it resolves through the forge's DEFAULT_ACTIONS_URL (GitHub)
+# and this public repo's workflow carries no instance hostname.
+name: security-gate
+
+on:
+  push:
+  pull_request:
+
+# Never cancel: Forgejo otherwise cancels a branch's queued runs of this
+# workflow when a newer push lands, and each run scans only its own push, so a
+# cancelled run is an unscanned push. (forgejo-ci-watch rescans any that are.)
+concurrency:
+  cancel-in-progress: false
+
+jobs:
+  secret-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (full history for diff range)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Secret scan
+        uses: snickery/secret-gate@v1
+        with:
+          base: ${{ github.event.pull_request.base.sha || github.event.before }}
+          head: ${{ github.event.pull_request.head.sha || github.sha }}

mcp_server_kit-0.1.0/.forgejo/workflows/tests.yml

@@ -0,0 +1,30 @@
+# Unit-test job: runs the pytest suite on every push/PR. Identical across the
+# first-party MCP repos.
+# Credential-free by design: integration/live tests self-skip without their
+# env vars — never add secrets here. Python = .python-version, else 3.13
+# (the Containerfile base). Forgejo ignores .github/workflows while
+# .forgejo/workflows exists, so this is the one that runs on the forge.
+name: tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv + Python
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          py="$(cat .python-version 2>/dev/null || echo 3.13)"
+          echo "UV_PYTHON=$py" >> "$GITHUB_ENV"
+          "$HOME/.local/bin/uv" python install "$py"
+
+      - name: pytest
+        run: uv run --isolated --frozen --extra test python -m pytest -q

mcp_server_kit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --frozen --extra test
+      - run: uv run pytest tests/ -q

mcp_server_kit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+# Publishes via PyPI Trusted Publishing (OIDC) — no stored token.
+# Fires on a published GitHub release, or manually via workflow_dispatch.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish

mcp_server_kit-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.secrets.env
+dist/

mcp_server_kit-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

mcp_server_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Engel
+
+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.

mcp_server_kit-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: mcp-server-kit
+Version: 0.1.0
+Summary: Shared plumbing for FastMCP servers: bearer auth, off-event-loop sync tools with per-call logging, stdio/HTTP serving, and a liveness probe
+Project-URL: Homepage, https://github.com/snickery/mcp-server-kit
+Project-URL: Issues, https://github.com/snickery/mcp-server-kit/issues
+Author-email: Nick Engel <nick@engel.au>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auth,fastmcp,mcp,model-context-protocol,server
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.0
+Requires-Dist: mcp[cli]<2,>=1.0.0
+Requires-Dist: uvicorn>=0.32.0
+Provides-Extra: pdf
+Requires-Dist: httpx>=0.27; extra == 'pdf'
+Requires-Dist: pdfplumber>=0.11; extra == 'pdf'
+Requires-Dist: pillow>=10.0; extra == 'pdf'
+Requires-Dist: pypdfium2>=4.30; extra == 'pdf'
+Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
+Requires-Dist: httpx>=0.27.0; extra == 'test'
+Requires-Dist: pdfplumber>=0.11; extra == 'test'
+Requires-Dist: pillow>=10.0; extra == 'test'
+Requires-Dist: pypdfium2>=4.30; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mcp-server-kit
+
+Shared plumbing for Python MCP servers built on the official SDK's FastMCP
+(`mcp.server.fastmcp`). It covers the parts every server ends up copying:
+
+| Module | What it does |
+|---|---|
+| `offload_sync_tools` | Registers each **sync** tool as an async wrapper that runs the body in a worker thread, so one blocking upstream call can't freeze every other request. The SDK runs sync handlers inline on the event loop. Signatures, and so input schemas, are unchanged. Every call, sync or async, logs one `tool=… outcome=… duration_ms=… rss_mib=…` line. |
+| `BearerAuthMiddleware` | Pure ASGI bearer-token gate (timing-safe compare, streaming-safe). Only `/.well-known/` discovery paths are exempt, matched by prefix, never by substring. |
+| `serve` | `--stdio` runs stdio. Otherwise it serves Streamable HTTP at `/mcp` behind the bearer gate, and **refuses to start without a token**. |
+| `healthcheck.probe` | A liveness probe for containers: a full HTTP round-trip to `/mcp`, where the 401 counts as alive. Pair it with restart-on-unhealthy so a wedged loop heals itself. |
+| `files` | Collision-safe staging for a directory several servers share: bare names only, never overwrite (`-2`, `-3`, … before the extension, `O_CREAT\|O_EXCL`), `sha256` of every transfer. `atomic_create` writes bytes; `exclusive_open` hands a streaming writer the fd. |
+| `pdf` (extra `[pdf]`) | PDF text extraction (pdfplumber text / layout / tables), page rendering (pypdfium2), and OCR through an [xberg](https://github.com/xberg-io/xberg) server (tesseract, or a vision model for hard pages). Configured by `XBERG_*` env vars; the PDF libraries load lazily. |
+
+## Install
+
+```bash
+uv add mcp-server-kit        # or: pip install mcp-server-kit
+```
+
+It pins `mcp>=1,<2`, so the SDK range lives in one place for every server built on the kit.
+
+## Use
+
+```python
+import logging
+import os
+
+from mcp.server.fastmcp import FastMCP
+from mcp_server_kit import offload_sync_tools, serve
+
+mcp = FastMCP("example", instructions="...", stateless_http=True, json_response=True)
+offload_sync_tools(mcp, logger_name="example_mcp.requests")   # before the first @mcp.tool()
+
+
+@mcp.tool()
+def lookup(query: str) -> str:
+    """A blocking call is fine here: it runs in a worker thread."""
+    ...
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO)
+    serve(mcp, port=8000, bearer_token=os.environ.get("MCP_BEARER_TOKEN", ""))
+```
+
+`lookup` stays a plain function, so tests and other tools can call it directly.
+
+To give every tool the same annotations unless it passes its own:
+`offload_sync_tools(mcp, logger_name=..., default_annotations=ToolAnnotations(readOnlyHint=True))`.
+
+Healthcheck module for a container (`HealthCmd=python -m example_mcp.healthcheck`):
+
+```python
+from mcp_server_kit.healthcheck import probe
+
+def main() -> None:
+    probe(8000)
+
+if __name__ == "__main__":
+    main()
+```
+
+Shared non-thread-safe clients (e.g. cached `httplib2` objects) need a lock in the
+server. Thread-safe ones (`httpx.Client`, `requests.Session`) don't.
+
+## Develop
+
+```bash
+uv sync --extra test
+uv run pytest -q
+```
+
+MIT licensed.

mcp_server_kit-0.1.0/README.md

@@ -0,0 +1,74 @@
+# mcp-server-kit
+
+Shared plumbing for Python MCP servers built on the official SDK's FastMCP
+(`mcp.server.fastmcp`). It covers the parts every server ends up copying:
+
+| Module | What it does |
+|---|---|
+| `offload_sync_tools` | Registers each **sync** tool as an async wrapper that runs the body in a worker thread, so one blocking upstream call can't freeze every other request. The SDK runs sync handlers inline on the event loop. Signatures, and so input schemas, are unchanged. Every call, sync or async, logs one `tool=… outcome=… duration_ms=… rss_mib=…` line. |
+| `BearerAuthMiddleware` | Pure ASGI bearer-token gate (timing-safe compare, streaming-safe). Only `/.well-known/` discovery paths are exempt, matched by prefix, never by substring. |
+| `serve` | `--stdio` runs stdio. Otherwise it serves Streamable HTTP at `/mcp` behind the bearer gate, and **refuses to start without a token**. |
+| `healthcheck.probe` | A liveness probe for containers: a full HTTP round-trip to `/mcp`, where the 401 counts as alive. Pair it with restart-on-unhealthy so a wedged loop heals itself. |
+| `files` | Collision-safe staging for a directory several servers share: bare names only, never overwrite (`-2`, `-3`, … before the extension, `O_CREAT\|O_EXCL`), `sha256` of every transfer. `atomic_create` writes bytes; `exclusive_open` hands a streaming writer the fd. |
+| `pdf` (extra `[pdf]`) | PDF text extraction (pdfplumber text / layout / tables), page rendering (pypdfium2), and OCR through an [xberg](https://github.com/xberg-io/xberg) server (tesseract, or a vision model for hard pages). Configured by `XBERG_*` env vars; the PDF libraries load lazily. |
+
+## Install
+
+```bash
+uv add mcp-server-kit        # or: pip install mcp-server-kit
+```
+
+It pins `mcp>=1,<2`, so the SDK range lives in one place for every server built on the kit.
+
+## Use
+
+```python
+import logging
+import os
+
+from mcp.server.fastmcp import FastMCP
+from mcp_server_kit import offload_sync_tools, serve
+
+mcp = FastMCP("example", instructions="...", stateless_http=True, json_response=True)
+offload_sync_tools(mcp, logger_name="example_mcp.requests")   # before the first @mcp.tool()
+
+
+@mcp.tool()
+def lookup(query: str) -> str:
+    """A blocking call is fine here: it runs in a worker thread."""
+    ...
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO)
+    serve(mcp, port=8000, bearer_token=os.environ.get("MCP_BEARER_TOKEN", ""))
+```
+
+`lookup` stays a plain function, so tests and other tools can call it directly.
+
+To give every tool the same annotations unless it passes its own:
+`offload_sync_tools(mcp, logger_name=..., default_annotations=ToolAnnotations(readOnlyHint=True))`.
+
+Healthcheck module for a container (`HealthCmd=python -m example_mcp.healthcheck`):
+
+```python
+from mcp_server_kit.healthcheck import probe
+
+def main() -> None:
+    probe(8000)
+
+if __name__ == "__main__":
+    main()
+```
+
+Shared non-thread-safe clients (e.g. cached `httplib2` objects) need a lock in the
+server. Thread-safe ones (`httpx.Client`, `requests.Session`) don't.
+
+## Develop
+
+```bash
+uv sync --extra test
+uv run pytest -q
+```
+
+MIT licensed.

mcp_server_kit-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "mcp-server-kit"
+version = "0.1.0"
+description = "Shared plumbing for FastMCP servers: bearer auth, off-event-loop sync tools with per-call logging, stdio/HTTP serving, and a liveness probe"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Nick Engel", email = "nick@engel.au" }]
+requires-python = ">=3.12"
+keywords = ["mcp", "model-context-protocol", "fastmcp", "server", "auth"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: AsyncIO",
+]
+dependencies = [
+    # The kit owns the SDK range for every server built on it. <2: mcp 2.0
+    # moved FastMCP out of mcp.server.fastmcp; moving to 2.x is a kit release.
+    "mcp[cli]>=1.0.0,<2",
+    "anyio>=4.0",
+    "uvicorn>=0.32.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/snickery/mcp-server-kit"
+Issues = "https://github.com/snickery/mcp-server-kit/issues"
+
+[project.optional-dependencies]
+# mcp_server_kit.pdf: native text (pdfplumber), page rasterising (pypdfium2 + pillow),
+# OCR through an xberg server over httpx. Imported lazily, only on a PDF call.
+pdf = ["pdfplumber>=0.11", "pypdfium2>=4.30", "pillow>=10.0", "httpx>=0.27"]
+test = ["pytest>=8.0", "httpx>=0.27.0", "mcp-server-kit[pdf]"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_server_kit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mcp_server_kit-0.1.0/src/mcp_server_kit/__init__.py

@@ -0,0 +1,9 @@
+"""Shared plumbing for FastMCP servers: bearer auth, off-loop tools, serving, healthcheck,
+collision-safe file staging (`files`) and PDF reading (`pdf`, extra `[pdf]`)."""
+
+from mcp_server_kit.auth import BearerAuthMiddleware
+from mcp_server_kit.serve import serve
+from mcp_server_kit.tools import offload_sync_tools, request_logger, rss_mib
+
+__all__ = ["BearerAuthMiddleware", "offload_sync_tools", "request_logger", "rss_mib", "serve"]
+__version__ = "0.1.0"

mcp_server_kit-0.1.0/src/mcp_server_kit/auth.py

@@ -0,0 +1,48 @@
+"""Bearer-token gate for a Streamable HTTP MCP app."""
+
+import hmac
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+_LOOPBACK = ("127.0.0.1", "::1")
+
+
+class BearerAuthMiddleware:
+    """Pure ASGI bearer-token middleware (streaming-safe, timing-safe compare).
+
+    Every HTTP/websocket request needs `Authorization: Bearer <expected_token>`,
+    except `/.well-known/` discovery paths. That exemption is a prefix match on
+    purpose: a substring match would become an auth bypass the moment the app
+    routes anything under /mcp. Rejections get a JSON 401. A loopback request
+    with no credentials (a liveness probe) is logged at debug; anything else is
+    a warning. The token itself is never logged.
+    """
+
+    def __init__(self, app, expected_token: str):
+        if not expected_token:
+            raise ValueError("BearerAuthMiddleware needs a non-empty token")
+        self.app = app
+        self.expected_token = expected_token
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] not in ("http", "websocket"):
+            return await self.app(scope, receive, send)
+        if scope.get("path", "").startswith("/.well-known/"):
+            return await self.app(scope, receive, send)
+        auth = dict(scope.get("headers", [])).get(b"authorization", b"").decode()
+        if auth.startswith("Bearer ") and hmac.compare_digest(auth[7:], self.expected_token):
+            return await self.app(scope, receive, send)
+
+        client_host = (scope.get("client") or ("unknown",))[0]
+        if client_host in _LOOPBACK and not auth:
+            logger.debug("Health probe 401 (loopback, no credentials, expected)")
+        else:
+            logger.warning("Rejected request: invalid or missing bearer token from %s", client_host)
+        body = json.dumps({"error": "unauthorized"}).encode()
+        await send({"type": "http.response.start", "status": 401, "headers": [
+            [b"content-type", b"application/json"],
+            [b"content-length", str(len(body)).encode()],
+        ]})
+        await send({"type": "http.response.body", "body": body})

mcp_server_kit-0.1.0/src/mcp_server_kit/files.py

@@ -0,0 +1,62 @@
+"""Collision-safe file staging, e.g. a directory shared by several MCP servers.
+
+Servers that hand files to each other through a shared directory (one writes
+`shared:<name>`, another reads it) need identical semantics, or a file staged
+by one isn't where the other looks: bare filenames only, never overwrite, and
+on a collision append -2, -3, ... before the extension. Creation uses
+O_CREAT|O_EXCL, so parallel writers in different processes can't clobber each
+other. Every transfer reports the sha256 of the bytes, so the caller can verify
+a handoff in-band.
+"""
+
+import hashlib
+import os
+from pathlib import Path
+
+MAX_SUFFIX = 1000
+
+
+class NoFreeNameError(RuntimeError):
+    """Every candidate name up to -MAX_SUFFIX already exists."""
+
+
+def sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def require_bare(name: str, what: str = "filename") -> str:
+    """`name`, if it is a bare filename (no directory part, not . or ..); else ValueError."""
+    if not name or name != os.path.basename(name) or name in (".", ".."):
+        raise ValueError(f"Invalid {what} {name!r} — must be a bare filename.")
+    return name
+
+
+def exclusive_open(root: Path, filename: str, mode: int = 0o644) -> tuple[Path, int]:
+    """Create a new file under `root` and return (path, fd) open for writing.
+
+    Tries `filename`, then `<stem>-2<ext>`, `<stem>-3<ext>`, ... `filename` must already
+    be bare (see require_bare). For streaming writers; `atomic_create` writes bytes.
+    """
+    root = Path(root)
+    root.mkdir(parents=True, exist_ok=True)
+    stem, ext = os.path.splitext(filename)
+    for i in range(MAX_SUFFIX + 1):
+        candidate = root / (filename if i == 0 else f"{stem}-{i + 1}{ext}")
+        try:
+            return candidate, os.open(candidate, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+        except FileExistsError:
+            continue
+    raise NoFreeNameError(f"No free filename for {filename!r} in {root} (tried -{MAX_SUFFIX}).")
+
+
+def atomic_create(root: Path, filename: str, data: bytes) -> Path:
+    """Write `data` to a new file under `root` (see exclusive_open) and return its path.
+    A failed write removes the partial file."""
+    path, fd = exclusive_open(root, filename)
+    try:
+        with os.fdopen(fd, "wb") as fp:
+            fp.write(data)
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+    return path

mcp_server_kit-0.1.0/src/mcp_server_kit/healthcheck.py

@@ -0,0 +1,29 @@
+"""Container liveness probe for a kit-served MCP server.
+
+A full HTTP round-trip to /mcp within a short timeout proves the event loop is
+alive. The bearer middleware's 401 to this unauthenticated loopback probe is a
+completed response and counts as healthy. A transport failure or timeout exits
+non-zero, so a restart-on-unhealthy policy (Podman `HealthOnFailure=kill`)
+self-heals a wedged loop. Wire it from the server's own module:
+
+    # <package>/healthcheck.py
+    from mcp_server_kit.healthcheck import probe
+    from <package>.config import PORT
+
+    def main() -> None:
+        probe(PORT)
+"""
+
+import sys
+import urllib.error
+import urllib.request
+
+
+def probe(port: int, timeout: float = 5) -> None:
+    try:
+        urllib.request.urlopen(f"http://127.0.0.1:{port}/mcp", timeout=timeout)
+    except urllib.error.HTTPError:
+        return
+    except Exception as exc:  # noqa: BLE001 - any transport failure = unhealthy
+        print(f"health: unreachable on :{port}: {exc}", file=sys.stderr)
+        sys.exit(1)