docs: Add comprehensive guide for creating MCP tools with Gradio and Python

docs/mcp_with_gradio.md

@@ -0,0 +1,143 @@
+# Creating MCP Tools with Gradio and Python
+
+This document provides a detailed explanation of how to build a Model Context Protocol (MCP) tool server using Python and Gradio. We will use a simple sentiment analysis function as a practical example to illustrate the process of exposing Python functions as MCP tools.
+
+## 1. Project Overview
+
+This project demonstrates how to build a Model Context Protocol (MCP) tool server using Python and Gradio. We will use a simple sentiment analysis function as a practical example to illustrate the process of exposing Python functions as MCP tools.
+
+The primary focus is to show how Gradio can automatically create an MCP tool from a Python function, making it accessible to MCP clients like LLM-based agents. The sentiment analysis function serves as a concrete illustration of this capability, rather than being the central subject itself.
+
+## 2. Core Technologies
+
+### a. Python
+The project is written in Python, a versatile and widely-used programming language, particularly popular in web development, data science, and machine learning.
+
+### b. Gradio
+[Gradio](https://www.gradio.app/) is a Python library that makes it easy to create and share web-based UIs for machine learning models, Python functions, or any arbitrary Python code. Key features relevant to this project include:
+*   **Rapid UI Development**: Quickly build interactive demos.
+*   **Variety of Input/Output Components**: Supports text boxes, sliders, images, JSON, etc.
+*   **Automatic MCP Server Integration**: Can automatically expose Python functions as MCP tools, which is the core focus of this demonstration.
+
+### c. Model Context Protocol (MCP)
+[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) is a standard designed to allow language models (LLMs) and other AI agents to interact with external tools and resources in a structured way.
+Key concepts of MCP include:
+*   **Resources**: File-like data that can be read by clients (e.g., API responses, file contents).
+*   **Tools**: Functions (like our example sentiment analysis function) that can be called by an LLM or agent (with user approval) to perform actions or retrieve information.
+*   **Prompts**: Pre-written templates that help users accomplish specific tasks with an LLM.
+
+#### Gradio MCP Integration
+Gradio simplifies the creation of MCP servers by:
+1.  **Automatic Tool Conversion**: Python functions provided to a Gradio Interface are automatically converted into MCP Tools.
+2.  **Schema Mapping**: Input components (like `gr.Textbox`) are mapped to the tool's argument schemas. Docstrings and type hints in the Python function further refine this schema.
+3.  **Response Formatting**: Output components (like `gr.JSON`) determine the response format of the MCP tool.
+4.  **Communication Protocol**: Sets up JSON-RPC over HTTP+SSE (Server-Sent Events) for client-server communication.
+5.  **Dual Endpoints**: Creates both a user-facing web interface and an MCP server endpoint from the same Python function.
+
+### d. TextBlob (for the example function)
+[TextBlob](https://textblob.readthedocs.io/) is a Python library for processing textual data. In this project, we use it *solely to provide a simple example function* for sentiment analysis. Its specific NLP capabilities are secondary to its role as an illustrative function to be exposed via MCP.
+
+## 3. Code Breakdown (`server.py`)
+
+Let's examine the `server.py` file. The core idea is to define a Python function and then use Gradio to expose it as an MCP tool.
+
+```python
+import gradio as gr
+from textblob import TextBlob # For our example function
+```
+*   **`import gradio as gr`**: Imports the Gradio library.
+*   **`from textblob import TextBlob`**: Imports `TextBlob` for our example `sentiment_analysis` function.
+
+```python
+# This is the example Python function we will expose as an MCP tool.
+def sentiment_analysis(text: str) -> dict:
+    """
+    Analyze the sentiment of the given text.
+    (This docstring is used by Gradio for the MCP tool description)
+
+    Args:
+        text (str): The text to analyze (used for MCP tool input schema)
+
+    Returns:
+        dict: A dictionary containing polarity, subjectivity, and assessment (used for MCP tool output schema)
+    """
+    # The internal logic of this function is an example.
+    # Any Python function can be exposed similarly.
+    blob = TextBlob(text)
+    sentiment = blob.sentiment
+
+    return {
+        "polarity": round(sentiment.polarity, 2),
+        "subjectivity": round(sentiment.subjectivity, 2),
+        "assessment": "positive"
+        if sentiment.polarity > 0
+        else "negative"
+        if sentiment.polarity < 0
+        else "neutral",
+    }
+```
+*   **`def sentiment_analysis(text: str) -> dict:`**: Defines our example function.
+    *   **`text: str` (Type Hint)**: Gradio uses this (along with the input component) to define the MCP tool's input argument type and schema.
+    *   **`-> dict` (Return Type Hint)**: Gradio uses this (along with the output component) for the MCP tool's output schema.
+    *   **Docstring**: Crucially, Gradio uses the docstring to generate the description for the MCP tool, its arguments (`Args`), and what it returns (`Returns`). This makes the tool understandable to MCP clients.
+*   The internal logic using `TextBlob` is specific to this example. The key is that *any* well-documented Python function with type hints can be similarly exposed by Gradio.
+
+```python
+# Create the Gradio interface to expose the function
+demo = gr.Interface(
+    fn=sentiment_analysis, # The Python function to expose as an MCP tool
+    inputs=gr.Textbox(placeholder="Enter text to analyze..."), # Defines UI and helps MCP schema
+    outputs=gr.JSON(), # Defines UI output and MCP tool output type
+    title="MCP Tool Server Example (Sentiment Analysis)",
+    description="Demonstrates exposing a Python function as an MCP tool via Gradio.",
+)
+```
+*   **`demo = gr.Interface(...)`**: Creates a Gradio Interface.
+    *   **`fn=sentiment_analysis`**: Specifies the Python function that Gradio will wrap and expose as an MCP tool.
+    *   **`inputs=gr.Textbox(...)`**: Defines the input component for the optional web UI and helps Gradio infer the input schema for the MCP tool (expecting a string for the `text` argument).
+    *   **`outputs=gr.JSON()`**: Defines the output component for the web UI and signals to Gradio that the MCP tool will return a JSON structure (matching the `dict` return type).
+
+```python
+# Launch the interface and the MCP server
+if __name__ == "__main__":
+    demo.launch(mcp_server=True) # Key parameter to enable MCP
+```
+*   **`demo.launch(mcp_server=True)`**: This launches the Gradio web UI and, most importantly for this demonstration, starts the MCP server.
+    *   **`mcp_server=True`**: This parameter explicitly tells Gradio to expose the function (`sentiment_analysis`) defined in `gr.Interface` as an MCP tool.
+
+## 4. Running the Server
+
+To start the server:
+1.  Open your terminal or command prompt.
+2.  Navigate to the directory containing `server.py`.
+3.  Ensure you have the necessary libraries installed (`pip install gradio textblob`).
+4.  Run the command: `python server.py`
+
+Upon successful execution, you will see output similar to:
+```
+Running on local URL:  http://127.0.0.1:7860
+Running on MCP server at: http://127.0.0.1:7860/gradio_api/mcp/sse
+```
+*   **Web Interface**: An optional web UI is available at `http://127.0.0.1:7860`.
+*   **MCP Server Endpoint**: The MCP server, exposing the `sentiment_analysis` function as a tool, is available at `http://127.0.0.1:7860/gradio_api/mcp/sse`. MCP clients connect here.
+
+## 5. How Gradio Exposes Functions as MCP Tools (Illustrated by the Example)
+
+1.  **Tool Creation**: When `demo.launch(mcp_server=True)` is called, Gradio inspects the Python function (in this case, `sentiment_analysis`) provided to `gr.Interface`.
+2.  **Schema Generation**: Gradio automatically generates the MCP tool's schema:
+    *   The Python function's name (`sentiment_analysis`) becomes the MCP tool's name.
+    *   The function's docstring is used for the tool's description, arguments, and return value explanations.
+    *   Input components (e.g., `gr.Textbox`) and Python type hints (e.g., `text: str`) define the tool's input arguments and their types.
+    *   Output components (e.g., `gr.JSON()`) and Python return type hints (e.g., `-> dict`) define the tool's output structure and type.
+3.  **Server Endpoint**: Gradio hosts an HTTP server that listens for MCP requests at the `/gradio_api/mcp/sse` path. Communication typically uses JSON-RPC over HTTP with Server-Sent Events (SSE).
+4.  **Client Interaction**: An MCP client can:
+    *   Connect to the MCP server endpoint.
+    *   Request a list of available tools (it would find `sentiment_analysis` with its generated schema).
+    *   Call the tool by sending a request matching the schema (e.g., providing a string for the `text` argument).
+    *   Receive the JSON response as defined by the tool's output schema.
+
+## 6. Conclusion
+
+This project primarily demonstrates the ease with which Python functions can be exposed as Model Context Protocol (MCP) tools using Gradio. The sentiment analysis function served as a straightforward example to illustrate this process.
+
+The key takeaway is Gradio's capability to automatically handle MCP tool creation, schema generation from docstrings and type hints, and server endpoint setup. This significantly simplifies the development of MCP-compatible services, allowing developers to focus on their core Python logic while Gradio manages the MCP integration. Any Python function can be similarly exposed, making Gradio a powerful utility for extending the capabilities of LLMs and other AI agents through MCP.