Flaskion

Flaskion is a Laravel-inspired application framework and project scaffolder for Flask. The 2.0.0a1 runtime adds a small interface-independent use-case boundary while retaining the Flask project generators from Phase 1.

Flaskion 2 is being designed as an AI-native application framework. The generic Task List uses Flaskion's optional MCP API as a third adapter beside HTTP and CLI; authentication and remote deployment integration remain future work.

Current features

• Flask application factory and explicit extension initialization
• flaskion.Application for registering and invoking plain Python use cases
• Constructor-based service and repository dependencies without a DI container
• Optional flaskion.mcp API backed by FastMCP 4
• Local stdio and remote Streamable HTTP serving with MCP test support
• Separate web and JSON API blueprints
• SQLite, MySQL, or PostgreSQL project configuration
• SQLAlchemy and Flask-Migrate
• Conflict-safe model, controller, schema, resource, and authentication generators
• Session authentication scaffold with CSRF-protected forms
• Cross-platform virtual-environment invocation

Installation

pipx install flaskion
# or
pip install flaskion
# Optional MCP adapter support
pip install "flaskion[mcp]"

Flaskion requires Python 3.11 or newer. The core package and optional MCP integration share the same supported Python floor.

Create a project

flaskion make:new myproject --db=sqlite
cd myproject
source .venv/bin/activate
flask run

On Windows, activate the environment with .venv\Scripts\activate.

Use --db=mysql or --db=postgres to install and configure the matching SQLAlchemy driver. Use --no-install to create files without creating an environment or installing dependencies.

The default creation flow:

1. builds the project in a staging directory;
2. writes a random development secret and a database URL to .env;
3. initializes Git;
4. creates .venv and installs dependencies;
5. initializes the Alembic migration repository;
6. moves the complete project into its final directory.

If a setup command fails, Flaskion reports the command and removes the incomplete staging directory.

Generated project structure

myproject/
├── app/
│   ├── __init__.py           # Application factory
│   ├── application.py        # Interface-independent use-case registration
│   ├── config.py             # Environment-backed configuration
│   ├── extensions.py         # Unbound Flask extensions
│   ├── controllers/
│   ├── models/
│   ├── routes/
│   ├── schemas/
│   ├── static/
│   └── templates/
├── migrations/               # Created by `flask db init`
├── .env.example
├── requirements.txt
└── run.py

Commands

Generators refuse to overwrite existing files. Multi-file generation is planned before writing, so a conflict does not leave a partially changed project. Names such as CardGrader, card-grader, and card_grader normalize to consistent Python module and class names.

Generated API controller methods return explicit 501 Not Implemented JSON until application behavior is supplied. Flaskion does not generate pretend persistence logic.

Database migrations

The normal project-creation flow runs flask db init. Create and apply revisions with:

flask db migrate -m "Initial schema"
flask db upgrade

When a project is created with --no-install, install its dependencies and run flask db init yourself before creating the first revision.

Authentication scaffold

flaskion make:auth

This creates a user model, schema, controller, and login/register/dashboard templates. Forms carry Flask-WTF CSRF tokens, login clears prior session data, passwords must contain at least 12 characters, and logout is POST-only.

This remains starter authentication, not a complete identity product. Production applications still need requirements appropriate to their threat model, such as email verification, password reset, rate limiting, secure-cookie deployment settings, and authorization policies.

Development

Install the development dependency group with a compatible environment manager, then run:

python -m unittest discover -v
ruff check .
python -m build

When running directly from a source checkout with the src/ layout, use an editable install or set PYTHONPATH=src:..

Runtime usage

Use cases do not inherit from Flaskion classes. Register a plain function, bound service method, or callable object against any message type:

from dataclasses import dataclass

from flaskion import Application


@dataclass(frozen=True)
class Greet:
    name: str


application = Application()
application.register(Greet, lambda message: f"Hello, {message.name}")

assert application.handle(Greet("Ada")) == "Hello, Ada"

The decorator form @application.use_case(Greet) is available but optional. Services and repository protocols are application-owned; Flaskion does not require base classes or a universal repository abstraction.

Task List example

The canonical example is under examples/task_list. It implements create, list, and complete through one TaskService, a repository protocol, and a SQLite adapter. HTTP, CLI, and MCP receive the same Application instance and invoke the same handlers.

PYTHONPATH=src:. flask --app examples.task_list.run run
PYTHONPATH=src:. python -m examples.task_list.cli create "Write documentation"
PYTHONPATH=src:. python -m examples.task_list.cli list
PYTHONPATH=src:. python -m examples.task_list.cli complete 1
PYTHONPATH=src:. flaskion mcp:serve --app examples.task_list.mcp_server:mcp

Install the MCP adapter with pip install -e '.[mcp]'. MCP remains optional: FastMCP is imported only by flaskion.mcp's private compatibility boundary, never by Task List code.

For a remotely connectable development endpoint, use Streamable HTTP:

PYTHONPATH=src:. flaskion mcp:serve \
  --app examples.task_list.mcp_server:mcp \
  --transport http --host 127.0.0.1 --port 8000

The MCP endpoint is http://127.0.0.1:8000/mcp. Inspect it locally with:

npx -y @modelcontextprotocol/inspector --web http://127.0.0.1:8000/mcp

Loopback is the safe default. Binding to a public interface exposes an unauthenticated MCP endpoint until Flaskion's remote authentication boundary is implemented; use network controls and do not treat the development command as a production deployment configuration.

The example intentionally does not include jobs, events, authentication policy, generic middleware, or a dependency-injection container.

Architecture documents

• Flaskion 2 architecture
• Flaskion 2 roadmap
• MCP architecture