| Name | keycardai JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | Keycard Python SDK - A workspace for Keycard service packages |
| upload_time | 2025-09-10 16:41:02 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
api
authentication
keycard
oauth
security
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# KeyCard Python SDK
A collection of Python packages for KeyCard services, organized as a uv workspace.
## Overview
This workspace contains multiple Python packages that provide various KeyCard functionality:
- **keycardai-oauth**: OAuth 2.0 implementation with support for RFC 8693 (Token Exchange), RFC 7662 (Introspection), RFC 7009 (Revocation), and more
- **keycardai-mcp**: Core MCP (Model Context Protocol) integration utilities
- **keycardai-mcp-fastmcp**: FastMCP-specific integration package with decorators and middleware
## Getting Started
### Prerequisites
- Python 3.10 or higher
- [uv](https://docs.astral.sh/uv/) package manager
- [just](https://github.com/casey/just) task runner (optional, for convenience commands)
### Installation
1. Clone the repository:
```bash
git clone git@github.com:keycardai/python-sdk.git
cd python-sdk
```
2. Install the workspace:
```bash
uv sync
```
## Documentation
### Launch Documentation Server
The project includes comprehensive documentation built with Mint. To view the docs locally:
```bash
# Using just (recommended)
just docs
# Or directly with npx
cd docs && npx --yes mint@latest dev
```
This will start a local documentation server (typically at `http://localhost:3000`) with:
- API reference for all packages
- Usage examples
- Integration guides
- Architecture decisions
### Generate API Documentation
To regenerate the API reference documentation:
```bash
# Generate docs for all packages
just sdk-ref-all
# Or generate for specific packages
just sdk-ref-oauth
just sdk-ref-mcp
just sdk-ref-mcp-fastmcp
```
## Development
This project uses uv workspaces to manage multiple related packages. Each package lives in the `packages/` directory and has its own `pyproject.toml`.
### Common Tasks
```bash
# Install all dependencies
uv sync
# Run tests
just test
# or: uv run pytest
# Lint and format code
just check # Check for issues
just fix # Fix auto-fixable issues
just fix-all # Fix all issues (including unsafe fixes)
# Type checking
just typecheck
# or: uv run mypy .
# Build packages
just build
```
### Working with the workspace
- **Install all dependencies**: `uv sync`
- **Run commands in the workspace root**: `uv run <command>`
- **Run commands in a specific package**: `uv run --package <package-name> <command>`
- **Add dependencies to the workspace**: Add to the root `pyproject.toml`
- **Add dependencies to a specific package**: Add to the package's `pyproject.toml`
### Adding a new package
1. Create a new directory in `packages/`
2. Initialize the package: `uv init packages/your-package-name`
3. Update the package's `pyproject.toml` with appropriate metadata
4. The package will automatically be included in the workspace
## Package Structure
```
python-sdk/
├── pyproject.toml # Workspace root configuration
├── justfile # Task runner commands
├── README.md # This file
├── docs/ # Documentation
│ ├── docs.json # Mint documentation config
│ ├── examples/ # Usage examples
│ ├── sdk/ # Auto-generated API reference
│ └── standards/ # Development standards
├── packages/ # Individual packages
│ ├── oauth/ # OAuth 2.0 implementation
│ ├── mcp/ # Core MCP utilities
│ └── mcp-fastmcp/ # FastMCP integration
├── src/ # Workspace-level source
└── uv.lock # Shared lockfile
```
## Available Packages
### keycardai-oauth
OAuth 2.0 client implementation with comprehensive support for:
- Token Exchange (RFC 8693)
- Dynamic Client Registration (RFC 7591)
- Server Metadata Discovery (RFC 8414)
- Token Introspection (RFC 7662)
- Token Revocation (RFC 7009)
### keycardai-mcp
Core utilities for MCP (Model Context Protocol) integration.
### keycardai-mcp-fastmcp
FastMCP-specific integration package providing:
- Authentication providers
- OAuth middleware
- Decorators for token exchange
- MCP server utilities
## Examples
Each package includes practical examples in their respective `examples/` directories:
- **OAuth examples**: Anonymous token exchange, server discovery, dynamic registration
- **MCP examples**: Google API integration with delegated token exchange
## Workspace Benefits
Using a uv workspace provides several advantages:
- **Consistent Dependencies**: All packages share the same lockfile, ensuring consistent versions
- **Cross-package Development**: Easy to develop and test packages that depend on each other
- **Simplified CI/CD**: Single lockfile and unified testing across all packages
- **Shared Development Tools**: Common linting, formatting, and testing configuration
## Architecture Decision Records
Important architectural and design decisions are documented using [Architecture Decision Records (ADRs)](./docs/project/decisions/). These help explain the reasoning behind key technical choices in the project.
- [ADR-0001: Use uv Workspaces for Multi-Package Development](./docs/project/decisions/0001-use-uv-workspaces-for-package-management.mdx)
- [ADR-0002: Modular Package Structure for Minimal Dependencies](./docs/project/decisions/0002-modular-package-structure-for-minimal-dependencies.mdx)
- [ADR-0003: Use Commitizen for Commit Validation and Changelog Management](./docs/project/decisions/0003-use-commitizen-for-commit-validation-and-changelog-management.mdx)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the development tools to ensure quality:
```bash
just test # Run tests
just check # Lint code
just typecheck # Type checking
```
### Commit Message Guidelines
We use [Conventional Commits](https://www.conventionalcommits.org/) with specific scopes for our monorepo structure:
**Format**: `<type>(<scope>): <description>`
**Required Scopes**:
- `keycardai-oauth`: Changes to the OAuth package
- `keycardai-mcp`: Changes to the core MCP package
- `keycardai-mcp-fastmcp`: Changes to the FastMCP integration
- `deps`: Dependency updates
- `docs`: Documentation updates
**Common Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
**Examples**:
```bash
feat(keycardai-oauth): add PKCE support for enhanced security
fix(keycardai-mcp-fastmcp): resolve connection timeout in auth middleware
docs(keycardai-oauth): update API documentation with new examples
chore(deps): update httpx to v0.25.0 for security patch
```
**Important Notes**:
- **Squash commits** before merging - only the final commit message appears in changelog
- Scoped commits automatically appear in generated changelogs
- Use `git commit --amend` to fix commit messages if needed
- Preview changelog generation with: `just changelog-preview`
5. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
For questions, issues, or support:
- GitHub Issues: [https://github.com/keycardai/python-sdk/issues](https://github.com/keycardai/python-sdk/issues)
- Documentation: [https://docs.keycardai.com](https://docs.keycardai.com)
- Email: support@keycardai.com
Raw data
{
"_id": null,
"home_page": null,
"name": "keycardai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, authentication, keycard, oauth, security",
"author": null,
"author_email": "KeycardAI <support@keycardai.com>",
"download_url": "https://files.pythonhosted.org/packages/36/af/e5acfccbc0eb07c0a6e96a415e079df26b7eb23dae4f88ef8fdd238f547d/keycardai-0.2.0.tar.gz",
"platform": null,
"description": "# KeyCard Python SDK\n\nA collection of Python packages for KeyCard services, organized as a uv workspace.\n\n## Overview\n\nThis workspace contains multiple Python packages that provide various KeyCard functionality:\n\n- **keycardai-oauth**: OAuth 2.0 implementation with support for RFC 8693 (Token Exchange), RFC 7662 (Introspection), RFC 7009 (Revocation), and more\n- **keycardai-mcp**: Core MCP (Model Context Protocol) integration utilities\n- **keycardai-mcp-fastmcp**: FastMCP-specific integration package with decorators and middleware\n\n## Getting Started\n\n### Prerequisites\n\n- Python 3.10 or higher\n- [uv](https://docs.astral.sh/uv/) package manager\n- [just](https://github.com/casey/just) task runner (optional, for convenience commands)\n\n### Installation\n\n1. Clone the repository:\n```bash\ngit clone git@github.com:keycardai/python-sdk.git\ncd python-sdk\n```\n\n2. Install the workspace:\n```bash\nuv sync\n```\n\n## Documentation\n\n### Launch Documentation Server\n\nThe project includes comprehensive documentation built with Mint. To view the docs locally:\n\n```bash\n# Using just (recommended)\njust docs\n\n# Or directly with npx\ncd docs && npx --yes mint@latest dev\n```\n\nThis will start a local documentation server (typically at `http://localhost:3000`) with:\n- API reference for all packages\n- Usage examples \n- Integration guides\n- Architecture decisions\n\n### Generate API Documentation\n\nTo regenerate the API reference documentation:\n\n```bash\n# Generate docs for all packages\njust sdk-ref-all\n\n# Or generate for specific packages\njust sdk-ref-oauth\njust sdk-ref-mcp\njust sdk-ref-mcp-fastmcp\n```\n\n## Development\n\nThis project uses uv workspaces to manage multiple related packages. Each package lives in the `packages/` directory and has its own `pyproject.toml`.\n\n### Common Tasks\n\n```bash\n# Install all dependencies\nuv sync\n\n# Run tests\njust test\n# or: uv run pytest\n\n# Lint and format code\njust check # Check for issues\njust fix # Fix auto-fixable issues\njust fix-all # Fix all issues (including unsafe fixes)\n\n# Type checking\njust typecheck\n# or: uv run mypy .\n\n# Build packages\njust build\n```\n\n### Working with the workspace\n\n- **Install all dependencies**: `uv sync`\n- **Run commands in the workspace root**: `uv run <command>`\n- **Run commands in a specific package**: `uv run --package <package-name> <command>`\n- **Add dependencies to the workspace**: Add to the root `pyproject.toml`\n- **Add dependencies to a specific package**: Add to the package's `pyproject.toml`\n\n### Adding a new package\n\n1. Create a new directory in `packages/`\n2. Initialize the package: `uv init packages/your-package-name`\n3. Update the package's `pyproject.toml` with appropriate metadata\n4. The package will automatically be included in the workspace\n\n## Package Structure\n\n```\npython-sdk/\n\u251c\u2500\u2500 pyproject.toml # Workspace root configuration\n\u251c\u2500\u2500 justfile # Task runner commands\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 docs/ # Documentation\n\u2502 \u251c\u2500\u2500 docs.json # Mint documentation config\n\u2502 \u251c\u2500\u2500 examples/ # Usage examples\n\u2502 \u251c\u2500\u2500 sdk/ # Auto-generated API reference\n\u2502 \u2514\u2500\u2500 standards/ # Development standards\n\u251c\u2500\u2500 packages/ # Individual packages\n\u2502 \u251c\u2500\u2500 oauth/ # OAuth 2.0 implementation\n\u2502 \u251c\u2500\u2500 mcp/ # Core MCP utilities \n\u2502 \u2514\u2500\u2500 mcp-fastmcp/ # FastMCP integration\n\u251c\u2500\u2500 src/ # Workspace-level source\n\u2514\u2500\u2500 uv.lock # Shared lockfile\n```\n\n## Available Packages\n\n### keycardai-oauth\nOAuth 2.0 client implementation with comprehensive support for:\n- Token Exchange (RFC 8693)\n- Dynamic Client Registration (RFC 7591)\n- Server Metadata Discovery (RFC 8414)\n- Token Introspection (RFC 7662)\n- Token Revocation (RFC 7009)\n\n### keycardai-mcp\nCore utilities for MCP (Model Context Protocol) integration.\n\n### keycardai-mcp-fastmcp \nFastMCP-specific integration package providing:\n- Authentication providers\n- OAuth middleware\n- Decorators for token exchange\n- MCP server utilities\n\n## Examples\n\nEach package includes practical examples in their respective `examples/` directories:\n\n- **OAuth examples**: Anonymous token exchange, server discovery, dynamic registration\n- **MCP examples**: Google API integration with delegated token exchange\n\n## Workspace Benefits\n\nUsing a uv workspace provides several advantages:\n\n- **Consistent Dependencies**: All packages share the same lockfile, ensuring consistent versions\n- **Cross-package Development**: Easy to develop and test packages that depend on each other\n- **Simplified CI/CD**: Single lockfile and unified testing across all packages\n- **Shared Development Tools**: Common linting, formatting, and testing configuration\n\n## Architecture Decision Records\n\nImportant architectural and design decisions are documented using [Architecture Decision Records (ADRs)](./docs/project/decisions/). These help explain the reasoning behind key technical choices in the project.\n\n- [ADR-0001: Use uv Workspaces for Multi-Package Development](./docs/project/decisions/0001-use-uv-workspaces-for-package-management.mdx)\n- [ADR-0002: Modular Package Structure for Minimal Dependencies](./docs/project/decisions/0002-modular-package-structure-for-minimal-dependencies.mdx)\n- [ADR-0003: Use Commitizen for Commit Validation and Changelog Management](./docs/project/decisions/0003-use-commitizen-for-commit-validation-and-changelog-management.mdx)\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run the development tools to ensure quality:\n ```bash\n just test # Run tests\n just check # Lint code\n just typecheck # Type checking\n ```\n\n### Commit Message Guidelines\n\nWe use [Conventional Commits](https://www.conventionalcommits.org/) with specific scopes for our monorepo structure:\n\n**Format**: `<type>(<scope>): <description>`\n\n**Required Scopes**:\n- `keycardai-oauth`: Changes to the OAuth package\n- `keycardai-mcp`: Changes to the core MCP package \n- `keycardai-mcp-fastmcp`: Changes to the FastMCP integration\n- `deps`: Dependency updates\n- `docs`: Documentation updates\n\n**Common Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`\n\n**Examples**:\n```bash\nfeat(keycardai-oauth): add PKCE support for enhanced security\nfix(keycardai-mcp-fastmcp): resolve connection timeout in auth middleware\ndocs(keycardai-oauth): update API documentation with new examples\nchore(deps): update httpx to v0.25.0 for security patch\n```\n\n**Important Notes**:\n- **Squash commits** before merging - only the final commit message appears in changelog\n- Scoped commits automatically appear in generated changelogs\n- Use `git commit --amend` to fix commit messages if needed\n- Preview changelog generation with: `just changelog-preview`\n\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor questions, issues, or support:\n\n- GitHub Issues: [https://github.com/keycardai/python-sdk/issues](https://github.com/keycardai/python-sdk/issues)\n- Documentation: [https://docs.keycardai.com](https://docs.keycardai.com)\n- Email: support@keycardai.com",
"bugtrack_url": null,
"license": "MIT",
"summary": "Keycard Python SDK - A workspace for Keycard service packages",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://docs.keycardai.com",
"Homepage": "https://github.com/keycardai/python-sdk",
"Issues": "https://github.com/keycardai/python-sdk/issues",
"Repository": "https://github.com/keycardai/python-sdk"
},
"split_keywords": [
"api",
" authentication",
" keycard",
" oauth",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "17aa1b8afeeb7bf04e362644431f5af7f6568b72bed65358f40774fb03d16273",
"md5": "36e4227809121bef491e54754e25fe86",
"sha256": "72ed4c1f01995ba0f9892a483d3998bb5a757cb7000e52bd5ccaee8dcc91ae27"
},
"downloads": -1,
"filename": "keycardai-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "36e4227809121bef491e54754e25fe86",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 5226,
"upload_time": "2025-09-10T16:41:01",
"upload_time_iso_8601": "2025-09-10T16:41:01.783610Z",
"url": "https://files.pythonhosted.org/packages/17/aa/1b8afeeb7bf04e362644431f5af7f6568b72bed65358f40774fb03d16273/keycardai-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "36afe5acfccbc0eb07c0a6e96a415e079df26b7eb23dae4f88ef8fdd238f547d",
"md5": "3a72f8d92138af60b0bd064a5752bf8d",
"sha256": "2b3a29cf7c41b3cda203d9e0a7213a4798f10da54e9b5dd4af8695e6289eed7c"
},
"downloads": -1,
"filename": "keycardai-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "3a72f8d92138af60b0bd064a5752bf8d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 214433,
"upload_time": "2025-09-10T16:41:02",
"upload_time_iso_8601": "2025-09-10T16:41:02.823693Z",
"url": "https://files.pythonhosted.org/packages/36/af/e5acfccbc0eb07c0a6e96a415e079df26b7eb23dae4f88ef8fdd238f547d/keycardai-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 16:41:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "keycardai",
"github_project": "python-sdk",
"github_not_found": true,
"lcname": "keycardai"
}
