Refactor MCP server for FastMCP and update documentation

Rewrote and streamlined the MCP server to use FastMCP as the core, removed legacy FastAPI/HTTP API code, and improved argument parsing for transport selection. Updated and condensed README.md, and added a new, comprehensive README_NEW.md with clear instructions, architecture, and usage examples for FastMCP transports and CLI. The server now focuses on FastMCP transports (stdio, http, streamable-http, sse) and provides improved logging and configuration.

Author: Fr4nc3

src/backend/v3/mcp_server/README.md

@@ -1,76 +1,14 @@
 # MACAE MCP Server
 
-A unified Model Context Protocol (MCP) server for the Multi-Agent Custom Automation Engine (MACAE) solution accelerator.
+A FastMCP-based Model Context Protocol (MCP) server for the Multi-Agent Custom Automation Engine (MACAE) solution accelerator.
 
 ## Features
 
-- **Unified Server**: Single `mcp_server.py` supporting both HTTP API and MCP protocol
-  -# Get HR tools (with auth if enabled)
-  curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:9000/tools/hr
-
-````
-
-## MCP Client Usage
-
-For MCP clients, connect to the MCP server:
-
-```python
-from fastmcp import Client
-
-client = Client("http://localhost:9000")
-
-async with client:
-    result = await client.call_tool("greet", {"name": "World"})
-    print(result)
-````
-
-### Quick Test
-
-**Test HTTP API mode:**
-
-```bash
-# Start the HTTP server
-python mcp_server.py --mode http
-
-# In another terminal, test the API
-curl http://localhost:9000/tools | jq
-curl -X POST http://localhost:9000/tools/list_employees | jq
-```
-
-**Test MCP Protocol mode:**
-
-```bash
-# Start the MCP server
-python mcp_server.py --mode mcp
-
-# Test with the included client
-python client_example.py
-```
-
-**Test with FastMCP CLI (recommended for MCP clients):**
-
-```bash
-# Using fastmcp run command (streamable HTTP transport)
-fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG
-
-# Or use the helper script
-python run_fastmcp.py
-
-# Server will be available at: http://127.0.0.1:9000/mcp/
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Import Errors**: Make sure you're in the correct directory and dependencies are installed
-2. **Authentication Errors**: Check your Azure AD configuration and tokens
-3. **Port Conflicts**: Change the port in configuration if 9000 is already in use
-4. **Missing fastmcp**: Install with `pip install fastmcp`**Factory Pattern**: Reusable MCP tools factory for easy service management
-
+- **FastMCP Server**: Pure FastMCP implementation supporting multiple transport protocols
+- **Factory Pattern**: Reusable MCP tools factory for easy service management
 - **Domain-Based Organization**: Services organized by business domains (HR, Tech Support, etc.)
 - **Authentication**: Optional Azure AD authentication support
-- **Dual Protocol Support**: HTTP API (FastAPI) and MCP protocol in one server
+- **Multiple Transports**: STDIO, HTTP (Streamable), and SSE transport support
 - **Docker Support**: Containerized deployment with health checks
 - **VS Code Integration**: Debug configurations and development settings
 - **Comprehensive Testing**: Unit tests with pytest
@@ -95,7 +33,7 @@ src/backend/v3/mcp_server/
 ├── config/                 # Configuration management
 │   ├── __init__.py
 │   └── settings.py        # Settings and configuration
-├── mcp_server.py          # Unified server (HTTP API + MCP protocol)
+├── mcp_server.py          # FastMCP server implementation
 ├── requirements.txt       # Python dependencies
 ├── uv.lock               # Lock file for dependencies
 ├── Dockerfile            # Container configuration
@@ -155,39 +93,50 @@ src/backend/v3/mcp_server/
 
 4. **Start the Server**:
 
-   ````bash
-   # HTTP API mode (default) - for REST clients
+   ```bash
+   # Default STDIO transport (for local MCP clients)
    python mcp_server.py
 
-   # MCP protocol mode - for MCP clients
-   python mcp_server.py --mode mcp
+   # HTTP transport (for web-based clients)
+   python mcp_server.py --transport http --port 9000
 
-   # FastMCP CLI (recommended for MCP clients) - streamable HTTP transport
+   # Using FastMCP CLI (recommended)
    fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG
 
    # Debug mode with authentication disabled
-   python mcp_server.py --debug --no-auth
-   ```### Server Modes
-   ````
+   python mcp_server.py --transport http --debug --no-auth
+   ```
 
-**The unified `mcp_server.py` supports two modes:**
+### Transport Options
 
-**1. HTTP API Mode (default)**
+**1. STDIO Transport (default)**
+- 🔧 Perfect for: Local tools, command-line integrations, Claude Desktop
+- 🚀 Usage: `python mcp_server.py` or `python mcp_server.py --transport stdio`
 
-- 🌐 FastAPI-based REST API
-- 📚 Automatic Swagger/OpenAPI documentation
-- 🔗 CORS support for web clients
-- 🔧 HTTP endpoints for all MCP tools
-- 💡 Perfect for: Web apps, curl, Postman, REST clients
-- 🌐 **Port: 9000**
+**2. HTTP (Streamable) Transport**
+- 🌐 Perfect for: Web-based deployments, microservices, remote access
+- 🚀 Usage: `python mcp_server.py --transport http --port 9000`
+- 🌐 URL: `http://127.0.0.1:9000/mcp/`
 
-**2. MCP Protocol Mode**
+**3. SSE Transport (deprecated)**
+- ⚠️ Legacy support only - use HTTP transport for new projects
+- 🚀 Usage: `python mcp_server.py --transport sse --port 9000`
 
