fastmcp-creds 0.1.0__tar.gz

fastmcp_creds-0.1.0/.gitattributes

@@ -0,0 +1,10 @@
+# Store and check out text files as LF on every platform, overriding a local
+# core.autocrlf=true that would otherwise produce phantom EOL-only diffs.
+# text=auto leaves detected binaries untouched; eol=lf pins the *working tree*.
+* text=auto eol=lf
+
+# cmd.exe reads batch files by byte offset, so LF-only endings break labels
+# and goto. Do NOT add *.ps1 here: PowerShell is cross-platform, and CRLF
+# breaks the shebang of a .ps1 meant to run on Linux/macOS.
+*.bat text eol=crlf
+*.cmd text eol=crlf

fastmcp_creds-0.1.0/.github/workflows/publish-test.yml

@@ -0,0 +1,40 @@
+name: Publish to TestPyPI
+on:
+  workflow_dispatch:
+
+jobs:
+  test-pypi-publish:
+    name: Upload to TestPyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # For PyPI's trusted publishing
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build
+        run: uv build
+
+      - name: Check version format
+        run: |
+          # Extract version from the built package
+          VERSION=$(ls dist/*.whl | head -n1 | sed -E 's/.*-([0-9].*)-.*/\1/')
+          echo "Package version: $VERSION"
+
+          # Check if version contains dev/post markers (development version)
+          if [[ "$VERSION" =~ (dev|post.*dev) ]]; then
+            echo "❌ ERROR: Cannot publish development version: $VERSION"
+            echo "Please create a proper Git tag first (e.g., 'git tag v0.1.0')"
+            exit 1
+          fi
+
+          echo "✅ Version $VERSION is valid for publishing"
+
+      - name: Publish to TestPyPI
+        run: uv publish --publish-url https://test.pypi.org/legacy/ -v dist/*

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

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Upload to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # For PyPI's trusted publishing
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build
+        run: uv build
+
+      - name: Check version format
+        run: |
+          # Extract version from the built package
+          VERSION=$(ls dist/*.whl | head -n1 | sed -E 's/.*-([0-9].*)-.*/\1/')
+          echo "Package version: $VERSION"
+
+          # Check if version contains dev/post markers (development version)
+          if [[ "$VERSION" =~ (dev|post.*dev) ]]; then
+            echo "❌ ERROR: Cannot publish development version: $VERSION"
+            echo "Please create a proper Git tag first (e.g., 'git tag v0.1.0')"
+            exit 1
+          fi
+
+          echo "✅ Version $VERSION is valid for publishing"
+
+      - name: Publish to PyPI
+        run: uv publish -v dist/*

fastmcp_creds-0.1.0/.github/workflows/run-static.yml

@@ -0,0 +1,58 @@
+name: Run static analysis
+
+env:
+  # Enable colored output
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+
+  # Run on all pull requests because these checks are required and will block merges otherwise
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  static_analysis:
+    timeout-minutes: 2
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Check lockfile is up to date
+        run: |
+          if ! uv lock --check; then
+            echo "❌ Lockfile is out of date!"
+            echo "To update the lockfile, run 'uv lock'."
+            exit 1
+          fi
+          echo "✅ Lockfile is up to date"
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Check formatting
+        run: uv run ruff format --check src tests
+
+      - name: Type checking
+        run: uv run ty check src

fastmcp_creds-0.1.0/.github/workflows/run-tests.yml

@@ -0,0 +1,51 @@
+name: Run tests
+
+env:
+  # Enable colored output
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+
+  # Run on all pull requests because these checks are required and will block merges otherwise
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  run_tests:
+    name: "Run tests: Python ${{ matrix.python-version }} on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10"]
+      fail-fast: false
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        # Run with frozen to use the current lockfile; static checks will determine if it needs updating
+        run: uv sync --frozen
+
+      - name: Run tests
+        run: uv run pytest

fastmcp_creds-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv/
+
+# Log files
+*.log
+
+# Coverage reports
+.coverage
+htmlcov/
+.pytest_cache/
+
+# VSCode settings
+.vscode/PythonImportHelper-v2-Completion.json
+
+# Claude Code local settings (tool permissions, personal overrides — not shared)
+.claude/settings.local.json

fastmcp_creds-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+fail_fast: false
+
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.1.0
+    hooks:
+      - id: prettier
+        types_or: [yaml, json]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.15.12
+    hooks:
+      # Run the linter.
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      # Run the formatter.
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty check
+        entry: uv run ty check
+        language: system
+        types: [python]
+        files: ^src/|^tests/
+        pass_filenames: false
+        require_serial: true
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell # See pyproject.toml for args
+        additional_dependencies:
+          - tomli

fastmcp_creds-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing <!-- omit in toc -->
+
+Thank you for your interest in contributing to `fastmcp-creds`! This document
+provides guidelines for setting up a development environment, making changes,
+and testing them locally before pushing to GitHub.
+
+- [Development Setup](#development-setup)
+  - [Prerequisites](#prerequisites)
+  - [Clone and install](#clone-and-install)
+- [Code Quality](#code-quality)
+  - [Enable automatic execution on git commit](#enable-automatic-execution-on-git-commit)
+  - [Manual execution](#manual-execution)
+- [Testing](#testing)
+- [Release Process](#release-process)
+  - [Testing a release first](#testing-a-release-first)
+- [Building Packages Locally](#building-packages-locally)
+- [Dependency Management](#dependency-management)
+
+## Development Setup
+
+### Prerequisites
+
+- [Python 3.10](https://www.python.org/downloads) or later
+- [uv](https://docs.astral.sh/uv/) — fast Python package manager
+
+### Clone and install
+
+```bash
+git clone https://github.com/stephaneberle9/fastmcp-creds.git
+cd fastmcp-creds
+uv sync
+```
+
+## Code Quality
+
+This project uses `pre-commit` hooks for static checks to maintain high code
+quality standards:
+
+| Hook | Purpose |
+| ---- | ------- |
+| `ruff-check` | Python linting (with auto-fix) |
+| `ruff-format` | Python code formatting |
+
+### Enable automatic execution on git commit
+
+```bash
+uv run pre-commit install
+```
+
+### Manual execution
+
+```bash
+# Run all checks on all files
+uv run pre-commit run --all-files
+
+# Run individual tools
+uv run ruff format src tests      # Code formatting
+uv run ruff check --fix src tests # Linting with auto-fix
+uv run ty check src               # Type checking
+```
+
+## Testing
+
+```bash
+# Run all tests with coverage
+uv run pytest
+
+# Run a specific test file
+uv run pytest tests/test_chain.py
+
+# Run with verbose output
+uv run pytest -v
+
+# Show only a coverage summary (skip HTML report)
+uv run pytest --cov-report=term-missing --no-cov-on-fail
+```
+
+Coverage is collected from `src/fastmcp_creds` and an HTML report is written
+to `htmlcov/`.
+
+## Release Process
+
+1. Ensure all changes are committed and the `main` branch is up to date.
+
+2. Create and push a version tag:
+
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+3. Create a GitHub release from the tag and add release notes. The
+   `publish.yml` workflow triggers automatically and uploads the package to
+   PyPI.
+
+The package version is derived automatically from the git tag by
+[uv-dynamic-versioning](https://github.com/nicoddemus/uv-dynamic-versioning).
+
+### Testing a release first
+
+To publish to TestPyPI before a real release, trigger the `publish-test.yml`
+workflow manually from the **Actions** tab on GitHub (select **Run workflow**).
+
+## Building Packages Locally
+
+```bash
+uv build
+ls dist/
+```
+
+This produces both a wheel (`.whl`) and a source distribution (`.tar.gz`).
+
+## Dependency Management
+
+Dependencies are pinned in `uv.lock` for reproducible installs. After adding or
+changing dependencies in `pyproject.toml`:
+
+```bash
+uv lock        # update the lockfile
+uv sync        # sync your environment to the new lockfile
+```
+
+> [!IMPORTANT]
+> Always commit both `pyproject.toml` and `uv.lock` together.

fastmcp_creds-0.1.0/LICENSE

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

fastmcp_creds-0.1.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.5
+Name: fastmcp-creds
+Version: 0.1.0
+Summary: Credential provider chain for FastMCP servers: keyring, environment variables, and HTTP Basic Auth header providers with unresolved placeholder detection.
+Project-URL: Homepage, https://github.com/stephaneberle9/fastmcp-creds
+Project-URL: Repository, https://github.com/stephaneberle9/fastmcp-creds
+Project-URL: Issues, https://github.com/stephaneberle9/fastmcp-creds/issues
+Author-email: Stephan Eberle <stephaneberle9@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: credchain>=0.1.0
+Requires-Dist: fastmcp<5,>=4.0.0
+Provides-Extra: keyring
+Requires-Dist: credchain[keyring]; extra == 'keyring'
+Description-Content-Type: text/markdown
+
+# fastmcp-creds <!-- omit in toc -->
+
+Pluggable credential management for FastMCP servers — supply API tokens or
+username/password credentials for the backend services they connect to, from
+environment variables, OS keychain, or HTTP headers, with automatic fallback
+through a priority chain.
+
+The framework-neutral parts — the chain and the environment and keychain
+providers — live in [credchain](https://github.com/stephaneberle9/python-credchain)
+and are re-exported here unchanged, so existing imports keep working. This
+package adds the providers that read FastMCP's HTTP request headers.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Credential provider chain](#credential-provider-chain)
+  - [Environment variables](#environment-variables)
+  - [HTTP Basic Auth header](#http-basic-auth-header)
+  - [Custom HTTP headers](#custom-http-headers)
+  - [OS keychain](#os-keychain)
+- [API Reference](#api-reference)
+  - [`CredentialsProvider`](#credentialsprovider)
+  - [`CredentialsProviderChain`](#credentialsproviderchain)
+  - [`EnvironmentCredentialsProvider`](#environmentcredentialsprovider)
+  - [`BasicAuthCredentialsProvider`](#basicauthcredentialsprovider)
+  - [`CustomHeaderCredentialsProvider`](#customheadercredentialsprovider)
+  - [`KeyringCredentialsProvider`](#keyringcredentialsprovider)
+  - [`BasicAuthError`](#basicautherror)
+  - [`is_unresolved_placeholder_value`](#is_unresolved_placeholder_value)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+```bash
+pip install fastmcp-creds
+# or, with uv:
+uv add fastmcp-creds
+```
+
+The `KeyringCredentialsProvider` requires the optional `keyring` extra:
+
+```bash
+pip install fastmcp-creds[keyring]
+# or, with uv:
+uv add fastmcp-creds[keyring]
+```
+
+Requires Python 3.10+.
+
+## Usage
+
+### Credential provider chain
+
+Compose providers in priority order. The chain tries each in sequence and
+returns the first result where both username and password (or token) are
+non-empty.
+
+```python
+from fastmcp_creds import (
+    CredentialsProviderChain,
+    BasicAuthCredentialsProvider,
+    EnvironmentCredentialsProvider,
+)
+from fastmcp_creds.keyring import KeyringCredentialsProvider  # optional dep
+
+chain = CredentialsProviderChain([
+    KeyringCredentialsProvider("my-service"),
+    BasicAuthCredentialsProvider(),
+    EnvironmentCredentialsProvider("MY_USERNAME", "MY_PASSWORD"),
+])
+
+username, password = chain.get_credentials()
+```
+
+### Environment variables
+
+Read username and password from two environment variables:
+
+```python
+from fastmcp_creds import EnvironmentCredentialsProvider
+
+provider = EnvironmentCredentialsProvider("MY_USERNAME", "MY_PASSWORD")
+username, password = provider.get_credentials()
+```
+
+For a single token variable:
+
+```python
+provider = EnvironmentCredentialsProvider.for_token("MY_API_TOKEN")
+token, _ = provider.get_credentials()
+```
+
+### HTTP Basic Auth header
+
+Decode credentials from the standard `Authorization: Basic <base64>` header.
+Also accepts the non-compliant `Bearer Basic <base64>` variant emitted by MCP
+Inspector, and raw base64 without a scheme prefix.
+
+```python
+from fastmcp_creds import BasicAuthCredentialsProvider
+
+provider = BasicAuthCredentialsProvider()
+username, password = provider.get_credentials()
+```
+
+Optionally check a custom header first before falling back to `Authorization`:
+
+```python
+provider = BasicAuthCredentialsProvider(custom_header_name="X-My-Auth")
+```
+
+### Custom HTTP headers
+
+Read credentials from two plain-text HTTP headers:
+
+```python
+from fastmcp_creds import CustomHeaderCredentialsProvider
+
+provider = CustomHeaderCredentialsProvider("X-Username", "X-Password")
+username, password = provider.get_credentials()
+```
+
+For a single token header:
+
+```python
+provider = CustomHeaderCredentialsProvider.for_token("X-Api-Token")
+token, _ = provider.get_credentials()
+```
+
+### OS keychain
+
+Read credentials stored in the OS keychain via
+[`keyring`](https://pypi.org/project/keyring/). Requires `fastmcp-creds[keyring]`.
+
+```python
+from fastmcp_creds.keyring import KeyringCredentialsProvider
+
+# Two-key mode: reads "username" and "password" entries under the service name
+provider = KeyringCredentialsProvider("my-service")
+username, password = provider.get_credentials()
+
+# Token mode: reads a single "token" entry
+provider = KeyringCredentialsProvider.for_token("my-service")
+token, _ = provider.get_credentials()
+
+# Custom key names
+provider = KeyringCredentialsProvider("my-service", username_key="user", password_key="secret")
+provider = KeyringCredentialsProvider.for_token("my-service", token_key="jwt")
+
+# Custom lookup timeout in seconds (default 5), or None to wait indefinitely
+provider = KeyringCredentialsProvider("my-service", timeout=10)
+```
+
+The keychain lookup is bounded by a timeout, so a locked or unresponsive
+keychain (e.g. one waiting for an unlock prompt in a headless session) cannot
+stall server startup. On timeout, a warning is logged and `(None, None)` is
+returned, so a `CredentialsProviderChain` falls through to its next provider.
+
+## API Reference
+
+### `CredentialsProvider`
+
+`CredentialsProvider` is a `Protocol` — any object with a
+`get_credentials() -> tuple[str | None, str | None]` method satisfies it.
+
+### `CredentialsProviderChain`
+
+`CredentialsProviderChain(providers)` — tries each provider in order and
+returns the first result where both values are non-empty. Returns
+`(None, None)` if no provider succeeds.
+
+| Method | Description |
+| --- | --- |
+| `get_credentials()` | Returns `tuple[str \| None, str \| None]` — `(username, password)` or `(token, token)` |
+
+### `EnvironmentCredentialsProvider`
+
+`EnvironmentCredentialsProvider(username_env_var_name, password_env_var_name)`
+— reads two environment variables.
+
+`EnvironmentCredentialsProvider.for_token(token_env_var_name)` — reads a
+single environment variable; returns it as both elements of the tuple.
+
+| Method | Description |
+| --- | --- |
+| `get_credentials()` | Returns `tuple[str \| None, str \| None]` |
+
+### `BasicAuthCredentialsProvider`
+
+`BasicAuthCredentialsProvider(custom_header_name=None)` — extracts credentials
+from an HTTP Basic Auth header. Checks `custom_header_name` first if provided,
+then falls back to the standard `Authorization` header. Silently ignores
+unresolved MCP client placeholders (e.g. `${MY_VAR}`).
+
+| Method | Description |
+| --- | --- |
+| `get_credentials()` | Returns `tuple[str \| None, str \| None]`; raises `BasicAuthError` on malformed headers |
+
+### `CustomHeaderCredentialsProvider`
+
+`CustomHeaderCredentialsProvider(username_header_name, password_header_name)`
+— reads credentials from two plain-text HTTP headers. Ignores unresolved
+placeholders.
+
+`CustomHeaderCredentialsProvider.for_token(token_header_name)` — reads a
+single header; returns it as both elements of the tuple.
+
+| Method | Description |
+| --- | --- |
+| `get_credentials()` | Returns `tuple[str \| None, str \| None]` |
+
+### `KeyringCredentialsProvider`
+
+`KeyringCredentialsProvider(service, username_key="username", password_key="password", timeout=5.0)`
+— reads credentials stored in the OS keychain under the given service name.
+Returns `(None, None)` if the keychain does not answer within `timeout` seconds
+(`None` waits indefinitely). Requires `fastmcp-creds[keyring]`.
+
+`KeyringCredentialsProvider.for_token(service, token_key="token", timeout=5.0)`
+— reads a single keychain entry.
+
+| Method | Description |
+| --- | --- |
+| `get_credentials()` | Returns `tuple[str \| None, str \| None]` |
+
+### `BasicAuthError`
+
+`BasicAuthError(message, header_name)` — raised by `BasicAuthCredentialsProvider`
+when a header is present but malformed (bad base64, unsupported scheme, missing
+colon separator, empty username or password).
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `header_name` | `str` | Name of the header that caused the error |
+
+### `is_unresolved_placeholder_value`
+
+`is_unresolved_placeholder_value(value: str) -> bool` — returns `True` when a
+header value is an unresolved MCP client placeholder such as `${MY_VAR}` or
+`Basic ${MY_VAR}`. Used internally by `BasicAuthCredentialsProvider` and
+`CustomHeaderCredentialsProvider`; exposed for custom provider implementations.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE).