flet-mcp-server 0.1.0__py3-none-any.whl

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.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/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)

flet_mcp/services/packages.py

@@ -0,0 +1,131 @@
+import os
+import httpx
+import diskcache
+
+CACHE_DIR = os.path.expanduser("~/.cache/flet-mcp")
+cache = diskcache.Cache(CACHE_DIR)
+
+class FletPackageFetcher:
+    def __init__(self):
+        self.client = httpx.AsyncClient(timeout=15.0)
+        self.github_headers = {
+            "Accept": "application/vnd.github.v3+json",
+            "User-Agent": "Flet-MCP-Server/0.1.0"
+        }
+        if token := os.getenv("GITHUB_TOKEN"):
+            self.github_headers["Authorization"] = f"Bearer {token}"
+
+    _FALLBACK_OFFICIAL = [
+        "flet-ads", "flet-audio", "flet-audio-recorder", "flet-camera",
+        "flet-charts", "flet-code-editor", "flet-color-pickers", "flet-datatable2",
+        "flet-flashlight", "flet-geolocator", "flet-lottie", "flet-map",
+        "flet-permission-handler", "flet-rive", "flet-secure-storage",
+        "flet-video", "flet-webview"
+    ]
+
+    async def _fetch_json(self, url: str, headers: dict | None = None) -> dict | None:
+        if url in cache:
+            return cache[url]
+        try:
+            response = await self.client.get(url, headers=headers)
+            if response.status_code == 200:
+                data = response.json()
+                cache.set(url, data, expire=86400)
+                return data
+        except Exception:
+            pass
+        return None
+
+    async def list_official_packages(self) -> list[str]:
+        """Scrapes the Flet monorepo to find all official extensions."""
+        url = "https://api.github.com/repos/flet-dev/flet/git/trees/main?recursive=1"
+        data = await self._fetch_json(url, headers=self.github_headers)
+        
+        if not data or "tree" not in data:
+            return self._FALLBACK_OFFICIAL 
+
+        packages = []
+        for item in data["tree"]:
+            path = item["path"]
+            if path.startswith("sdk/python/packages/") and item["type"] == "tree":
+                parts = path.split("/")
+                if len(parts) == 4: 
+                    packages.append(parts[3])
+                    
+        return sorted(list(set(packages))) if packages else self._FALLBACK_OFFICIAL
+
+    async def _is_true_flet_package(self, package_name: str) -> bool:
+        """Verifies PyPI metadata to ensure the package actually depends on flet."""
+        url = f"https://pypi.org/pypi/{package_name}/json"
+        data = await self._fetch_json(url)
+        
+        if not data or "info" not in data:
+            return False
+            
+        requires_dist = data["info"].get("requires_dist")
+        if not requires_dist:
+            # Some packages might be Flet related but not strictly depend on 'flet' in metadata
+            # but for a 'strict' check we require it.
+            return False
+            
+        for req in requires_dist:
+            # Clean up requirement string (e.g. 'flet (>=0.1.0) ; extra == "all"')
+            dep_name = req.split(";")[0].split(" ")[0].split(">")[0].split("=")[0].split("<")[0]
+            base_name = dep_name.split("[")[0].strip().lower()
+            if base_name == "flet":
+                return True
+        return False
+
+    async def search_flet_ecosystem(self, query: str) -> list[dict]:
+        """Searches GitHub for third-party Flet packages and verifies them."""
+        search_query = f"flet {query} language:python"
+        url = f"https://api.github.com/search/repositories?q={search_query}&sort=stars&order=desc&per_page=15"
+        
+        data = await self._fetch_json(url, headers=self.github_headers)
+        if not data or "items" not in data:
+            return []
+
+        results = []
+        for item in data["items"]:
+            # Check if this GitHub repo is actually a published PyPI package depending on flet
+            repo_name = item["name"]
+            is_verified = await self._is_true_flet_package(repo_name)
+            
+            results.append({
+                "name": repo_name,
+                "full_name": item["full_name"],
+                "description": item["description"],
+                "stars": item["stargazers_count"],
+                "url": item["html_url"],
+                "is_verified_flet_package": is_verified
+            })
+        return results
+
+    async def get_package_details(self, package_name: str) -> str:
+        """Fetches detailed package info and installation instructions from PyPI."""
+        url = f"https://pypi.org/pypi/{package_name}/json"
+        data = await self._fetch_json(url)
+        
+        if not data or "info" not in data:
+            return f"Package '{package_name}' not found on PyPI."
+
+        info = data["info"]
+        version = info.get("version", "Unknown")
+        summary = info.get("summary", "No summary available.")
+        
+        # Smart Classification
+        pkg_type = "Python Package"
+        summary_lower = summary.lower()
+        if "control" in summary_lower or "widget" in summary_lower or "ui" in summary_lower:
+            pkg_type = "UI Control"
+        elif "service" in summary_lower or "auth" in summary_lower or "database" in summary_lower:
+            pkg_type = "Service Integration"
+
+        details = (
+            f"Package: {package_name} (v{version})\n"
+            f"Type: {pkg_type}\n"
+            f"Summary: {summary}\n\n"
+            f"Installation:\n```bash\n"
+            f"uv add {package_name}\n```\n"
+        )
+        return details

flet_mcp_server-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+flet_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flet_mcp/main.py,sha256=DyPZy9vB9RMrl0_ft8W2b2u9kexli_aOwQmG86l3QL4,320
+flet_mcp/server.py,sha256=YqvocNPUm3jMnBf7H_IP8yv7bKOMdqbnWnBlpF3Oea0,2485
+flet_mcp/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flet_mcp/services/github_docs.py,sha256=XfhssrS7HWL-w13uPK2L69TiqKxUeFufrYrtrB5p9qI,4043
+flet_mcp/services/packages.py,sha256=jS3uXzJ6-Tjrh8ZKH5-e6Wn-g_qa9VWPGBF1DAkELNI,5338
+flet_mcp_server-0.1.0.dist-info/METADATA,sha256=L9Fda4GoB6j3-aZqI_L2cFAdRF40LxfKtui9uFhOOC4,3203
+flet_mcp_server-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+flet_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=GvbVY1sP95qcsikhGlsXfEKcnJbqm0BNJLgjdeYUoHE,61
+flet_mcp_server-0.1.0.dist-info/licenses/LICENSE,sha256=0nUZjabbuM34H2XHsAfhYFnhNF4baiGt9ufHQWfIvP4,1071
+flet_mcp_server-0.1.0.dist-info/RECORD,,

flet_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

flet_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flet-mcp-server = flet_mcp.main:run_server

flet_mcp_server-0.1.0.dist-info/licenses/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.