Metadata-Version: 2.5
Name: fastmcp-guard
Version: 0.2.2
Summary: Production operations layer for FastMCP — API key management, rate limiting, and audit logging
Project-URL: Homepage, https://github.com/rohanprichard/fastmcp-guard
Project-URL: Documentation, https://github.com/rohanprichard/fastmcp-guard/tree/main/docs
Project-URL: Repository, https://github.com/rohanprichard/fastmcp-guard
Project-URL: Issues, https://github.com/rohanprichard/fastmcp-guard/issues
Project-URL: Author, https://rohanprichard.com
Author-email: Rohan Richard <rohanrichard.work@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api-keys,audit,auth,fastmcp,llm,mcp,rate-limiting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: anyio>=4.0
Requires-Dist: bcrypt>=4.0
Requires-Dist: fastmcp>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis[hiredis]>=5.0; extra == 'redis'
Description-Content-Type: text/markdown

# fastmcp-guard 🛡️

> Production operations for [FastMCP](https://github.com/jlowin/fastmcp) servers: API-key lifecycle management, identity-aware audit logs, and policy controls without changing tool code.

[![PyPI](https://img.shields.io/pypi/v/fastmcp-guard)](https://pypi.org/project/fastmcp-guard/)
[![Python](https://img.shields.io/pypi/pyversions/fastmcp-guard)](https://pypi.org/project/fastmcp-guard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/fastmcp-guard?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/fastmcp-guard)

## Status

**Beta, v0.2.** The package is tested for single-server deployments. Memory and SQLite key stores, API-key issue/rotate/revoke flows, per-key/global/per-tool rate limits, audit logs, IP allow/deny rules, and the CLI are implemented. Postgres/Redis backends, distributed rate limiting, and OpenTelemetry export are planned.

## Install

```bash
pip install fastmcp-guard
```

## Quickstart

```python
from fastmcp import FastMCP
from fastmcp_guard import Guard

mcp = FastMCP("my-server")
guard = Guard(mcp)

key = guard.keys.create(name="alice", scopes=["read:data"])
print(key.token)  # show this once and store it safely

@mcp.tool
def get_data(query: str) -> str:
    return f"Results for: {query}"
```

Clients send the key as `Authorization: Bearer fmg_sk_...`.

## What it adds to FastMCP

FastMCP already provides strong authentication primitives and middleware. `fastmcp-guard` focuses on the operational layer around them:

- issue, inspect, rotate, and revoke scoped API keys
- enforce global, per-key, and per-tool limits
- record structured audit events by caller identity
- allow or deny callers by IP address when the transport provides one
- operate those controls through a CLI

## Documentation

- [Quickstart](docs/quickstart.md)
- [API keys](docs/keys.md)
- [Rate limiting](docs/rate-limiting.md)
- [Audit logging](docs/audit.md)
- [IP policy](docs/ip-policy.md)
- [CLI reference](docs/cli.md)
- [Backend choices](docs/backends.md)

## Local development

Requires Python 3.10+. Install the development extras, then run the repository test suite and static checks defined in `pyproject.toml`.

```bash
pip install -e '.[dev]'
pytest
ruff check .
mypy src
```

## License

MIT
