flet-mcp-server 0.1.0__tar.gz

flet_mcp_server-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+        
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+        
+    - name: Install dependencies
+      run: uv sync --dev
+
+    - name: Run tests
+      run: uv run pytest

flet_mcp_server-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/p/flet-mcp-server
+    
+    # Required for PyPI Trusted Publisher authentication
+    permissions:
+      id-token: write
+      contents: read
+      
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        
+      - name: Build distributions
+        run: uv build
+        
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

flet_mcp_server-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

flet_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Onyeka Nwokike
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flet_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: flet-mcp-server
+Version: 0.1.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
+
+# Flet MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+An auto-updating Model Context Protocol (MCP) server that dynamically fetches, caches, and serves the official Flet documentation and ecosystem packages directly from GitHub and PyPI.
+
+## Features
+
+*   **GitHub Tree Sync**: Maps documentation in real-time.
+*   **Intelligent Caching**: Uses `diskcache` for fast responses.
+*   **Ecosystem Discovery**: Finds and verifies official and community Flet packages.
+*   **AI-Optimized**: Tool definitions designed for LLM understanding.
+
+## Tools Included
+
+### 1. `list_flet_controls`
+List all available Flet UI controls.
+
+### 2. `search_flet_docs(query)`
+Search the documentation index.
+
+### 3. `get_flet_doc(doc_path)`
+Get raw Markdown for a specific doc.
+
+### 4. `list_official_packages()`
+List official Flet extension packages.
+
+### 5. `search_flet_ecosystem(query)`
+Search for verified community Flet components.
+
+### 6. `get_package_details(package_name)`
+Fetch version and installation info from PyPI.
+
+## Client Configuration Examples
+
+### 🌌 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`
+
+## Development
+
+### Install
+```bash
+git clone https://github.com/Nwokike/flet-mcp-server.git
+cd flet-mcp-server
+uv sync
+```
+
+### Test
+```bash
+uv run pytest
+```
+
+## License
+MIT

flet_mcp_server-0.1.0/README.md

@@ -0,0 +1,86 @@
+# Flet MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+An auto-updating Model Context Protocol (MCP) server that dynamically fetches, caches, and serves the official Flet documentation and ecosystem packages directly from GitHub and PyPI.
+
+## Features
+
+*   **GitHub Tree Sync**: Maps documentation in real-time.
+*   **Intelligent Caching**: Uses `diskcache` for fast responses.
+*   **Ecosystem Discovery**: Finds and verifies official and community Flet packages.
+*   **AI-Optimized**: Tool definitions designed for LLM understanding.
+
+## Tools Included
+
+### 1. `list_flet_controls`
+List all available Flet UI controls.
+
+### 2. `search_flet_docs(query)`
+Search the documentation index.
+
+### 3. `get_flet_doc(doc_path)`
+Get raw Markdown for a specific doc.
+
+### 4. `list_official_packages()`
+List official Flet extension packages.
+
+### 5. `search_flet_ecosystem(query)`
+Search for verified community Flet components.
+
+### 6. `get_package_details(package_name)`
+Fetch version and installation info from PyPI.
+
+## Client Configuration Examples
+
+### 🌌 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`
+
+## Development
+
+### Install
+```bash
+git clone https://github.com/Nwokike/flet-mcp-server.git
+cd flet-mcp-server
+uv sync
+```
+
+### Test
+```bash
+uv run pytest
+```
+
+## License
+MIT

flet_mcp_server-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,21 @@
+# Architecture
+
+The Flet MCP Server is built with a focus on speed, reliability, and real-time data.
+
+## Components
+
+### 1. `FastMCP` Interface
+Uses the official Python SDK to expose tools via the Model Context Protocol.
+
+### 2. Documentation Service (`github_docs.py`)
+*   Uses the GitHub Git Tree API to fetch documentation structure.
+*   Caches content locally to minimize network latency.
+
+### 3. Package Service (`packages.py`)
+*   Scrapes official extensions from the Flet repository.
+*   Searches GitHub for community packages.
+*   **PyPI Verification**: Cross-references GitHub search results with PyPI metadata to ensure packages actually depend on `flet`.
+*   **Classification**: Automatically classifies packages as "UI Control" or "Service Integration" based on summary analysis.
+
+### 4. Caching Layer
+Uses `diskcache` to store responses for 24 hours, ensuring near-instant tool execution for the AI agent.