-- 🤖 Model Context Protocol compliant
-- ⚡ Direct tool invocation protocol
-- 🔌 MCP client compatibility
-- 💡 Perfect for: AI agents, MCP-compatible clients
-- 🌐 **Port: 9000**
+### FastMCP CLI Usage
+
+```bash
+# Standard HTTP server
+fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG
+
+# With custom host
+fastmcp run mcp_server.py -t streamable-http --host 0.0.0.0 --port 9000 -l DEBUG
+
+# STDIO transport (for local clients)
+fastmcp run mcp_server.py -t stdio
+
+# Development mode with MCP Inspector
+fastmcp dev mcp_server.py -t streamable-http --port 9000
+```
 
 ### Docker Deployment
 
@@ -197,10 +146,9 @@ src/backend/v3/mcp_server/
    docker-compose up --build
    ```
 
-2. **Access the API**:
-   - Health check: http://localhost:9000/health
-   - API docs: http://localhost:9000/docs (when debug=true)
-   - Tools summary: http://localhost:9000/tools
+2. **Access the Server**:
+   - MCP endpoint: http://localhost:9000/mcp/
+   - Health check available via custom routes
 
 ### VS Code Development
 
@@ -211,8 +159,8 @@ src/backend/v3/mcp_server/
    ```
 
 2. **Use Debug Configurations**:
-   - `Debug MCP Server (MCP mode)`: Run the server in MCP protocol mode
-   - `Debug HTTP Server (HTTP mode)`: Run the server in HTTP API mode
+   - `Debug MCP Server (STDIO)`: Run with STDIO transport
+   - `Debug MCP Server (HTTP)`: Run with HTTP transport
    - `Debug Tests`: Run the test suite
 
 ## Configuration
@@ -295,40 +243,73 @@ pytest --cov=. src/tests/mcp_server/
 pytest src/tests/mcp_server/test_hr_service.py -v
 ```
 
-## API Endpoints (HTTP Server)
+## MCP Client Usage
+
+### Python Client
+
+```python
+from fastmcp import Client
 
-### Available Endpoints
+# Connect to HTTP server
+client = Client("http://localhost:9000")
 
-- `GET /`: Server information
-- `GET /health`: Health check
-- `GET /tools`: Get all tools summary
-- `GET /tools/{domain}`: Get tools for specific domain
+async with client:
+    # List available tools
+    tools = await client.list_tools()
+    print(f"Available tools: {[tool.name for tool in tools]}")
+    
+    # Call a tool
+    result = await client.call_tool("greet", {"name": "World"})
+    print(result)
+```
 
-### Example API Calls
+### Command Line Testing
 
 ```bash
-# Health check
-curl http://localhost:9000/health
+# Test the server is running
+curl http://localhost:9000/mcp/
 
-# Get tools summary
-curl http://localhost:9000/tools
+# With FastMCP CLI for testing
+fastmcp dev mcp_server.py -t streamable-http --port 9000
+```
+
+## Quick Test
+
+**Test STDIO Transport:**
+
+```bash
+# Start server in STDIO mode
+python mcp_server.py --debug --no-auth
 
-# Get HR tools (with auth if enabled)
-curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8000/tools/hr
+# Test with client_example.py
+python client_example.py
 ```
 
-## MCP Client Usage
+**Test HTTP Transport:**
 
-For MCP clients, connect to the FastMCP server:
+```bash
+# Start HTTP server
+python mcp_server.py --transport http --port 9000 --debug --no-auth
 
-```python
+# Test with FastMCP client
+python -c "
 from fastmcp import Client
+import asyncio
+async def test():
+    async with Client('http://localhost:9000') as client:
+        result = await client.call_tool('greet', {'name': 'Test'})
+        print(result)
+asyncio.run(test())
+"
+```
 
-client = Client("http://localhost:8000")
+**Test with FastMCP CLI:**
 
-async with client:
-    result = await client.call_tool("greet", {"name": "World"})
-    print(result)
+```bash
+# Start with FastMCP CLI
+fastmcp run mcp_server.py -t streamable-http --port 9000 -l DEBUG
+
+# Server will be available at: http://127.0.0.1:9000/mcp/
 ```
 
 ## Troubleshooting
@@ -337,13 +318,19 @@ async with client:
 
 1. **Import Errors**: Make sure you're in the correct directory and dependencies are installed
 2. **Authentication Errors**: Check your Azure AD configuration and tokens
-3. **Port Conflicts**: Change the port in configuration if 8000 is already in use
+3. **Port Conflicts**: Change the port in configuration if 9000 is already in use
 4. **Missing fastmcp**: Install with `pip install fastmcp`
 
 ### Debug Mode
 
 Enable debug mode for detailed logging:
 
+```bash
+python mcp_server.py --debug --no-auth
+```
+
+Or set in environment:
+
 ```env
 MCP_DEBUG=true
 ```
@@ -356,6 +343,23 @@ Check container logs:
 docker-compose logs mcp-server
 ```
 
+## Server Arguments
+
+```bash
+usage: mcp_server.py [-h] [--transport {stdio,http,streamable-http,sse}] 
+                     [--host HOST] [--port PORT] [--debug] [--no-auth]
+
+MACAE MCP Server
+
+options:
+  -h, --help            show this help message and exit
+  --transport, -t       Transport protocol (default: stdio)
+  --host HOST           Host to bind to for HTTP transport (default: 127.0.0.1)
+  --port, -p PORT       Port to bind to for HTTP transport (default: 9000)
+  --debug               Enable debug mode
+  --no-auth             Disable authentication
+```
+
 ## Contributing
 
 1. Follow the existing code structure and patterns