Metadata-Version: 2.4
Name: flet-mcp-server
Version: 0.2.0
Summary: Auto-updating MCP server for Flet documentation and packages
Project-URL: Homepage, https://github.com/Nwokike/flet-mcp-server
Project-URL: Repository, https://github.com/Nwokike/flet-mcp-server
Project-URL: Issues, https://github.com/Nwokike/flet-mcp-server/issues
Author-email: Onyeka Nwokike <nwokikeonyeka@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,ai,documentation,flet,github-api,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: diskcache>=5.6.3
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.27.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'test'
Requires-Dist: pytest-cov>=7.1.0; extra == 'test'
Requires-Dist: pytest>=9.0.3; extra == 'test'
Requires-Dist: ruff>=0.15.12; extra == 'test'
Description-Content-Type: text/markdown

<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">Flet MCP Server</h1>

<p align="center">
  <em>Model Context Protocol that serves official Flet resources to 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 MCP Server dynamically fetches and serves official Flet documentation, controls, packages, and ecosystem resources for AI agents and MCP-compatible clients.
<div align="center">

[![Nwokike/flet-mcp-server MCP server](https://glama.ai/mcp/servers/Nwokike/flet-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/Nwokike/flet-mcp-server)

</div>

## Features

* **GitHub Tree Sync**: Maps documentation in real-time from the Flet repository.
* **Intelligent Caching**: Uses `diskcache` for fast responses with 24-hour TTL.
* **Smart Search**: Fuzzy matching, keyword aliases, and direct path search over documentation.
* **Ecosystem Discovery**: Finds and verifies official and community Flet packages via PyPI metadata.
* **AI-Optimized**: Tool definitions designed for LLM understanding with clear usage guidance.
* **Configurable**: Supports custom Flet repo/branch via environment variables.
* **Resource Safe**: Shared HTTP client with proper lifecycle management and graceful shutdown.

## Tools Included

### 1. `list_flet_controls`
List all available Flet UI controls.

### 2. `search_flet_docs(query)`
Search the documentation index with fuzzy matching and keyword aliases.

### 3. `get_flet_doc(doc_path)`
Get raw Markdown for a specific doc file.

### 4. `list_official_packages()`
List official Flet extension packages from the monorepo.

### 5. `search_flet_ecosystem(query)`
Search for verified community Flet components on GitHub.

### 6. `get_package_details(package_name)`
Fetch version, type classification, and installation info from PyPI.

## Client Configuration Examples

### 🌌 VSCode
Add this to your `.vscode/mcp.json`:

```json
{
  "servers": {
    "flet-mcp-server": {
      "command": "uvx",
      "args": ["flet-mcp-server"]
    }
  }
}
```

### 🌌 Antigravity / Cascade
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`

### 💻 OpenCode
Add this to your `~/.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
    }
  }
}
```

For authenticated GitHub API access (higher rate limits), set `GITHUB_TOKEN` in your environment:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flet-mcp": {
      "type": "local",
      "command": ["uvx", "flet-mcp-server"],
      "enabled": true,
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `FLET_MCP_CACHE_DIR` | `/tmp/flet-mcp-cache` | Directory for persistent cache storage |
| `GITHUB_TOKEN` | *(none)* | GitHub personal access token for higher API rate limits |
| `FLET_REPO` | `flet-dev/flet` | GitHub repository to fetch docs from |
| `FLET_BRANCH` | `main` | Branch or tag to fetch docs from |

## Development

### Directory Structure
```text
flet-mcp-server/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── publish.yml
├── docs/
│   ├── ARCHITECTURE.md
│   └── CONTRIBUTING.md
├── src/
│   └── flet_mcp/
│       ├── services/
│       │   ├── github_docs.py
│       │   ├── packages.py
│       │   └── __init__.py
│       ├── __init__.py
│       ├── exceptions.py
│       ├── http.py
│       ├── main.py
│       └── server.py
├── tests/
│   └── test_fetcher.py
├── LICENSE
├── README.md
├── pyproject.toml
└── uv.lock
```

### Install
```bash
git clone https://github.com/Nwokike/flet-mcp-server.git
cd flet-mcp-server
uv sync
```

### Test
```bash
uv run pytest
```

### Lint
```bash
uv run ruff check .
```

## Changelog

### v0.2.0
- **Smart Search**: Added fuzzy matching, keyword alias index, and multi-strategy search (direct > alias > fuzzy)
- **Shared HTTP Client**: Single `httpx.AsyncClient` with proper lifecycle management via server lifespan
- **Custom Exceptions**: `DocNotFoundError`, `PackageNotFoundError`, `FetchError`, `TreeFetchError` for better error handling
- **Configurable Repo/Branch**: `FLET_REPO` and `FLET_BRANCH` environment variables for version pinning
- **Robust Control Parsing**: Set-based deduplication with safer path parsing
- **Concurrent Verification**: Batched PyPI verification with semaphore-based rate limiting for ecosystem search
- **Graceful Shutdown**: Server lifespan handler cleans up HTTP connections
- **Better Error Handling**: All tools catch and format errors gracefully for LLM consumption
- **Mocked Tests**: Full test suite with mocked HTTP responses for fast, reliable CI
- **OpenCode Support**: Added OpenCode MCP configuration example to README
- **Expanded Fallback**: Added `flet`, `flet-cli`, `flet-desktop`, `flet-web` to fallback package list

<details>
<summary>v0.1.1</summary>

- Initial release with 6 MCP tools
- GitHub Tree API integration with diskcache
- PyPI verification for ecosystem packages

</details>

## License
MIT
