DOCS: fix MCP tool example scripts; add docs about HTTP transport

Author: mdw771

README.md

@@ -188,6 +188,28 @@ mcp_tool = MCPTool(
 )
 ```
 
+Use an MCP server over HTTP from another machine:
+
+```python
+from eaa.tool.mcp import MCPTool
+
+mcp_tool = MCPTool(
+    {
+        "mcpServers": {
+            "calculator": {
+                "url": "http://SERVER_IP:8050/mcp",
+                "transport": "http",
+            }
+        }
+    }
+)
+```
+
+For this remote HTTP setup, the server side must be started with
+``run_mcp_server_from_tools(..., transport="http", host="0.0.0.0", port=8050, path="/mcp")``.
+The client config must keep the server definition under ``mcpServers``; passing
+only ``{"url": ..., "transport": "http"}`` is not enough.
+
 ## Skills
 
 Skills are reusable, markdown-first task packages that EAA can discover and

docs/tools.rst

@@ -93,6 +93,45 @@ interface.
 
    task_manager.register_tools(mcp_tool)
 
+To connect to an MCP server over HTTP from a different machine, configure the
+client with a named entry under ``mcpServers`` and point it at the server's MCP
+endpoint:
+
+.. code-block:: python
+
+   from eaa.tool.mcp import MCPTool
+
+   mcp_tool = MCPTool(
+       {
+           "mcpServers": {
+               "calculator": {
+                   "url": "http://SERVER_IP:8050/mcp",
+                   "transport": "http",
+               }
+           }
+       }
+   )
+
+The server side should be started with HTTP transport enabled, for example:
+
+.. code-block:: python
+
+   from eaa.core.mcp.server import run_mcp_server_from_tools
+   from eaa.tool.example_calculator import CalculatorTool
+
+   run_mcp_server_from_tools(
+       tools=CalculatorTool(),
+       server_name="Calculator MCP Server",
+       transport="http",
+       host="0.0.0.0",
+       port=8050,
+       path="/mcp",
+   )
+
+Do not pass only ``{"url": ..., "transport": "http"}`` to ``MCPTool``. The
+FastMCP client expects a full config object with one or more named servers
+inside ``mcpServers``.
+
 Notes:
 
 - EAA normalizes tool results to JSON for tools served through the EAA MCP

examples/mcp_calculator_server.py

@@ -12,14 +12,15 @@
 divide, get_history, clear_history) as MCP tools.
 """
 
-import sys
 import logging
+import inspect
+import sys
 from pathlib import Path
 
 # Add the src directory to the Python path
 sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
 
-from eaa.mcp import run_mcp_server_from_tools
+from eaa.core.mcp.server import run_mcp_server_from_tools
 from eaa.tool.example_calculator import CalculatorTool
 
 # Configure logging
@@ -31,18 +32,56 @@
 logger = logging.getLogger(__name__)
 
 
-def main():
+def log_available_tools(calculator: CalculatorTool) -> None:
+    """Log the exposed calculator tool methods."""
+    logger.info("Created calculator tool with the following methods:")
+    for spec in calculator.exposed_tools:
+        doc = inspect.getdoc(spec.function) or "No description"
+        logger.info("  - %s: %s", spec.name, doc.split(".")[0])
+
+
+def print_banner() -> None:
+    """Print usage information without corrupting stdio MCP transport."""
+    print(
+        """
+Calculator MCP Server Example
+============================
+
+This server exposes calculator operations as MCP tools:
+- add(a, b): Add two numbers
+- subtract(a, b): Subtract two numbers
+- multiply(a, b): Multiply two numbers
+- divide(a, b): Divide two numbers
+- get_history(): Get calculation history
+- clear_history(): Clear calculation history
+
+Connect this server to your MCP client (like Cursor) to use these tools
+in AI conversations.
+
+Press Ctrl+C to stop the server.
+""",
+        file=sys.stderr,
+    )
+
+
+def main() -> None:
     """Main function to run the MCP calculator server."""
     try:
         # Create the calculator tool
         calculator = CalculatorTool()
-        
-        logger.info("Created calculator tool with the following methods:")
-        for tool_dict in calculator.exposed_tools:
-            logger.info(f"  - {tool_dict['name']}: {tool_dict['function'].__doc__.split('.')[0] if tool_dict['function'].__doc__ else 'No description'}")
-        
+        log_available_tools(calculator)
+
         # Create and run the MCP server
         logger.info("Starting MCP server...")
+        # To expose this server over HTTP for remote clients instead of stdio, use:
+        # run_mcp_server_from_tools(
+        #     tools=calculator,
+        #     server_name="Calculator MCP Server",
+        #     transport="http",
+        #     host="0.0.0.0",
+        #     port=8000,
+        #     path="/mcp",
+        # )
         run_mcp_server_from_tools(
             tools=calculator,
             server_name="Calculator MCP Server",
@@ -56,22 +95,5 @@ def main():
 
 
 if __name__ == "__main__":
-    print("""
-    Calculator MCP Server Example
-    ============================
-    
-    This server exposes calculator operations as MCP tools:
-    - add(a, b): Add two numbers
-    - subtract(a, b): Subtract two numbers  
-    - multiply(a, b): Multiply two numbers
-    - divide(a, b): Divide two numbers
-    - get_history(): Get calculation history
-    - clear_history(): Clear calculation history
-    
-    Connect this server to your MCP client (like Cursor) to use these tools
-    in AI conversations.
-    
-    Press Ctrl+C to stop the server.
-    """)
-    
-    main() 
+    print_banner()
+    main()

src/eaa/tool/example_calculator.py

@@ -4,8 +4,8 @@
 This module provides a simple calculator tool that can be exposed via MCP.
 """
 
-from typing import List
 import logging
+from typing import Annotated, List
 
 from eaa.core.tooling.base import BaseTool, check, tool
 
@@ -35,7 +35,11 @@ def __init__(
         self.calculation_history: List[str] = []
 
     @tool(name="add")
-    def add(self, a: float, b: float) -> float:
+    def add(
+        self,
+        a: Annotated[float, "The first addend."],
+        b: Annotated[float, "The second addend."],
+    ) -> float:
         """
         Add two numbers together.
         
@@ -57,7 +61,11 @@ def add(self, a: float, b: float) -> float:
         return result
 
     @tool(name="subtract")
-    def subtract(self, a: float, b: float) -> float:
+    def subtract(
+        self,
+        a: Annotated[float, "The number to subtract from."],
+        b: Annotated[float, "The number to subtract."],
+    ) -> float:
         """
         Subtract the second number from the first.
         
@@ -79,7 +87,11 @@ def subtract(self, a: float, b: float) -> float:
         return result
 
     @tool(name="multiply")
-    def multiply(self, a: float, b: float) -> float:
+    def multiply(
+        self,
+        a: Annotated[float, "The first factor."],
+        b: Annotated[float, "The second factor."],
+    ) -> float:
         """
         Multiply two numbers together.
         
@@ -101,7 +113,11 @@ def multiply(self, a: float, b: float) -> float:
         return result
 
     @tool(name="divide")
-    def divide(self, a: float, b: float) -> float:
+    def divide(
+        self,
+        a: Annotated[float, "The dividend."],
+        b: Annotated[float, "The non-zero divisor."],
+    ) -> float:
         """
         Divide the first number by the second.