From ab7f3ecaaa2fc7d319068d01460c945a5ef662ab Mon Sep 17 00:00:00 2001
From: MervinPraison <praison.ms@gmail.com>
Date: Tue, 13 May 2025 16:40:20 +0100
Subject: [PATCH] Add STDIO MCP documentation and update navigation menu

---
 docs/mcp/stdio.mdx | 221 +++++++++++++++++++++++++++++++++++++++++++++
 docs/mint.json     |   1 +
 2 files changed, 222 insertions(+)
 create mode 100644 docs/mcp/stdio.mdx

diff --git a/docs/mcp/stdio.mdx b/docs/mcp/stdio.mdx
new file mode 100644
index 000000000..7f387c5de
--- /dev/null
+++ b/docs/mcp/stdio.mdx
@@ -0,0 +1,221 @@
+---
+title: "MCP STDIO Integration"
+sidebarTitle: "MCP STDIO"
+description: "Guide for integrating Standard Input/Output (STDIO) with PraisonAI agents using MCP"
+icon: "terminal"
+---
+
+## Add STDIO Tool to AI Agent
+
+```mermaid
+flowchart LR
+    In[In] --> Agent[AI Agent]
+    Agent --> Tool[STDIO MCP]
+    Tool --> Agent
+    Agent --> Out[Out]
+    
+    style In fill:#8B0000,color:#fff
+    style Agent fill:#2E8B57,color:#fff
+    style Tool fill:#000000,color:#fff
+    style Out fill:#8B0000,color:#fff
+```
+
+## Quick Start
+
+<Steps>
+    <Step title="Create a client file">
+        Create a new file `calculator_client.py` with the following code:
+        ```python
+        from praisonaiagents import Agent, MCP
+
+        calculator_agent = Agent(
+            instructions="""You are a calculator agent that can perform basic arithmetic operations.""",
+            llm="gpt-4o-mini",
+            tools=MCP("python calculator_server.py")
+        )
+
+        calculator_agent.start("What is 25 * 16?")
+        ```
+    </Step>
+
+    <Step title="Set Up STDIO MCP Server">
+        Create a file `calculator_server.py` with the following code:
+        ```python
+        # calculator_server.py
+        from mcp.server.fastmcp import FastMCP
+        import logging
+        import sys
+
+        # Set up logging
+        logging.basicConfig(level=logging.INFO, filename="calculator_server.log")
+        logger = logging.getLogger("calculator-server")
+
+        # Initialize FastMCP server for simple tools
+        mcp = FastMCP("calculator-tools")
+
+        @mcp.tool()
+        def add(a: float, b: float) -> float:
+            """Add two numbers.
+
+            Args:
+                a: First number
+                b: Second number
+            
+            Returns:
+                The sum of a and b
+            """
+            logger.info(f"Adding {a} + {b}")
+            return a + b
+
+        @mcp.tool()
+        def subtract(a: float, b: float) -> float:
+            """Subtract b from a.
+
+            Args:
+                a: First number
+                b: Second number
+            
+            Returns:
+                The result of a - b
+            """
+            logger.info(f"Subtracting {b} from {a}")
+            return a - b
+
+        @mcp.tool()
+        def multiply(a: float, b: float) -> float:
+            """Multiply two numbers.
+
+            Args:
+                a: First number
+                b: Second number
+            
+            Returns:
+                The product of a and b
+            """
+            logger.info(f"Multiplying {a} * {b}")
+            return a * b
+
+        @mcp.tool()
+        def divide(a: float, b: float) -> float:
+            """Divide a by b.
+
+            Args:
+                a: First number (numerator)
+                b: Second number (denominator)
+            
+            Returns:
+                The result of a / b
+            """
+            if b == 0:
+                raise ValueError("Cannot divide by zero")
+            logger.info(f"Dividing {a} / {b}")
+            return a / b
+
+        if __name__ == "__main__":
+            # Run the MCP server using STDIO transport
+            mcp.run()
+        ```
+    </Step>
+
+    <Step title="Install Dependencies">
+        Make sure you have the required packages installed:
+        ```bash
+        pip install "praisonaiagents[llm]" mcp
+        ```
+    </Step>
+    <Step title="Export API Key">
+        ```bash
+        export OPENAI_API_KEY="your_api_key"
+        ```
+    </Step>
+
+    <Step title="Run the Agent">
+        Run the agent which will automatically start the calculator server:
+        ```bash
+        python calculator_client.py
+        ```
+    </Step>
+</Steps>
+
+<Note>
+  **Requirements**
+  - Python 3.10 or higher
+  - MCP package
+</Note>
+
+## Alternative LLM Integrations
+
+### Using Groq with STDIO
+
+```python
+from praisonaiagents import Agent, MCP
+
+calculator_agent = Agent(
+    instructions="""You are a calculator agent that can perform basic arithmetic operations.""",
+    llm="groq/llama-3.2-90b-vision-preview",
+    tools=MCP("python calculator_server.py")
+)
+
+calculator_agent.start("What is 144 divided by 12?")
+```
+
+### Using Ollama with STDIO
+
+```python
+from praisonaiagents import Agent, MCP
+
+calculator_agent = Agent(
+    instructions="""You are a calculator agent that can perform basic arithmetic operations.""",
+    llm="ollama/llama3.2",
+    tools=MCP("python calculator_server.py")
+)
+
+calculator_agent.start("What is 15 + 27? Use the add tool with parameters a and b.")
+```
+
+## Gradio UI Integration
+
+Create a Gradio UI for your calculator service:
+
+```python
+from praisonaiagents import Agent, MCP
+import gradio as gr
+
+def calculate(query):
+    calculator_agent = Agent(
+        instructions="""You are a calculator agent that can perform basic arithmetic operations.""",
+        llm="gpt-4o-mini",
+        tools=MCP("python calculator_server.py")
+    )
+
+    result = calculator_agent.start(query)
+    return f"## Calculation Result\n\n{result}"
+
+demo = gr.Interface(
+    fn=calculate,
+    inputs=gr.Textbox(placeholder="What is 25 * 16?"),
+    outputs=gr.Markdown(),
+    title="Calculator MCP Agent",
+    description="Ask any arithmetic question:"
+)
+
+if __name__ == "__main__":
+    demo.launch()
+```
+
+## Features
+
+<CardGroup cols={2}>
+  <Card title="Simple Integration" icon="plug">
+    Use standard input/output for easy integration with any tool or service.
+  </Card>
+  <Card title="Cross-Platform" icon="laptop">
+    Works on any operating system that supports Python.
+  </Card>
+  <Card title="Multiple LLM Options" icon="brain">
+    Use with OpenAI, Groq, Ollama, or other supported LLMs.
+  </Card>
+  <Card title="Gradio UI" icon="window">
+    Create user-friendly interfaces for your STDIO integrations.
+  </Card>
+</CardGroup>
diff --git a/docs/mint.json b/docs/mint.json
index 0e30277f4..daa771c56 100644
--- a/docs/mint.json
+++ b/docs/mint.json
@@ -238,6 +238,7 @@
       "group": "MCP",
       "pages": [
         "mcp/airbnb",
+        "mcp/stdio",
         "mcp/sse",
         "mcp/ollama",
         "mcp/groq",