MCP Server
MCP server that makes the installed Flet source code the source of truth for AI agents.
---
Flet changes faster than model training data. Controls get renamed, deprecated
and removed (`ft.ElevatedButton` → `ft.Button`, and `Button(text=...)` is now
`Button(content=...)`), properties change types, icon names get hallucinated.
The only reliable reference is the flet source code **actually installed in
your environment** — this server ships with flet as a dependency, gives your AI
tools to read it directly, and — uniquely — can **run and verify AI-written
Flet code against that installed flet** before you ever see it.
> **Upgrading from v0.2.x?** The plain command below works again — no
> `--with mcp<2 --with typing_extensions` flags needed anymore. v0.2.x broke
> because the mcp SDK 2.0 removed `mcp.server.fastmcp`; v1.0.0 is built on the
> new `MCPServer` API and pins `mcp>=2`.
```bash
uvx flet-mcp-server
```
## Verify your Flet code (the killer feature)
`verify_flet_code(code)` checks AI-generated Flet code against the installed
flet in two passes and reports **every problem with line numbers and hints**:
* **Static**: unknown controls, properties that don't exist anymore, enum
typos, deprecated classes, undefined event handlers.
* **Dynamic**: the code runs in a sandboxed subprocess (app launchers are
neutralized — nothing opens, nothing starts) while flet's own validators
fire on every constructed control, catching errors that normally only appear
at runtime — like `Slider(min=10, max=5)`.
```json
{
"status": "errors",
"flet_version": "0.86.5",
"controls_verified": 6,
"diagnostics": [
{"severity": "warning", "code": "deprecated", "line": 4,
"message": "'ElevatedButton' is deprecated in flet 0.86.5.",
"hint": "Did you mean 'FilledButton'?"},
{"severity": "error", "code": "bad-kwarg", "line": 4,
"message": "'ElevatedButton' has no property 'text' in flet 0.86.5."},
{"severity": "error", "code": "runtime", "line": null,
"message": "ValueError: Slider: min (10) must be less than or equal to max (5)"}
]
}
```
The server's instructions tell AI clients to **verify before delivering** and
fix-and-reverify until the report is `passed` — plus three ready-made prompts
(`verify_flet_code_prompt`, `migrate_flet_prompt`, `build_flet_ui_prompt`)
that encode the full workflow.
## What your AI gets
**Verify (new in v1.0.0)** — confidence that AI-written code is actually valid:
* `verify_flet_code(code)` — static + sandboxed dynamic verification against
the installed flet, structured diagnostics with line numbers and hints.
* Prompts: `verify_flet_code_prompt`, `migrate_flet_prompt`, `build_flet_ui_prompt`.
* Resources: `flet://version` and `flet-source://` (browsable installed
source, path-traversal safe).
**Source of truth** — reads the flet package installed alongside the server,
so every answer matches the exact version your app runs:
* `inspect_flet_control(control_name)` — every property with type, default and
origin class (inherited fields marked), `on_*` events, deprecation warnings,
the class hierarchy, and the full class source with per-property docstrings.
* `get_flet_version()` — which flet version the tools are reading, and from where.
* `search_flet_source(query)` — grep the installed flet sources; definitions
rank first.
* `read_flet_source(module, symbol?)` — numbered source of any module, or a
single class/function extracted by AST.
* `list_flet_api()` — the true `flet.__all__` of the installed version, grouped
by category (Material / Cupertino / Core controls, Services, Components & hooks).
* `search_flet_icons(query, icon_set)` — valid `ft.Icons.*` /
`ft.CupertinoIcons.*` names, so the AI never invents one again.
* `search_flet_colors(query)` — valid `ft.Colors.*` constants, including shades
like `AMBER_500`.
**Docs & examples** — official guides and runnable apps:
* `search_flet_docs(query)` — smart search (direct > keyword aliases > fuzzy).
* `get_flet_doc(doc_path, offset?, max_lines?)` — Markdown of a doc page, paged
so long pages don't flood the conversation.
* `list_flet_controls()` — every control that has a docs page.
* `search_flet_examples(query)` — official example apps (counter, todo, 7guis,
routing, games…) straight from the flet repo, always current.
* `get_flet_example(example_id)` — full source of an example project.
**Ecosystem** — packages beyond core flet:
* `list_official_packages()` — official extensions from the monorepo (flet-audio, flet-video, …).
* `search_flet_ecosystem(query)` — verified community packages on GitHub/PyPI.
* `get_package_details(package_name)` — PyPI version, classification, install command.
## Tools reference (complete list)
All 16 tools, three prompts and two resources exposed by the server:
| # | Tool | What it does |
|---|---|---|
| 1 | `verify_flet_code(code, timeout_secs?)` | Verify AI-written Flet code against the installed flet (static + sandboxed execution with flet's own validators); line-numbered diagnostics. |
| 2 | `get_flet_version()` | Which flet version the tools read, and from where. |
| 3 | `inspect_flet_control(control_name)` | Exact current API of any control: properties, types, defaults, events, deprecations, full class source. |
| 4 | `search_flet_source(query, max_results?)` | Ranked grep across the installed flet sources. |
| 5 | `read_flet_source(module, symbol?, max_lines?)` | Numbered source of any flet module or a single class/function. |
| 6 | `list_flet_api()` | The installed flet's true `__all__`, grouped by category. |
| 7 | `search_flet_icons(query, icon_set?, max_results?)` | Valid `ft.Icons.*` / `ft.CupertinoIcons.*` names. |
| 8 | `search_flet_colors(query, max_results?)` | Valid `ft.Colors.*` / `ft.CupertinoColors.*` constants. |
| 9 | `search_flet_docs(query)` | Search the official docs index (fuzzy + keyword aliases). |
| 10 | `get_flet_doc(doc_path, offset?, max_lines?)` | Paged Markdown of a doc page. |
| 11 | `list_flet_controls()` | Controls that have documentation pages. |
| 12 | `search_flet_examples(query, max_results?)` | Search official example apps by keyword. |
| 13 | `get_flet_example(example_id, max_chars?)` | Full source of an official example project. |
| 14 | `list_official_packages()` | Official flet extension packages. |
| 15 | `search_flet_ecosystem(query)` | Verified third-party flet packages on GitHub. |
| 16 | `get_package_details(package_name)` | PyPI details + install command for a package. |
**Prompts**: `verify_flet_code_prompt(code)`, `migrate_flet_prompt(project_summary)`,
`build_flet_ui_prompt(spec)` — guided workflows that encode the verify-first loop.
**Resources**: `flet://version` (static) and `flet-source://{module}` (template —
installed source, path-traversal safe).
## Matching your project's Flet version
By default the source tools read the latest flet bundled with the server. Two
ways to verify against the exact version **your project** uses:
**1. Pin the version at launch** (matches `uvx`-style workflows):
```bash
uvx --with flet==0.86.1 flet-mcp-server
```
**2. Local Mode** — point the tools at your project's virtualenv, so they read
its flet (and only its flet) no matter what the server bundles:
```json
{
"mcpServers": {
"flet-mcp-server": {
"command": "uvx",
"args": ["flet-mcp-server"],
"env": { "FLET_MCP_VENV": "/absolute/path/to/your/project/.venv" }
}
}
}
```
Every tool response then reports e.g. `[flet 0.86.5 — FLET_MCP_VENV=…/project/.venv]`,
and `inspect_flet_control` shows deprecations relative to that version.
## Client Configuration Examples
### VSCode
Add this to your `.vscode/mcp.json`:
```json
{
"servers": {
"flet-mcp-server": {
"command": "uvx",
"args": ["flet-mcp-server"]
}
}
}
```
### Antigravity
Add this to your `mcp_config.json`:
```json
{
"mcpServers": {
"flet-mcp-server": {
"command": "uvx",
"args": ["flet-mcp-server"]
}
}
}
```
### Claude Desktop
Add this to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"flet-mcp-server": {
"command": "uvx",
"args": ["flet-mcp-server"]
}
}
}
```
### Cursor / Windsurf
In your IDE's MCP settings, add a new server:
* **Name**: Flet MCP
* **Type**: Command
* **Command**: `uvx flet-mcp-server`
### Zed
Add this to your `settings.json` file inside the `context_servers` object:
```jsonc
{
"flet": {
"command": "uvx",
"args": ["flet-mcp-server"],
"env": {}
}
}
```
### OpenCode
Add this to your `~/.config/opencode/opencode.json` or project-level `.opencode/opencode.json`:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"flet-mcp": {
"type": "local",
"command": ["uvx", "flet-mcp-server"],
"enabled": true
}
}
}
```
## Configuration
| Variable | Default | Purpose |
|---|---|---|
| `FLET_MCP_VENV` | *(unset)* | Read flet from this project venv instead of the bundled one (Local Mode). |
| `FLET_MCP_TRANSPORT` | `stdio` | `stdio`, `sse`, or `streamable-http` (uses the bundled uvicorn). |
| `FLET_MCP_HOST` | `127.0.0.1` | Bind host for HTTP transports. |
| `FLET_MCP_PORT` | `8000` | Bind port for HTTP transports. |
| `GITHUB_TOKEN` | *(unset)* | Authenticated GitHub API access — higher rate limits. |
| `FLET_REPO` | `flet-dev/flet` | Docs source repo. |
| `FLET_BRANCH` | `main` | Docs source branch. |
| `FLET_MCP_CACHE_DIR` | `~/.cache/flet-mcp` | HTTP cache location (XDG-aware). |
Docker / remote deployments: run with `FLET_MCP_TRANSPORT=streamable-http
FLET_MCP_HOST=0.0.0.0` — a `GET /health` liveness endpoint is included.
OpenTelemetry traces are emitted automatically by the MCP SDK; configure any
standard `OTEL_*` environment variables to export them.
## Development
```bash
git clone https://github.com/Nwokike/flet-mcp-server.git
cd flet-mcp-server
uv sync
uv run pytest # unit tests (75)
uv run ruff check src/ tests/ scripts/ # lint
uv run python scripts/smoke_stdio.py # full MCP handshake from a fresh uvx env
```
The smoke script is the regression test for the v0.2.0 outage: it installs the
server into a clean ephemeral environment (exactly what end users get) and
verifies the handshake plus one call per tool group.
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture and
[CHANGELOG.md](CHANGELOG.md) for release history.
## License
MIT