Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@clearskies MCP Server Generate a model for a User with columns id, name, email"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
pip install clear-skies-mcp-serverOr with uv:
uv pip install clear-skies-mcp-serverRelated MCP server: Vibe Coder MCP Server
Tool | Description |
| List all available clearskies column types |
| List all available endpoint types |
| List all available backend types |
| List all available context types |
| Get detailed docs for a specific column type |
| Get detailed docs for a specific endpoint type |
| Get detailed docs for a specific backend type |
| Get detailed docs for a specific context type |
Tool | Description |
| List all authentication types (SecretBearer, JWKS, etc.) |
| List all validator types (Required, Unique, etc.) |
| List all exception types |
| List all DI inject helpers |
| List all cursor types |
| List all input/output handlers |
| List all configuration types |
| List all client types |
| List all secrets handlers |
| List all security header handlers |
| List all query builder types |
| List all query result types |
| List all functional utilities |
Tool | Description |
| Get detailed docs for a specific authentication type |
| Get detailed docs for a specific validator type |
| Get detailed docs for a specific exception type |
| Get detailed docs for a specific DI inject helper |
| Get detailed docs for a specific cursor type |
| Get detailed docs for a specific input/output handler |
| Get detailed docs for a specific configuration type |
| Get detailed docs for a specific client type |
| Get detailed docs for a specific secrets handler |
| Get detailed docs for a specific security header handler |
| Get detailed docs for a specific query builder type |
| Get detailed docs for a specific query result type |
| Get detailed docs for a specific functional utility |
Tool | Description |
| Explain any clearskies concept in detail |
Tool | Description |
| Generate a clearskies Model class definition |
| Generate an endpoint configuration |
| Generate a context wrapping an endpoint |
| Generate an endpoint group configuration |
Tool | Description |
| Generate a complete clearskies project with multiple models |
| Generate a complete REST API application for a single model |
| Generate multiple related models with relationships |
Resource URI | Description |
| Framework overview |
| Model documentation |
| Endpoint documentation |
| Column types documentation |
| Backend documentation |
| Context documentation |
| Dependency injection docs |
| Authentication docs |
| Save lifecycle docs |
| Query documentation |
| Validator documentation |
Resource URI | Description |
| Testing clearskies applications |
| Authorization patterns |
| Error handling |
| Input handling |
| Endpoint groups |
| Routing documentation |
| Response customization |
| Database migrations (Mygrations) |
| Advanced column types |
| Advanced query patterns |
| Configuration management |
| Logging and observability |
| Caching patterns |
| Async patterns |
| Advanced state machine patterns |
| Secrets backend |
Resource URI | Description |
| MemoryBackend deep dive |
| CursorBackend deep dive |
| Cursors and raw SQL |
| Transaction management |
Resource URI | Description |
| Advanced DI patterns |
| Query execution model |
| Model lifecycle |
| Input/output system |
Resource URI | Description |
| Troubleshooting guide |
| Best practices |
| Exception hierarchy reference |
| Auth flow documentation |
Resource URI | Description |
| Complete column parameter reference |
| Complete endpoint parameter reference |
| Performance guide |
| Common patterns cookbook |
Resource URI | Description |
| Complete REST API example |
| Model relationships example |
| Authenticated API example |
| CLI application example |
| API client (ApiBackend) example |
| Testing example |
| Authorization patterns example |
| Error handling example |
| Endpoint groups example |
| Database migrations example |
| Hierarchical data (CategoryTree) example |
| Audit trail tracking example |
| Many-to-many with pivot data example |
| Advanced query patterns example |
| Configuration management example |
| Advanced state machine example |
| Secrets backend example |
Resource URI | Description |
| Overview of all extension modules |
| clearskies-aws module |
| clearskies-graphql module |
| clearskies-gitlab module |
| clearskies-cortex module |
| clearskies-snyk module |
| clearskies-akeyless-custom-producer module |
Resource URI | Description |
| Docstring style guide |
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"]
}
}
}# 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-serverMIT
Analyze a ClearSkies v1 project and generate migration report.
Args:
project_path: Path to the v1 project directory
Returns:
Dictionary containing:
- models: List of discovered models
- handlers: List of discovered handlers
- errors: List of parsing errors
- warnings: List of migration warnings
- complexity: Migration complexity assessment
Inputs: project_path (required). Returns: object
Check if a module is installed and compatible.
Args:
module_name: The module name to check
Inputs: module_name (required). Returns: result
Explain a clearskies framework concept in detail.
Args:
concept: The concept to explain. One of: model, endpoint, backend, column, context, di,
authentication, autodoc, query, validator, schema, save_lifecycle, state_machine,
declarative_programming, infrastructure_neutral, testing, authorization, error_handling,
input_handling, endpoint_groups, routing, responses, migrations, advanced_columns,
advanced_queries, configuration, logging, caching, async, state_machine_advanced,
secrets_backend.
Inputs: concept (required). Returns: result
Get usage examples and integration guidance for a specific clearskies extension module.
Args:
module_name: The module name (e.g. "clearskies-aws", "clearskies-graphql", "clearskies-snyk",
"clearskies-gitlab", "clearskies-cortex", "clearskies-akeyless-custom-producer").
Inputs: module_name (required). Returns: result
Explain how a specific concept changed between v1 and v2.
Args:
concept: The concept to explain. Options:
- 'model': Model definition changes
- 'handler': Handler → Endpoint changes
- 'di': Dependency injection changes
- 'columns': Column definition changes
- 'application': Application → Context changes
- 'backend': Backend configuration changes
- 'type_hints': Type hint requirements
Returns:
Detailed explanation of the changes
Inputs: concept (required). Returns: result
Generate a clearskies context configuration that wraps an endpoint.
Args:
context_type: The context type (e.g. "Cli", "WsgiRef", "Wsgi").
endpoint_code: The endpoint expression to wrap (e.g. output from generate_endpoint).
classes: List of model class names to register with DI.
modules: List of module names to register with DI.
bindings: Dictionary of name → value DI bindings.
Inputs: context_type (required), endpoint_code (required), classes, modules, +1 more. Returns: result
Generate a clearskies endpoint configuration.
Args:
endpoint_type: Type of endpoint (e.g. "RestfulApi", "List", "Create", "Get", "Update", "Delete", "Callable").
model_name: The model class name to use with this endpoint.
url: The URL path for the endpoint (optional).
readable_column_names: List of column names that are returned in the response.
writeable_column_names: List of column names the client can set.
sortable_column_names: List of column names the client can sort by.
searchable_column_names: List of column names the client can search by.
default_sort_column_name: The default column to sort by.
authentication: Authentication configuration (e.g. 'clearskies.authentication.SecretBearer(environment_key="MY_SECRET")').
extra_options: Additional keyword arguments for the endpoint constructor.
Inputs: model_name (required), endpoint_type (required), url, extra_options, +6 more. Returns: result
Generate a clearskies EndpointGroup configuration.
Args:
url: The URL prefix for all endpoints in the group.
endpoints: List of endpoint configurations. Each dict has:
- type (str): Endpoint type (e.g. "RestfulApi", "Callable", "List")
- model_name (str): Model class name (for model-based endpoints)
- url (str): URL path for this endpoint
- readable_column_names (list[str], optional): Readable columns
- writeable_column_names (list[str], optional): Writeable columns
- sortable_column_names (list[str], optional): Sortable columns
- searchable_column_names (list[str], optional): Searchable columns
- default_sort_column_name (str, optional): Default sort column
- request_methods (list[str], optional): Allowed HTTP methods (for Callable)
- extra_options (dict, optional): Additional endpoint options
authentication: Authentication configuration for all endpoints in the group
(e.g. 'clearskies.authentication.SecretBearer(environment_key="MY_SECRET")').
Inputs: url, endpoints, authentication. Returns: result
Generate a clearskies Model class definition.
Args:
name: The model class name in PascalCase (e.g. "User", "OrderProduct").
columns: List of column definitions. Each dict has:
- name (str): Column name
- type (str): Column type (e.g. "String", "Integer", "Uuid", "BelongsToId")
- options (dict, optional): Keyword arguments for the column constructor
backend_type: Backend class name (default: "MemoryBackend").
backend_options: Keyword arguments for the backend constructor.
id_column_name: The name of the id column (default: "id").
hooks: Optional list of hook methods to include stubs for (e.g. ["pre_save", "post_save", "save_finished"]).
Inputs: name (required), columns (required), hooks, backend_type, +2 more. Returns: result
Generate multiple related clearskies Model classes with their relationships properly configured.
Use this when you need to create models with BelongsTo, HasMany, or ManyToMany relationships.
Args:
models: List of model definitions. Each dict has:
- name (str): Model class name
- columns (list[dict]): Column definitions
- backend_type (str, optional): Backend type
- id_column_name (str, optional): Id column name
Inputs: models (required). Returns: result
Generate v2 code from a v1 project.
This tool analyzes a v1 codebase and generates v2-compatible code.
Use dry_run=True to preview changes without writing files.
Args:
project_path: Path to the v1 project directory
output_path: Path where v2 code should be generated
dry_run: If True, don't write files (default: True)
Returns:
Dictionary containing:
- files: List of files to create/modify
- breaking_changes: List of breaking changes
- warnings: List of warnings
- manual_steps: List of manual steps required
Inputs: output_path (required), project_path (required), dry_run. Returns: object
Get detailed documentation for a specific clearskies authentication type.
Args:
auth_type: The auth type name (e.g. "SecretBearer", "JWKS", "SecretBasic").
Inputs: auth_type (required). Returns: result
Get detailed documentation for a specific clearskies backend type.
Args:
backend_type: The name of the backend type (e.g. "MemoryBackend", "CursorBackend", "ApiBackend").
Inputs: backend_type (required). Returns: result
Get detailed documentation for a specific clearskies client type.
Args:
client_type: The client type name.
Inputs: client_type (required). Returns: result
Get detailed documentation and constructor parameters for a specific clearskies column type.
Args:
column_type: The name of the column type (e.g. "String", "Integer", "BelongsToId").
Inputs: column_type (required). Returns: result
Get detailed documentation for a specific clearskies configuration type.
Args:
config_type: The config type name.
Inputs: config_type (required). Returns: result
Get detailed documentation for a specific clearskies context type.
Args:
context_type: The name of the context type (e.g. "Cli", "WsgiRef", "Wsgi").
Inputs: context_type (required). Returns: result
Get detailed documentation for a specific clearskies cursor type.
Args:
cursor_type: The cursor type name.
Inputs: cursor_type (required). Returns: result
Get detailed documentation for a specific clearskies DI inject helper.
Args:
inject_type: The inject type name (e.g. "ByClass", "Utcnow").
Inputs: inject_type (required). Returns: result
Get detailed documentation and configuration options for a specific clearskies endpoint type.
Args:
endpoint_type: The name of the endpoint type (e.g. "RestfulApi", "Create", "List").
Inputs: endpoint_type (required). Returns: result
Get detailed documentation for a specific clearskies exception type.
Args:
exception_type: The exception type name (e.g. "InputError", "AuthenticationError").
Inputs: exception_type (required). Returns: result
Get detailed documentation for a specific clearskies functional utility.
Args:
func_name: The functional utility name.
Inputs: func_name (required). Returns: result
Get detailed documentation for a specific clearskies input/output handler.
Args:
io_type: The input/output type name.
Inputs: io_type (required). Returns: result
Get a comprehensive checklist for v1 to v2 migration.
Returns:
Dictionary with migration phases and tasks
Inputs: no named parameters. Returns: object
Get detailed component information for a module.
Lists all components in a module, optionally filtered by category,
with their descriptions and constructor parameters.
Args:
module_name: The module name (e.g. "clearskies-aws")
category: Optional category filter (e.g. "backends", "contexts", "models")
Inputs: module_name (required), category. Returns: result
Get detailed documentation for a specific clearskies extension module.
Shows installation status, version, and all discovered components
with their descriptions and parameters.
Args:
module_name: The module name (e.g. "clearskies-aws", "clearskies-graphql", "clearskies-snyk").
Inputs: module_name (required). Returns: result
Get detailed documentation for a specific clearskies query builder type.
Args:
query_type: The query type name.
Inputs: query_type (required). Returns: result
Get detailed documentation for a specific clearskies query result type.
Args:
result_type: The query result type name.
Inputs: result_type (required). Returns: result
Get detailed documentation for a specific clearskies secrets handler.
Args:
secret_type: The secret type name.
Inputs: secret_type (required). Returns: result
Get detailed documentation for a specific clearskies security header handler.
Args:
header_type: The security header type name.
Inputs: header_type (required). Returns: result
Get detailed documentation for a specific clearskies validator type.
Args:
validator_type: The validator type name (e.g. "Required", "Unique", "Email").
Inputs: validator_type (required). Returns: result
List all available clearskies authentication types with a short description of each.
Authentication types are used to secure endpoints. They can be attached to endpoints
via the authentication parameter.
Example:
clearskies.endpoints.RestfulApi(
model_class=User,
authentication=clearskies.authentication.SecretBearer(
environment_key="API_SECRET"
),
readable_column_names=["id", "name", "email"],
writeable_column_names=["name", "email"],
searchable_column_names=["name", "email"],
sortable_column_names=["name"],
default_sort_column_name="name",
)
Inputs: no named parameters. Returns: result
List all available clearskies backend types with a short description of each.
Inputs: no named parameters. Returns: result
List all available clearskies client types with a short description of each.
Client types are used for making HTTP/API requests to external services.
Inputs: no named parameters. Returns: result
List all available clearskies column types with a short description of each.
Inputs: no named parameters. Returns: result
List all available clearskies configuration types with a short description of each.
Configuration types are used to configure various aspects of clearskies behavior.
Inputs: no named parameters. Returns: result
List all available clearskies context types with a short description of each.
Inputs: no named parameters. Returns: result
List all available clearskies cursor types with a short description of each.
Cursors are used internally by backends to execute database queries. Understanding these is useful for advanced backend customization.
Inputs: no named parameters. Returns: result
List all available clearskies DI inject helpers with a short description of each.
DI inject helpers are used to inject dependencies into your classes. They provide
special injection behaviors beyond simple class instantiation.
Example:
class MyService:
def __init__(self, utcnow: clearskies.di.inject.Utcnow):
self.utcnow = utcnow
Inputs: no named parameters. Returns: result
List all available clearskies endpoint types with a short description of each.
Inputs: no named parameters. Returns: result
List all available clearskies exception types with a short description of each.
These are the exceptions that clearskies may raise during operation. Understanding these helps with proper error handling in your application.
Inputs: no named parameters. Returns: result
List all available clearskies functional utilities with a short description of each.
Functional utilities provide helper functions and decorators for common patterns.
Inputs: no named parameters. Returns: result
List all available clearskies input/output handlers with a short description of each.
Input/output handlers define how data is read from requests and written to responses. They handle serialization formats like JSON, form data, etc.
Inputs: no named parameters. Returns: result
List all available clearskies query builder types with a short description of each.
Query builders are used to construct database queries programmatically.
Inputs: no named parameters. Returns: result
List all available clearskies query result types with a short description of each.
Query result types handle the results returned from database queries.
Inputs: no named parameters. Returns: result
List all available clearskies secrets handlers with a short description of each.
Secrets handlers provide secure access to sensitive configuration values like API keys, database passwords, etc.
Inputs: no named parameters. Returns: result
List all available clearskies security header handlers with a short description of each.
Security header handlers add security-related HTTP headers to responses, such as CORS headers, CSP, etc.
Inputs: no named parameters. Returns: result
List all available clearskies validator types with a short description of each.
Validators are used to validate model data before saving. They can be attached
to columns via the validators parameter.
Example:
from clearskies.validators import MinimumLength, Required
name = columns.String(validators=[Required(), MinimumLength(3)])
Inputs: no named parameters. Returns: result
List all available clearskies extension modules with a summary of what each provides.
Shows installation status, version (if installed), and component counts for each known clearskies extension module.
Inputs: no named parameters. Returns: result
Map a v1 code snippet to its v2 equivalent.
Useful for understanding how specific v1 patterns translate to v2.
Args:
v1_code_snippet: The v1 code to convert
context: Context hint ('model', 'handler', 'di', 'general')
Returns:
Dictionary containing:
- v2_code: Converted v2 code
- breaking_changes: List of breaking changes
- notes: Migration notes
Inputs: v1_code_snippet (required), context. Returns: object
Refresh the module discovery cache.
Forces re-discovery of all modules, useful after installing new modules.
Inputs: no named parameters. Returns: result
Generate a complete clearskies project with models and endpoints.
Returns the full file content for a working clearskies application.
Args:
project_name: The name of the project/application.
models: List of model definitions. Each dict has:
- name (str): Model class name in PascalCase
- columns (list[dict]): Column definitions (same format as generate_model)
- backend_type (str, optional): Backend type (default: "MemoryBackend")
- id_column_name (str, optional): Id column name (default: "id")
- url (str, optional): URL path for the REST API
- readable_column_names (list[str], optional): Readable columns
- writeable_column_names (list[str], optional): Writeable columns
- sortable_column_names (list[str], optional): Sortable columns
- searchable_column_names (list[str], optional): Searchable columns
- default_sort_column_name (str, optional): Default sort column
context_type: The context type to use (default: "WsgiRef").
endpoint_type: Endpoint type to use (default: "RestfulApi").
Inputs: models (required), project_name (required), context_type, endpoint_type. Returns: result
Generate a complete, runnable clearskies REST API application for a single model.
This is a convenience tool that generates a model, a RestfulApi endpoint, and a context
in a single file ready to run.
Args:
model_name: Model class name in PascalCase (e.g. "User").
columns: List of column definitions. Each dict has:
- name (str): Column name
- type (str): Column type
- options (dict, optional): Column constructor options
url: URL path (default: auto-generated from model name).
backend_type: Backend type (default: "MemoryBackend").
backend_options: Backend constructor options.
authentication: Authentication expression.
context_type: Context type (default: "WsgiRef").
Inputs: columns (required), model_name (required), url, backend_type, +3 more. Returns: result
Suggest modules that provide a specific component type.
Args:
component_type: The component category (e.g. "backends", "contexts", "models")
Inputs: component_type (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 54 tools
The list_available_X / get_X_info pairs are clearly distinct and well-partitioned by component category. However, the code-generation family has genuinely overlapping purposes: generate_model vs generate_model_with_relationships, generate_endpoint vs generate_endpoint_group, and scaffold_project vs scaffold_restful_api are easy to misselect. explain_concept vs explain_module vs explain_v1_v2_difference also risk confusion.
Most tools follow a readable verb_noun snake_case pattern (list_available_columns, get_column_info, generate_model, explain_concept). Minor deviations like list_modules/get_module_info instead of list_available_modules break the otherwise predictable list_/get_info pairing. Still consistently snake_case throughout, no camelCase mixing.
54 tools is very heavy, well past the 25+ threshold. While driven by many component categories, much of the count comes from repetitive list/get mirror pairs that could be consolidated, plus a large redundant generation/scaffolding family. Each tool does not clearly earn its place.
Coverage is broad: discovery (list/get), explanation, code generation, project scaffolding, module management, and v1→v2 migration tooling all present. Few dead ends for a framework-assistant server. Minor gaps around editing/validating generated code rather than only producing it.
Generate architecture docs, implementation plans, and dev tickets from your project requirements.
Tailor Platform for AI assistants: search, list and read the platform documentation.
Pay-per-call tools for AI assistants: code, data, finance, spreadsheets, media, web, time.
Claspine docs, API reference and code checks for AI agents: guides, recipes, errors, upgrades.
