clearskies MCP Server

An MCP (Model Context Protocol) server for the clearskies Python framework. This server provides AI assistants with tools for code generation, documentation, and project scaffolding when building applications with clearskies.

Installation

pip install clear-skies-mcp-server

Or with uv:

uv pip install clear-skies-mcp-server

Features

Documentation Tools

Core Type Discovery

Tool	Description
`list_available_columns`	List all available clearskies column types
`list_available_endpoints`	List all available endpoint types
`list_available_backends`	List all available backend types
`list_available_contexts`	List all available context types
`get_column_info`	Get detailed docs for a specific column type
`get_endpoint_info`	Get detailed docs for a specific endpoint type
`get_backend_info`	Get detailed docs for a specific backend type
`get_context_info`	Get detailed docs for a specific context type

Extended Type Discovery

Tool	Description
`list_available_authentication`	List all authentication types (SecretBearer, JWKS, etc.)
`list_available_validators`	List all validator types (Required, Unique, etc.)
`list_available_exceptions`	List all exception types
`list_available_di_inject`	List all DI inject helpers
`list_available_cursors`	List all cursor types
`list_available_input_outputs`	List all input/output handlers
`list_available_configs`	List all configuration types
`list_available_clients`	List all client types
`list_available_secrets`	List all secrets handlers
`list_available_security_headers`	List all security header handlers
`list_available_query`	List all query builder types
`list_available_query_results`	List all query result types
`list_available_functional`	List all functional utilities

Extended Type Info

Tool	Description
`get_authentication_info`	Get detailed docs for a specific authentication type
`get_validator_info`	Get detailed docs for a specific validator type
`get_exception_info`	Get detailed docs for a specific exception type
`get_di_inject_info`	Get detailed docs for a specific DI inject helper
`get_cursor_info`	Get detailed docs for a specific cursor type
`get_input_output_info`	Get detailed docs for a specific input/output handler
`get_config_info`	Get detailed docs for a specific configuration type
`get_client_info`	Get detailed docs for a specific client type
`get_secret_info`	Get detailed docs for a specific secrets handler
`get_security_header_info`	Get detailed docs for a specific security header handler
`get_query_info`	Get detailed docs for a specific query builder type
`get_query_result_info`	Get detailed docs for a specific query result type
`get_functional_info`	Get detailed docs for a specific functional utility

Concept Explanation

Tool	Description
`explain_concept`	Explain any clearskies concept in detail

Code Generation Tools

Tool	Description
`generate_model`	Generate a clearskies Model class definition
`generate_endpoint`	Generate an endpoint configuration
`generate_context`	Generate a context wrapping an endpoint
`generate_endpoint_group`	Generate an endpoint group configuration

Scaffolding Tools

Tool	Description
`scaffold_project`	Generate a complete clearskies project with multiple models
`scaffold_restful_api`	Generate a complete REST API application for a single model
`generate_model_with_relationships`	Generate multiple related models with relationships

Documentation Resources

Core Documentation

Resource URI	Description
`clearskies://docs/overview`	Framework overview
`clearskies://docs/models`	Model documentation
`clearskies://docs/endpoints`	Endpoint documentation
`clearskies://docs/columns`	Column types documentation
`clearskies://docs/backends`	Backend documentation
`clearskies://docs/contexts`	Context documentation
`clearskies://docs/di`	Dependency injection docs
`clearskies://docs/authentication`	Authentication docs
`clearskies://docs/save-lifecycle`	Save lifecycle docs
`clearskies://docs/queries`	Query documentation
`clearskies://docs/validators`	Validator documentation

Extended Documentation

