First commit as a hackathon submission, will improve it if I have time :)

.gitignore

@@ -0,0 +1,196 @@
+.env
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

README.md

@@ -8,6 +8,69 @@ sdk_version: 5.33.0
 app_file: app.py
 pinned: false
 short_description: A little app with a smolagent to explore and test MCP Tools
+tags:
+  - agent-demo-track
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🚀 MCP Explorer
+
+**Project submitted for the [Agents-MCP-Hackathon – June 2025](https://huggingface.co/Agents-MCP-Hackathon)**  
+Explore, test, and debug any MCP-compatible server — in one simple interface.
+
+---
+
+## 🧩 What is MCP Explorer?
+
+**MCP Explorer** is a Gradio-based tool built to help participants of the MCP Hackathon (and beyond) interact with the Model Context Protocol ecosystem.
+
+It allows you to:
+
+- 🔍 Discover and visualize tools exposed by any MCP server
+- 🧪 Test real-time prompts using a `smolagent` powered by `Qwen 32B`
+- 🔄 Automatically refresh the list of tools from any endpoint
+- 🧠 Browse available tools in a clean interactive table
+- 🌍 Quickly switch between hackathon candidates and custom endpoints
+
+---
+
+## 🎯 Features
+
+| Feature                           | Description                                                                 |
+|----------------------------------|-----------------------------------------------------------------------------|
+| 🔧 **Live MCP querying**          | Send a prompt and let the agent reason using the selected MCP tools        |
+| 📊 **Structured tool viewer**     | Display each tool's name, description, and input schema in a readable way  |
+| 🔀 **Endpoint selector**          | Toggle between hackathon submissions or custom MCP server URLs             |
+| ⚡ **Auto-refresh on load**       | Automatically pulls tools on app startup                                   |
+| 🗃 **Tool index builder (bonus)** | Aggregates all MCP tools from the hackathon into a single `parquet` file   |
+
+---
+
+## 🧪 How to use it
+
+1. Clone or open the Space.
+2. Select a known MCP server or paste a custom one.
+3. Click “🔄 Refresh MCP tools list” to load the available tools.
+4. Type a natural language prompt — the agent will use the tools if applicable.
+
+---
+
+## 📦 Bonus: MCP Tool Index
+
+In the `src/bonus.py` module, you'll find `extracthackathontools()` —  
+a utility that scans all `mcp-server` tagged Spaces from the hackathon and builds a global index of available tools in `hackathon_mcp_tools.parquet`.
+
+---
+
+## 🧠 Credits
+
+Built by [Ali Hmaou](https://huggingface.co/alihmaou)  
+With gratitude to the Hugging Face team for the amazing infrastructure, API access, and documentation.
+
+
+---
+
+## 🛠 Tech stack
+
+- Python, Gradio
+- `smolagents`, `Qwen 32B`, `pandas`
+- MCP Protocol (streamable-http)

app.py

@@ -0,0 +1,145 @@
+import gradio as gr
+import os
+from mcp import StdioServerParameters
+from smolagents import InferenceClientModel, CodeAgent, MCPClient
+import pandas as pd
+import requests
+
+DEFAULT_MCP_URL = "https://alihmaou-mcp-tools.hf.space/gradio_api/mcp/sse"
+HF_TOKEN = os.getenv("HUGGINGFACE_API_TOKEN")
+
+def get_mcp_space_endpoints():
+    """Fetch MCP-compatible Spaces from the HF Hackathon org."""
+    try:
+        resp = requests.get("https://huggingface.co/api/spaces?author=Agents-MCP-Hackathon")
+        resp.raise_for_status()
+        spaces = resp.json()
+    except Exception as e:
+        print(f"[Warning] Failed to fetch MCP spaces: {e}")
+        return [DEFAULT_MCP_URL]
+
+    endpoints = [DEFAULT_MCP_URL]  
+    for space in spaces:
+        if "mcp-server" in space.get("tags", []):
+            full_id = space["id"]  
+            slug = full_id.replace("/", "-").replace("_", "-").lower()
+            endpoint = f"https://{slug}.hf.space/gradio_api/mcp/sse"
+            if endpoint != DEFAULT_MCP_URL:
+                endpoints.append(endpoint)
+    return endpoints
+
+def reload_tools_from_url(mcp_url_input):
+    global tools, agent, mcp_client, mcp_url
+
+    mcp_url=mcp_url_input
+    
+    try:
+        mcp_client = MCPClient({"url": mcp_url,"transport": "sse"}) # Might be deprecated soon but didnt find out the clean way
+        tools = mcp_client.get_tools()
+        
+        model = InferenceClientModel(token=os.getenv("HUGGINGFACE_API_TOKEN"))
+        agent = CodeAgent(tools=tools, model=model,)
+    except Exception as e:
+        print(f"[Warning] Failed to reach MCP server: {e}")
+
+    # Tableau structuré : nom, description, inputs attendus
+    rows = []
+    for tool in tools:
+        input_fields = ", ".join(param for param in tool.inputs)
+        rows.append({
+            "Tool name": tool.name,
+            "Description": tool.description,
+            "Params": input_fields
+        })
+        df = pd.DataFrame(rows)
+    return gr.DataFrame(value=df)
+
+with gr.Blocks() as demo:
+    gr.Markdown("""
+                <div align="center">
+                    <h1>🚀 MCP Tools Explorer – Agents-MCP-Hackathon (June 2025)</h1>
+                    <p>
+                    🔍 Query any MCP-compatible endpoint, 🛠️ browse available tools in a clean table view, and 🤖 test real-time interactions using a `smolagent` powered by `HuggingFace`.  <br/>
+                    Perfect for 🧪 exploring fellow participants’ tools or 🧰 debugging your own MCP server during the event! </br>
+                    🍒 As a cherry on the cake, the list of the tools developed for the hackathon will be updated here from time to time (see src/bonus.py) : <a href="https://huggingface.co/datasets/alihmaou/Agents_MCP_Hackathon_Tools_List/blob/main/hackathon_mcp_tools.parquet">Ready to use hackathon MCP tools list</a>
+                    </p>
+                </div>
+                """,)
+    
+    with gr.Row():
+        
+        with gr.Column(scale=1):
+            gr.Markdown("""
+                <div align="center">
+                    <h2>🛠️ Set an MCP server and discover its tools</h2>
+                </div>
+                """)
+            source_selector = gr.Radio(
+                choices=["Hackathon candidates", "Custom MCP URL"],
+                label="🔀 Source",
+                value="Hackathon candidates"
+            )
+            
+            hackathon_dropdown = gr.Dropdown(
+                label="Select a MCP server from the hackathon organisation",
+                choices=get_mcp_space_endpoints(),
+                value=DEFAULT_MCP_URL,
+                interactive=True,
+                visible=True
+            )
+
+            custom_url_input = gr.Textbox(
+                label="Enter custom MCP server URL",
+                value="https://agents-mcp-hackathon-mcp-server-demo.hf.space/gradio_api/mcp/sse",
+                visible=False
+            )
+            
+            def toggle_url_input(source):
+                return (
+                    gr.update(visible=(source == "Hackathon candidates")),
+                    gr.update(visible=(source == "Custom MCP URL"))
+                )
+                
+            def reload_tools_router(source, dropdown_val, custom_val):
+                selected_url = dropdown_val if source == "Hackathon candidates" else custom_val
+                return reload_tools_from_url(selected_url)
+
+            source_selector.change(fn=toggle_url_input, inputs=source_selector, outputs=[hackathon_dropdown, custom_url_input])
+            
+            #print("[MCP] Endpoints loaded:", get_mcp_space_endpoints())
+            tool_table = gr.DataFrame(headers=["Tool name", "Description", "Params"], interactive=False, label="🔧 MCP Tools availables", wrap=True)
+            reload_btn = gr.Button("🔄 Refresh and set MCP tools list")
+            reload_btn.click(
+                fn=reload_tools_router,
+                inputs=[source_selector, hackathon_dropdown, custom_url_input],
+                outputs=tool_table
+            )
+            hackathon_dropdown.change(
+                fn=reload_tools_router,
+                inputs=[source_selector, hackathon_dropdown, custom_url_input],
+                outputs=tool_table
+            )
+            custom_url_input.submit(
+                fn=reload_tools_router,
+                inputs=[source_selector, hackathon_dropdown, custom_url_input],
+                outputs=tool_table
+            ) 
+            
+        with gr.Column(scale=2):
+            gr.Markdown("""
+                <div align="center">
+                    <h2>🔎 Test them with smolagents</h2>
+                </div>
+                """)
+            chatbot = gr.ChatInterface(
+                fn=lambda message, history: str(agent.run(message)),
+                type="messages", 
+            )
+
+demo.launch()
+
+try:
+    if mcp_client:
+        mcp_client.disconnect()
+except Exception as e:
+    print(f"[Warning] Failed to disconnect MCP client: {e}")

data/hackathon_mcp_tools.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:68e00574e01656199f29d490355f2adc9486ff07a97105ab0b44c823ba59e0d9
+size 40653

requirements.txt

@@ -0,0 +1,8 @@
+smolagents[mcp]
+gradio [mcp]
+mcp
+fastmcp
+python-dotenv
+pandas
+pyarrow
+fastparquet

src/bonus.py

@@ -0,0 +1,71 @@
+import requests
+import pandas as pd
+from smolagents import MCPClient
+
+
+
+def extracthackathontools():
+    """Scrape all MCP tools from hackathon Spaces and return as a pandas DataFrame to allow download as a bonus feature of the MCP Explorer."""
+    HF_API = "https://huggingface.co/api/spaces?author=Agents-MCP-Hackathon"
+
+    try:
+        resp = requests.get(HF_API)
+        resp.raise_for_status()
+    except Exception as e:
+        raise RuntimeError(f"Failed to fetch Spaces list: {e}")
+
+    spaces = resp.json()
+    rows = []
+
+    for space in spaces:
+        tags = space.get("tags", [])
+        if "mcp-server" not in tags:
+            continue
+
+        space_id = space["id"]  
+        space_slug = space_id.replace("/", "-").replace("_", "-").lower()
+        mcp_base_url = f"https://{space_slug}.hf.space/gradio_api/mcp/sse"
+            
+
+        try:
+            print(mcp_base_url)
+            #mcp_status = requests.get(mcp_base_url, timeout=5)
+            #print(mcp_status.status_code)
+            #if mcp_status.status_code != 200:
+            #    print(f"[Skip] Space in error: {mcp_base_url}")
+            #    continue
+            
+            mcp_client = MCPClient({"url": mcp_base_url,"transport": "sse"}) # Might be deprecated soon but didnt find out the clean way
+            tools = mcp_client.get_tools()
+            print(len(tools))
+            mcp_client.disconnect()
+        except Exception as e:
+            print(f"[Warning] Could not fetch tools from {mcp_base_url}: {e}")
+            continue
+
+        # Infos générales du Space
+        author, name = space_id.split("/")
+        hf_url = f"https://huggingface.co/spaces/{space_id}"
+        created_at = space.get("createdAt", "")
+        n_likes = space.get("likes", 0)
+
+        for tool in tools:
+            input_fields = ", ".join(param for param in tool.inputs)
+            rows.append({
+                "Gradio MCP endpoint": f"{mcp_base_url}",
+                "Tool name": tool.name,
+                "Tool description": tool.description,
+                "Tool inputs": input_fields,
+                "Space name": name,
+                "HF Space URL": hf_url,
+                "Likes": n_likes,
+                "Created at": created_at,
+                "Tags": ", ".join(tags)
+            })
+
+    df = pd.DataFrame(rows)
+    return df
+
+df=extracthackathontools()
+
+df.to_parquet("./data/hackathon_mcp_tools.parquet", index=False)