flet_mcp_server-0.1.0/docs/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing to Flet MCP Server
+
+We welcome contributions! 
+
+## How to Contribute
+
+1.  **Fork the repository** on GitHub.
+2.  **Clone your fork** locally.
+3.  **Create a new branch** for your feature or bugfix.
+4.  **Install dependencies** using `uv sync`.
+5.  **Write tests** for your changes.
+6.  **Run tests** with `uv run pytest`.
+7.  **Submit a Pull Request**.
+
+## Standards
+
+*   Use `ruff` for linting.
+*   Ensure all tests pass.
+*   Keep documentation updated.

flet_mcp_server-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "flet-mcp-server"
+version = "0.1.0"
+description = "Auto-updating MCP server for Flet documentation and packages"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Onyeka Nwokike", email = "nwokikeonyeka@gmail.com" }
+]
+keywords = ["flet", "mcp", "ai", "agent", "documentation", "github-api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "diskcache>=5.6.3",
+    "httpx>=0.28.1",
+    "mcp>=1.27.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/Nwokike/flet-mcp-server"
+Repository = "https://github.com/Nwokike/flet-mcp-server"
+Issues = "https://github.com/Nwokike/flet-mcp-server/issues"
+
+[project.scripts]
+flet-mcp-server = "flet_mcp.main:run_server"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flet_mcp"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.coverage.run]
+source = ["flet_mcp"]
+omit = ["tests/*", "**/tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if __name__ == .__main__.",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.12",
+]

flet_mcp_server-0.1.0/src/flet_mcp/main.py

@@ -0,0 +1,12 @@
+from flet_mcp.server import mcp
+
+def run_server():
+    """
+    Entry point for the uv script execution.
+    Runs the MCP server over standard input/output (stdio), 
+    which is the communication protocol required by desktop AI agents.
+    """
+    mcp.run(transport='stdio')
+
+if __name__ == "__main__":
+    run_server()

flet_mcp_server-0.1.0/src/flet_mcp/server.py

@@ -0,0 +1,72 @@
+from mcp.server.fastmcp import FastMCP
+from flet_mcp.services.github_docs import FletDocsFetcher
+from flet_mcp.services.packages import FletPackageFetcher
+
+# Initialize the FastMCP server
+mcp = FastMCP("Flet MCP Server")
+docs_fetcher = FletDocsFetcher()
+pkg_fetcher = FletPackageFetcher()
+
+# --- DOCUMENTATION TOOLS ---
+
+@mcp.tool()
+async def search_flet_docs(query: str) -> list[str]:
+    """
+    Search the official Flet documentation index for a specific topic or control.
+    Always use this first to find the correct file path before calling get_flet_doc.
+    
+    Args:
+        query: The keyword to search for (e.g., 'dropdown', 'navigation', 'layout').
+    """
+    return await docs_fetcher.search_docs(query)
+
+@mcp.tool()
+async def get_flet_doc(doc_path: str) -> str:
+    """
+    Fetch the full Markdown documentation for a specific Flet control or topic.
+    
+    Args:
+        doc_path: The exact path to the doc file, usually obtained from search_flet_docs 
+                  (e.g., 'website/docs/controls/dropdown/index.md').
+    """
+    return await docs_fetcher.get_doc_content(doc_path)
+
+@mcp.tool()
+async def list_flet_controls() -> list[str]:
+    """
+    Get a complete list of all available Flet UI controls.
+    Use this to discover what UI elements can be built in Flet.
+    """
+    return await docs_fetcher.list_flet_controls()
+
+# --- ECOSYSTEM & PACKAGE TOOLS ---
+
+@mcp.tool()
+async def list_official_packages() -> list[str]:
+    """
+    Get a list of all official Flet extension packages (e.g. flet-audio, flet-video).
+    Use this to see what official extra capabilities Flet supports outside the core library.
+    """
+    return await pkg_fetcher.list_official_packages()
+
+@mcp.tool()
+async def search_flet_ecosystem(query: str) -> list[dict]:
+    """
+    Search the open-source community for third-party Flet packages and components.
+    Use this when the user wants to add a feature (e.g., 'calendar', 'table', 'auth') 
+    that might not be in the core Flet library.
+    
+    Args:
+        query: The keyword to search for (e.g., 'calendar').
+    """
+    return await pkg_fetcher.search_flet_ecosystem(query)
+
+@mcp.tool()
+async def get_package_details(package_name: str) -> str:
+    """
+    Fetch PyPI details, current version, and installation instructions for a specific Flet package.
+    
+    Args:
+        package_name: The exact name of the package on PyPI (e.g., 'flet-audio').
+    """
+    return await pkg_fetcher.get_package_details(package_name)

flet_mcp_server-0.1.0/src/flet_mcp/services/github_docs.py

@@ -0,0 +1,98 @@
+import os
+import httpx
+import diskcache
+
+# Set up a persistent local cache in the user's home directory
+# This prevents us from getting rate-limited by GitHub when the AI asks multiple questions
+CACHE_DIR = os.path.expanduser("~/.cache/flet-mcp")
+cache = diskcache.Cache(CACHE_DIR)
+
+class FletDocsFetcher:
+    """Fetches and caches Flet documentation from the official GitHub repo."""
+
+    def __init__(self):
+        self.client = httpx.AsyncClient(timeout=10.0)
+        self.headers = {
+            "Accept": "application/vnd.github.v3+json",
+            "User-Agent": "Flet-MCP-Server/0.1.0"
+        }
+        # If the user has a GITHUB_TOKEN, use it to vastly expand API limits
+        if token := os.getenv("GITHUB_TOKEN"):
+            self.headers["Authorization"] = f"Bearer {token}"
+
+    async def _fetch_json(self, url: str) -> dict | list | None:
+        """Helper to fetch and cache JSON responses (24-hour TTL)."""
+        if url in cache:
+            return cache[url]
+
+        response = await self.client.get(url, headers=self.headers)
+        if response.status_code == 200:
+            data = response.json()
+            cache.set(url, data, expire=86400)  # 86400 seconds = 24 hours
+            return data
+        return None
+
+    async def _fetch_text(self, url: str) -> str | None:
+        """Helper to fetch and cache raw Markdown text (24-hour TTL)."""
+        if url in cache:
+            return cache[url]
+
+        response = await self.client.get(url)
+        if response.status_code == 200:
+            text = response.text
+            cache.set(url, text, expire=86400)
+            return text
+        return None
+
+    async def get_docs_tree(self) -> list[str]:
+        """Gets a flat list of all Markdown documentation paths in the Flet repo."""
+        # The Tree API is the most efficient way to get all files in a repo at once
+        repo_api_url = "https://api.github.com/repos/flet-dev/flet/git/trees/main?recursive=1"
+        data = await self._fetch_json(repo_api_url)
+
+        if not data or "tree" not in data:
+            return []
+
+        # Filter out everything except markdown files in the docs folder
+        doc_paths = [
+            item["path"] for item in data["tree"]
+            if item["path"].startswith("website/docs/") and item["path"].endswith(".md")
+        ]
+        return doc_paths
+
+    async def get_doc_content(self, file_path: str) -> str:
+        """Fetches the raw Markdown content for a specific Flet doc file."""
+        # Use raw.githubusercontent for fast, quota-free raw file fetching
+        raw_url = f"https://raw.githubusercontent.com/flet-dev/flet/main/{file_path}"
+        content = await self._fetch_text(raw_url)
+
+        if content:
+            return content
+        return f"Error: Could not fetch documentation for {file_path}. Ensure the path is correct."
+
+    async def search_docs(self, query: str) -> list[str]:
+        """A keyword search over the available document paths."""
+        all_docs = await self.get_docs_tree()
+        query_lower = query.lower()
+
+        # Filter paths that contain the query string 
+        # e.g., querying "dropdown" will match "docs/docs/controls/dropdown.md"
+        matches = [path for path in all_docs if query_lower in path.lower()]
+        return matches
+
+    async def list_flet_controls(self) -> list[str]:
+        """Returns a list of all available Flet UI controls."""
+        all_docs = await self.get_docs_tree()
+        
+        # Filter only the files that live in the controls directory
+        controls = []
+        for path in all_docs:
+            if "website/docs/controls/" in path:
+                # Extract just the control name from the path (e.g., 'dropdown/index.md' -> 'dropdown')
+                parts = path.split("website/docs/controls/")
+                if len(parts) > 1:
+                    clean_name = parts[1].split("/")[0].replace(".md", "")
+                    if clean_name not in controls:
+                        controls.append(clean_name)
+        
+        return sorted(controls)