update readme

Author: DidierRLopes

38-vanilla-agent-mcp-tools/README.md

@@ -1,40 +1,74 @@
-# Vanilla Agent with Custom Features
+# Vanilla Agent with MCP Tools
 
-This is a simple example agent that demonstrates how to detect and report which custom features are enabled or disabled in the OpenBB Workspace UI.
+This agent demonstrates how to integrate and use Model Context Protocol (MCP) tools within an OpenBB agent, enabling dynamic tool execution for enhanced functionality.
 
 ## What it does
 
 This agent:
-- Greets users with a friendly hello message
-- Reports the status of custom features (Deep Research and Web Search) 
-- Shows whether each feature is enabled (✅) or disabled (❌) based on the UI settings
+- Detects and lists available MCP tools from connected MCP servers
+- Executes MCP tools with proper parameter handling
+- Formats responses clearly separating MCP tool output from AI analysis
+- Supports real-time tool execution through the OpenBB frontend
 
-## Features
+## Key Features
 
-The agent defines two custom features in its configuration:
-- **Deep Research**: Allows the agent to perform deep research (default: disabled)
-- **Web Search**: Allows the agent to search the web (default: enabled)
+### MCP Tool Integration
+- **Automatic Tool Detection**: Discovers MCP tools from connected servers
+- **Parameter Schema Support**: Validates and passes parameters based on tool schemas
+- **Server Management**: Handles multiple MCP servers with proper server ID mapping
+- **Error Handling**: Graceful fallbacks when tools are unavailable or fail
 
-Users can toggle these features on/off in the OpenBB Workspace UI, and the agent will detect and report the current status.
+### Response Formatting
+All responses with MCP tool data are structured as:
+```
+## MCP OUTPUT
+[Raw data from MCP tool execution]
+
+## AI OUTPUT
+[AI analysis and interpretation of the tool results]
+```
+
+This clear separation helps users distinguish between actual tool data and AI-generated insights.
+
+## Supported MCP Tools
+
+This example works with any MCP tools, but includes specific support for:
+- **OpenBB Docs Tools**: For querying OpenBB documentation
+- **Data Retrieval Tools**: For fetching structured data
+- **Analysis Tools**: For processing and analyzing information
 
-## Getting started
+## How MCP Integration Works
+
+1. **Tool Discovery**: Agent detects available MCP tools from connected servers
+2. **Schema Parsing**: Reads tool input schemas to understand required parameters
+3. **Function Definition**: Creates OpenAI function definitions for each tool
+4. **Execution Flow**: 
+   - User requests action requiring external data
+   - Agent calls appropriate MCP tool with parameters
+   - Frontend executes tool on MCP server
+   - Results returned and formatted for user
+5. **Response Generation**: AI analyzes tool output and provides insights
+
+## Getting Started
 
 ### Prerequisites
 
-Ensure you have poetry, a tool for dependency management and packaging in Python, as well as your OpenAI API key.
+- Poetry for dependency management
+- OpenAI API key
+- MCP server with tools configured in OpenBB Terminal Pro
 
 ### Installation and Running
 
 1. Clone this repository to your local machine.
 
-2. Set the OpenAI API key as an environment variable in your .bashrc or .zshrc file:
+2. Set the OpenAI API key as an environment variable:
 
     ``` sh
     # in .zshrc or .bashrc
     export OPENAI_API_KEY=<your-api-key>
     ```
 
-3. Install the necessary dependencies:
+3. Install dependencies:
 
 ``` sh
 poetry install --no-root
@@ -43,22 +77,65 @@ poetry install --no-root
 4. Start the API server:
 
 ``` sh
-cd 37-vanilla-agent-custom-features
-poetry run uvicorn vanilla_agent_custom_features.main:app --port 7777 --reload
+cd 38-vanilla-agent-mcp-tools
+poetry run uvicorn vanilla_agent_mcp_tools.main:app --port 7777 --reload
 ```
 
-This command runs the FastAPI application, making it accessible on your network.
+### Testing MCP Integration
+
+To test MCP tool functionality:
 
-### Testing the Agent
+1. Ensure you have MCP tools configured in OpenBB Terminal Pro
+2. Ask the agent: "What MCP tools do you have available?"
+3. Request tool execution: "Use [tool_name] to search for [query]"
+4. Observe the structured output with MCP OUTPUT and AI OUTPUT sections
 
-The example agent has a small, basic test suite to ensure it's working correctly. As you develop your agent, you are highly encouraged to expand these tests.
+### Running Tests
 
-You can run the tests with:
+The agent includes tests for MCP tool integration:
 
 ```sh
 pytest tests
 ```
 
-### Accessing the Documentation
+### Configuration
+
+The agent automatically configures MCP tool support through:
+- **Feature Flag**: `"mcp-tools": true` in the agent configuration
+- **Tool Detection**: Automatic discovery from `request.tools`
+- **Parameter Mapping**: Dynamic schema-based parameter validation
+
+## API Documentation
+
+Access the interactive API documentation at: http://localhost:7777/docs
+
+## Example Usage
+
+```
+User: "What MCP tools do you have available?"
+Agent: Lists all detected MCP tools with descriptions and parameters
+
+User: "Use the docs tool to find information about widgets"
+Agent: 
+## MCP OUTPUT
+[Documentation search results from MCP tool]
+
+## AI OUTPUT
+Based on the documentation search, here's what I found about widgets...
+```
+
+## Architecture
+
+- **FastAPI Backend**: Handles requests and MCP tool orchestration
+- **OpenAI Integration**: Uses function calling for tool selection
+- **MCP Protocol**: Standard protocol for external tool communication
+- **Structured Output**: Clear separation of tool data and AI analysis
+
+## Debugging
+
+The agent includes comprehensive debugging output:
+- Tool discovery and server mapping
+- Parameter validation and transmission
+- Response processing and formatting
 
-Once the API server is running, you can view the documentation and interact with the API by visiting: http://localhost:7777/docs
+Enable debug mode by checking server logs for `[DEBUG]` messages.