Resource URI	Description
`clearskies://docs/testing`	Testing clearskies applications
`clearskies://docs/authorization`	Authorization patterns
`clearskies://docs/error-handling`	Error handling
`clearskies://docs/input-handling`	Input handling
`clearskies://docs/endpoint-groups`	Endpoint groups
`clearskies://docs/routing`	Routing documentation
`clearskies://docs/responses`	Response customization
`clearskies://docs/migrations`	Database migrations (Mygrations)
`clearskies://docs/advanced-columns`	Advanced column types
`clearskies://docs/advanced-queries`	Advanced query patterns
`clearskies://docs/configuration`	Configuration management
`clearskies://docs/logging`	Logging and observability
`clearskies://docs/caching`	Caching patterns
`clearskies://docs/async`	Async patterns
`clearskies://docs/state-machine-advanced`	Advanced state machine patterns
`clearskies://docs/secrets-backend`	Secrets backend

Backend Deep Dives

Resource URI	Description
`clearskies://docs/backend-memory`	MemoryBackend deep dive
`clearskies://docs/backend-cursor`	CursorBackend deep dive
`clearskies://docs/cursors`	Cursors and raw SQL
`clearskies://docs/transactions`	Transaction management

Framework Internals

Resource URI	Description
`clearskies://docs/di-advanced`	Advanced DI patterns
`clearskies://docs/query-execution`	Query execution model
`clearskies://docs/model-lifecycle`	Model lifecycle
`clearskies://docs/input-output`	Input/output system

Developer Experience

Resource URI	Description
`clearskies://docs/troubleshooting`	Troubleshooting guide
`clearskies://docs/best-practices`	Best practices
`clearskies://docs/exceptions`	Exception hierarchy reference
`clearskies://docs/auth-flow`	Auth flow documentation

Reference Material

Resource URI	Description
`clearskies://docs/column-reference`	Complete column parameter reference
`clearskies://docs/endpoint-reference`	Complete endpoint parameter reference
`clearskies://docs/performance`	Performance guide
`clearskies://docs/patterns`	Common patterns cookbook

Example Resources

Resource URI	Description
`clearskies://examples/restful-api`	Complete REST API example
`clearskies://examples/relationships`	Model relationships example
`clearskies://examples/authentication`	Authenticated API example
`clearskies://examples/cli-app`	CLI application example
`clearskies://examples/api-backend`	API client (ApiBackend) example
`clearskies://examples/testing`	Testing example
`clearskies://examples/authorization`	Authorization patterns example
`clearskies://examples/error-handling`	Error handling example
`clearskies://examples/endpoint-group`	Endpoint groups example
`clearskies://examples/migrations`	Database migrations example
`clearskies://examples/hierarchical-data`	Hierarchical data (CategoryTree) example
`clearskies://examples/audit-trail`	Audit trail tracking example
`clearskies://examples/pivot-data`	Many-to-many with pivot data example
`clearskies://examples/advanced-queries`	Advanced query patterns example
`clearskies://examples/configuration`	Configuration management example
`clearskies://examples/state-machine-advanced`	Advanced state machine example
`clearskies://examples/secrets-backend`	Secrets backend example

Module Resources

Resource URI	Description
`clearskies://modules/overview`	Overview of all extension modules
`clearskies://modules/aws`	clearskies-aws module
`clearskies://modules/graphql`	clearskies-graphql module
`clearskies://modules/gitlab`	clearskies-gitlab module
`clearskies://modules/cortex`	clearskies-cortex module
`clearskies://modules/snyk`	clearskies-snyk module
`clearskies://modules/akeyless`	clearskies-akeyless-custom-producer module

Style Resources

Resource URI	Description
`clearskies://style/docstrings`	Docstring style guide

MCP Configuration

Add this to your MCP settings (e.g. in Kilo Code, Claude Desktop, etc.):

{
    "mcpServers": {
        "clearskies": {
            "command": "clear-skies-mcp-server",
            "args": []
        }
    }
}

Or if using uv/uvx:

{
    "mcpServers": {
        "clearskies": {
            "command": "uvx",
            "args": ["clear-skies-mcp-server"]
        }
    }
}

Development

# Clone the repo
git clone https://github.com/clearskies-py/mcp-server.git
cd mcp-server

# Create venv and install dependencies
uv sync all-extras --all-groups

# Run the server
clear-skies-mcp-server

License

MIT