<p align="center">
  <a href="https://github.com/Nwokike/flet-mcp-server" target="_blank">
    <img src="https://raw.githubusercontent.com/flet-dev/flet/refs/heads/main/media/logo/flet-logo.svg" height="150" alt="Flet MCP Server logo">
  </a>
</p>

<h1 align="center">MCP Server</h1>

<p align="center">
  <em>MCP server that makes the installed Flet source code the source of truth for AI agents.</em>
</p>

<p align="center">
  <a href="https://pypi.org/project/flet-mcp-server/" target="_blank">
    <img src="https://img.shields.io/pypi/v/flet-mcp-server?color=%2334D058&label=PyPI" alt="PyPI version" />
  </a>
  <a href="https://pepy.tech/projects/flet-mcp-server" target="_blank">
    <img src="https://static.pepy.tech/personalized-badge/flet-mcp-server?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=Users" alt="Total users" />
  </a>
  <a href="https://github.com/Nwokike/flet-mcp-server/actions/workflows/ci.yml" target="_blank">
    <img src="https://github.com/Nwokike/flet-mcp-server/actions/workflows/ci.yml/badge.svg" alt="CI status" />
  </a>
  <a href="https://pypi.org/project/flet-mcp-server/" target="_blank">
    <img src="https://img.shields.io/badge/python-%3E%3D3.10-%2334D058" alt="Python >= 3.10" />
  </a>
  <a href="https://glama.ai/mcp/servers/Nwokike/flet-mcp-server" target="_blank">
    <img src="https://glama.ai/mcp/servers/Nwokike/flet-mcp-server/badges/score.svg" alt="MCP server score" />
  </a>
</p>

---

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://<module>` (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