keycardai-fastmcp 0.2.0__tar.gz

keycardai_fastmcp-0.2.0/.gitignore

@@ -0,0 +1,193 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.  For a PyCharm
+#  project, uncomment below!
+#.idea/
+
+# VS Code
+.vscode/
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Backup files
+*~
+*.bak
+*.backup
+*.old
+*.orig
+
+# Temporary files
+*.tmp
+*.temp
+
+# IDE files
+*.swp
+*.swo
+*~
+
+# Local development
+.local/
+
+# Claude Code
+CLAUDE.md

keycardai_fastmcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+## 0.2.0-keycardai-fastmcp (2026-04-27)
+
+
+- feat(keycardai-fastmcp): rename keycardai-mcp-fastmcp via bridge package (ACC-233) (#102)
+- * feat(keycardai-fastmcp): rename keycardai-mcp-fastmcp via bridge package (ACC-233)
+- The current name carries a redundant -mcp suffix (FastMCP only speaks MCP,
+so the protocol tag adds no information). Renames to keycardai-fastmcp per
+the revised KEP, with keycardai-mcp-fastmcp preserved as a deprecation
+bridge so the customer in production on the old name keeps working
+indefinitely.
+- What ships:
+- * New keycardai-fastmcp package at packages/fastmcp/, full implementation
+  under the keycardai.fastmcp namespace. Tests, examples, README move with
+  the source. Wired into the workspace and the release.yml tag filter.
+* Deprecated keycardai-mcp-fastmcp now depends only on keycardai-fastmcp
+  and re-exports every public symbol at the original
+  keycardai.mcp.integrations.fastmcp.* paths. Importing the top-level
+  module emits a DeprecationWarning pointing at the canonical name.
+* Bridge contract test (test_bridge.py, 4 tests) asserts the
+  DeprecationWarning fires and that bridge symbols are identity-equal to
+  the canonical ones. The full behavioral suite lives in keycardai-fastmcp
+  going forward.
+- Customer impact: pip install keycardai-mcp-fastmcp keeps working; the
+package transitively pulls keycardai-fastmcp. No forced removal timeline,
+the bridge ships until every known caller migrates.
+- Verified: ruff clean. fastmcp 51/51, mcp-fastmcp bridge 4/4, mcp 560/560,
+oauth 208/208, starlette 49/49.
+- Supersedes the canceled ACC-195 (which used the now-rejected
+keycardai-fastmcp-mcp name).
+- * fix(keycardai-fastmcp): bridge re-exports the full canonical surface
+- Review caught that the bridge provider.py only re-exported a hand-enumerated
+subset of the canonical surface, dropping documented public symbols
+(get_token_debug_info, introspect, INTROSPECT, AuthProviderConfigurationError,
+AuthProviderInternalError, AuthProviderRemoteError). Importing any of those
+from keycardai.mcp.integrations.fastmcp.provider raised ImportError, breaking
+the bridge contract for downstream callers using less common symbols.
+- Fixes:
+- - Add __all__ to keycardai.fastmcp.provider listing the 28-name public
+  surface. Stdlib/typing helpers (logging, os, urlparse, wraps, Any,
+  Callable, etc.) are deliberately excluded.
+- Replace the bridge provider.py hand-enumeration with
+  ``from keycardai.fastmcp.provider import *``, plus a re-export of __all__
+  so future symbol additions to the canonical module flow through
+  automatically.
+- Add test_bridge_provider_exposes_full_public_surface: iterates the
+  canonical __all__, asserts every symbol is present at the bridge path
+  and identity-equal to the canonical reference. Regression test for the
+  symbol-drop class of bug.
+- Scrub em dashes from the renamed example READMEs (pre-existing prose,
+  but new file paths shipping under our review).
+- Verified: fastmcp 51/51, mcp-fastmcp bridge 5/5 (was 4 + 1 new). Smoke:
+the six previously-missing symbols now import cleanly from the old path.
+- * ci: pin extractions/setup-just version
+- The action stopped resolving "latest" sometime today and started failing
+with `no release for just matching version specifier`. Pinning unblocks
+PR validation and the post-merge bump-and-publish pipeline.
+- 1.50.0 is the current stable just release (April 2026).
+- * ci: replace extractions/setup-just with the upstream install script
+- extractions/setup-just@v2 is currently broken for both unpinned and
+explicit-version requests ("no release for just matching version
+specifier"). Pinning to 1.50.0 did not help because the action regression
+is in its release lookup, not its version resolution.
+- Switch to the just.systems install script (the project owners ship and
+maintain it). Runs as a plain bash step with no third-party action
+dependency and is unaffected by setup-just regressions.

keycardai_fastmcp-0.2.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: keycardai-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 <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>=3.0.0
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: keycardai-mcp>=0.15.0
+Requires-Dist: keycardai-oauth>=0.7.0
+Requires-Dist: pydantic-settings>=2.7.1
+Requires-Dist: pydantic>=2.11.7
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
+Requires-Dist: pytest>=8.4.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+# keycardai-fastmcp
+
+FastMCP integration for Keycard OAuth: protect FastMCP servers with Keycard
+authentication and run delegated OAuth 2.0 token exchange (RFC 8693) for
+downstream APIs.
+
+This is the canonical home for the integration; `keycardai-mcp-fastmcp` is
+preserved as a deprecation bridge for callers still on the old name.
+
+## Installation
+
+```bash
+pip install keycardai-fastmcp
+```
+
+## Quick Start
+
+```python
+from fastmcp import FastMCP, Context
+from keycardai.fastmcp import AuthProvider
+
+auth_provider = AuthProvider(
+    zone_id="abc1234",
+    mcp_server_name="My Server",
+    mcp_base_url="http://localhost:8000",
+)
+
+mcp = FastMCP("My Server", auth=auth_provider.get_remote_auth_provider())
+
+@mcp.tool()
+@auth_provider.grant("https://api.example.com")
+async def call_external_api(ctx: Context, query: str):
+    keycardai = await ctx.get_state("keycardai")
+    token = keycardai.access("https://api.example.com").access_token
+    return f"Results for {query} (token starts with {token[:8]})"
+```
+
+## Migration from `keycardai-mcp-fastmcp`
+
+The old package keeps working: `from keycardai.mcp.integrations.fastmcp import AuthProvider`
+emits a `DeprecationWarning` pointing here and returns the same class. Migrate
+when convenient.

keycardai_fastmcp-0.2.0/README.md

@@ -0,0 +1,42 @@
+# keycardai-fastmcp
+
+FastMCP integration for Keycard OAuth: protect FastMCP servers with Keycard
+authentication and run delegated OAuth 2.0 token exchange (RFC 8693) for
+downstream APIs.
+
+This is the canonical home for the integration; `keycardai-mcp-fastmcp` is
+preserved as a deprecation bridge for callers still on the old name.
+
+## Installation
+
+```bash
+pip install keycardai-fastmcp
+```
+
+## Quick Start
+
+```python
+from fastmcp import FastMCP, Context
+from keycardai.fastmcp import AuthProvider
+
+auth_provider = AuthProvider(
+    zone_id="abc1234",
+    mcp_server_name="My Server",
+    mcp_base_url="http://localhost:8000",
+)
+
+mcp = FastMCP("My Server", auth=auth_provider.get_remote_auth_provider())
+
+@mcp.tool()
+@auth_provider.grant("https://api.example.com")
+async def call_external_api(ctx: Context, query: str):
+    keycardai = await ctx.get_state("keycardai")
+    token = keycardai.access("https://api.example.com").access_token
+    return f"Results for {query} (token starts with {token[:8]})"
+```
+
+## Migration from `keycardai-mcp-fastmcp`
+
+The old package keeps working: `from keycardai.mcp.integrations.fastmcp import AuthProvider`
+emits a `DeprecationWarning` pointing here and returns the same class. Migrate
+when convenient.

keycardai_fastmcp-0.2.0/examples/delegated_access/.python-version

@@ -0,0 +1 @@
+3.10

keycardai_fastmcp-0.2.0/examples/delegated_access/README.md

@@ -0,0 +1,187 @@
+# GitHub API Integration with Keycard Delegated Access
+
+A complete example demonstrating how to use the `@grant` decorator for token exchange, enabling your MCP server to access external APIs (GitHub) on behalf of authenticated users.
+
+## Why Keycard?
+
+Keycard lets you securely connect your AI IDE or agent to external resources. With delegated access, your MCP server can:
+
+- **Exchange user tokens** for API-specific access tokens via OAuth 2.0 Token Exchange
+- **Access external APIs** on behalf of authenticated users with proper scopes
+- **Maintain audit trails** of all delegated operations
+
+## Prerequisites
+
+Before running this example, set up Keycard for delegated access:
+
+### 1. Sign up at [keycard.ai](https://keycard.ai)
+
+### 2. Create a Zone
+
+A zone is your authentication boundary. Create one in the Keycard console.
+
+### 3. Configure an Identity Provider
+
+Set up an identity provider (Google, Microsoft, etc.) for user authentication.
+
+### 4. Create a GitHub App
+
+Create a GitHub App in your organization (or personal account) to enable delegated access:
+
+1. Go to your GitHub organization → **Settings** → **Developer settings** → **GitHub Apps**
+2. Click **New GitHub App**
+3. Configure the app with the permissions your MCP server needs (e.g., **Repository** access, **User** profile read)
+4. Generate a **Client Secret**
+5. Note down the **Client ID** and **Client Secret**; you'll use these to configure the credential provider in Keycard
+
+### 5. Configure a Credential Provider in Keycard
+
+Set up the GitHub credential provider so Keycard can obtain tokens on behalf of users:
+
+1. In your Keycard zone, go to **Providers**
+2. Add a new GitHub credential provider using the **Client ID** and **Client Secret** from the GitHub App you created in step 4
+3. This credential provider is what Keycard uses to issue GitHub API tokens on behalf of authenticated users
+
+### 6. Configure GitHub as an API Resource
+
+Add GitHub as an API resource in your zone:
+
+1. In your Keycard zone, go to **Resources**
+2. Add a new API resource for GitHub:
+   - **Resource URL**: `https://api.github.com`
+   - **Credential Provider**: Select the GitHub credential provider you created in step 5
+   - **Scopes**: `read:user`, `repo` (adjust based on your needs)
+
+### 7. Create an Application
+
+Create an application that will represent your MCP server:
+
+1. Go to **Applications** in your zone
+2. Create a new application
+   - **Identifier**: Set this to match your `MCP_SERVER_URL` (e.g., `http://localhost:8000/`)
+3. Add the **GitHub API** resource as a dependency of this application
+4. Generate **Application Credentials** (Client ID and Client Secret)
+   - These are what you'll use for `KEYCARD_CLIENT_ID` and `KEYCARD_CLIENT_SECRET`
+
+### 8. Create an MCP Server Resource
+
+Register your MCP server with Keycard:
+
+1. Go to **Resources** and add a new MCP Server resource
+2. Set the URL to your server's MCP endpoint: `http://localhost:8000/mcp`
+3. Configure the resource:
+   - **Provided by**: Select the application you created in step 7
+   - **Credential Provider**: Keycard STS Zone Provider
+
+> **Note:** Delegated token exchange requires Keycard to reach your MCP server. For local development, use a tunneling service (e.g., ngrok, Cloudflare Tunnel) or host the server on a publicly accessible URL.
+
+See [Delegated Access Setup](https://docs.keycard.ai/build-with-keycard/delegated-access) for detailed instructions.
+
+## Quick Start
+
+### 1. Set Up Tunneling (for local development)
+
+Delegated access requires Keycard to reach your server. For local development, set up a tunnel:
+
+```bash
+# Using ngrok
+ngrok http 8000
+
+# Or using Cloudflare Tunnel
+cloudflared tunnel --url http://localhost:8000
+```
+
+Use the public URL from your tunnel as `MCP_SERVER_URL`.
+
+### 2. Set Environment Variables
+
+```bash
+export KEYCARD_ZONE_ID="your-zone-id"          # or use KEYCARD_ZONE_URL
+export KEYCARD_CLIENT_ID="your-client-id"
+export KEYCARD_CLIENT_SECRET="your-client-secret"
+export MCP_SERVER_URL="https://your-tunnel-url.ngrok.io/"  # Must be publicly reachable
+```
+
+### 3. Install Dependencies and Run the Server
+
+```bash
+cd packages/mcp-fastmcp/examples/delegated_access
+uv sync
+uv run python main.py
+```
+
+The server will start on `http://localhost:8000`.
+
+### 5. Verify the Server
+
+Check that OAuth metadata is being served:
+
+```bash
+curl http://localhost:8000/.well-known/oauth-authorization-server
+```
+
+You should see JSON with `issuer`, `authorization_endpoint`, and other OAuth metadata.
+
+## Testing with MCP Client
+
+1. Connect to your server using an MCP-compatible client (e.g., Cursor, Claude Desktop)
+2. Authenticate through your configured identity provider
+3. When prompted by Keycard, authorize GitHub access
+4. Call the `get_github_user` or `list_github_repos` tools
+5. Verify GitHub user data is returned
+
+## How It Works
+
+### Token Exchange Flow
+
+```
+User                    MCP Server              Keycard                 GitHub
+  │                         │                      │                       │
+  │──── Authenticate ──────►│                      │                       │
+  │                         │◄── User Token ───────│                       │
+  │                         │                      │                       │
+  │──── Call Tool ─────────►│                      │                       │
+  │                         │── Exchange Token ───►│                       │
+  │                         │◄─ GitHub Token ──────│                       │
+  │                         │                      │                       │
+  │                         │──────────────────────┼── API Request ───────►│
+  │                         │◄─────────────────────┼── API Response ───────│
+  │◄─── Tool Result ────────│                      │                       │
+```
+
+1. User authenticates to your MCP server via Keycard
+2. When a tool with `@grant` is called, Keycard exchanges the user's token
+3. The exchanged token has the scopes configured for the external resource
+4. Your server uses this token to call GitHub API on behalf of the user
+
+## Error Handling
+
+The example demonstrates comprehensive error handling patterns:
+
+| Method | Description |
+|--------|-------------|
+| `has_errors()` | Check for any errors (global or resource-specific) |
+| `get_errors()` | Get all error details as a dictionary |
+| `has_resource_error(url)` | Check for errors on a specific resource |
+| `get_resource_errors(url)` | Get errors for a specific resource |
+| `has_error()` | Check for global errors only |
+| `get_error()` | Get global error details |
+
+## Environment Variables Reference
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `KEYCARD_ZONE_ID` | Yes* | Your Keycard zone ID |
+| `KEYCARD_ZONE_URL` | Yes* | Your full Keycard zone URL (alternative to `KEYCARD_ZONE_ID`) |
+| `KEYCARD_CLIENT_ID` | Yes | Client ID from application credentials |
+| `KEYCARD_CLIENT_SECRET` | Yes | Client secret from application credentials |
+| `MCP_SERVER_URL` | Yes | Server URL (must be publicly reachable for delegated access) |
+
+\* Provide either `KEYCARD_ZONE_ID` or `KEYCARD_ZONE_URL`, not both.
+
+## Learn More
+
+- [Keycard Documentation](https://docs.keycard.ai)
+- [Delegated Access Guide](https://docs.keycard.ai/build-with-keycard/delegated-access)
+- [FastMCP Documentation](https://docs.fastmcp.com)
+- [GitHub API Documentation](https://docs.github.com/rest)