Metadata-Version: 2.4
Name: keycardai-mcp-fastmcp
Version: 0.2.0
Summary: FastMCP integration for KeyCard OAuth client with automated token exchange and authentication
Project-URL: Homepage, https://github.com/keycardai/python-sdk
Project-URL: Repository, https://github.com/keycardai/python-sdk
Project-URL: Documentation, https://docs.keycardai.com
Project-URL: Issues, https://github.com/keycardai/python-sdk/issues
Author-email: KeyCard AI <support@keycard.ai>
License: MIT
Keywords: authentication,fastmcp,keycard,mcp,model-context-protocol,oauth,token-exchange
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastmcp==2.12.0
Requires-Dist: httpx>=0.27.2
Requires-Dist: keycardai-oauth
Requires-Dist: pydantic-settings>=2.7.1
Requires-Dist: pydantic>=2.11.7
Description-Content-Type: text/markdown

# KeyCard AI FastMCP Integration

A Python package that provides seamless integration between KeyCard and FastMCP servers, enabling secure token exchange and authentication for MCP tools.

## Installation

```bash
pip install keycardai-mcp-fastmcp
```

## Quick Start

```python
from fastmcp import FastMCP, Context
from keycardai.mcp.integrations.fastmcp import KeycardAuthProvider, OAuthClientMiddleware, get_access_token_for_resource

# Create FastMCP server with KeyCard authentication
mcp = FastMCP("My Secure Service")

# Add KeyCard authentication
auth = KeycardAuthProvider(
    zone_url="https://abc1234.keycard.cloud",
    mcp_server_name="My MCP Service"
)
mcp.set_auth_provider(auth)

# Add OAuth client middleware for token exchange
oauth_middleware = OAuthClientMiddleware(
    zone_url="https://abc1234.keycard.cloud",
    client_name="My MCP Service"
)
mcp.add_middleware(oauth_middleware)

# Use decorator for automatic token exchange
@mcp.tool()
@get_access_token_for_resource("https://www.googleapis.com/calendar/v3")
async def get_calendar_events(ctx: Context, maxResults: int = 10) -> dict:
    # ctx.access_token is automatically available with Google Calendar access
    access_token = ctx.access_token
    # Make API calls with the exchanged token...
    return {"events": [...], "totalEvents": 5}
```

## 🏗️ Architecture & Features

This integration package provides FastMCP-specific components for KeyCard OAuth:

### Core Components

| Component | Module | Description |
|-----------|---------|-------------|
| **KeycardAuthProvider** | `provider.py` | **FastMCP Authentication** - Integrates KeyCard zone tokens with FastMCP auth system |
| **OAuthClientMiddleware** | `middleware.py` | **Client Lifecycle** - Manages OAuth client initialization and context injection |
| **Token Exchange Decorators** | `decorators.py` | **Automated Exchange** - Decorators for seamless resource-specific token exchange |

### Authentication Flow

1. **Token Verification**: `KeycardAuthProvider` validates incoming JWT tokens using KeyCard zone JWKS
2. **Client Management**: `OAuthClientMiddleware` provides OAuth client to tools via FastMCP context
3. **Token Exchange**: `@get_access_token_for_resource()` decorator automates RFC 8693 token exchange
4. **API Access**: Tools receive resource-specific access tokens transparently

## Development

This package is part of the [KeycardAI Python SDK](../../README.md). 

To develop:

```bash
# From workspace root
uv sync
uv run --package keycardai-mcp-fastmcp pytest
```
## License

MIT License - see [LICENSE](../../LICENSE) file for details.

## Support

- 🐛 [Issue Tracker](https://github.com/keycardai/python-sdk/issues)
- 💬 [Community Discussions](https://github.com/keycardai/python-sdk/discussions)
- 📧 [Support Email](mailto:support@keycard.ai)
