diff --git a/docs/mcp/airbnb.mdx b/docs/mcp/airbnb.mdx new file mode 100644 index 000000000..71aba41a4 --- /dev/null +++ b/docs/mcp/airbnb.mdx @@ -0,0 +1,85 @@ +--- +title: "Airbnb MCP Integration" +sidebarTitle: "Airbnb" +description: "Guide for integrating Airbnb booking capabilities with PraisonAI agents using MCP" +icon: "airbnb" +--- + +# Airbnb MCP Integration + +```mermaid +flowchart LR + In[In] --> Agent[AI Agent] + Agent --> Tool[Airbnb MCP] + Tool --> Agent + Agent --> Out[Out] + + style In fill:#8B0000,color:#fff + style Agent fill:#2E8B57,color:#fff + style Tool fill:#FF5A5F,color:#fff + style Out fill:#8B0000,color:#fff +``` + +## Quick Start + + + + Set your OpenAI API key as an environment variable in your terminal: + ```bash + export OPENAI_API_KEY=your_openai_api_key_here + ``` + + + + Create a new file `airbnb_search.py` with the following code: + ```python + from praisonaiagents import Agent, MCP + + search_agent = Agent( + instructions="""You help book apartments on Airbnb.""", + llm="gpt-4o-mini", + tools=MCP("npx -y @openbnb/mcp-server-airbnb --ignore-robots-txt") + ) + + search_agent.start("I want to book an apartment in Paris for 2 nights. 03/28 - 03/30 for 2 adults") + ``` + + + + Make sure you have Node.js installed, as the MCP server requires it: + ```bash + pip install praisonaiagents + ``` + + + + Execute your script: + ```bash + python airbnb_search.py + ``` + + + + + **Requirements** + - Python 3.10 or higher + - Node.js installed on your system + - OpenAI API key (for the agent's LLM) + + +## Features + + + + Search for accommodations on Airbnb with natural language queries. + + + Seamless integration with Model Context Protocol. + + + Specify dates, guests, and location preferences in natural language. + + + Leverages the official Airbnb MCP server package. + + diff --git a/docs/mcp/bravesearch.mdx b/docs/mcp/bravesearch.mdx new file mode 100644 index 000000000..3906f638c --- /dev/null +++ b/docs/mcp/bravesearch.mdx @@ -0,0 +1,95 @@ +--- +title: "Brave Search MCP Integration" +sidebarTitle: "Brave Search" +description: "Guide for integrating Brave Search capabilities with PraisonAI agents using MCP" +icon: "searchengin" +--- + +# Brave Search MCP Integration + +```mermaid +flowchart LR + In[In] --> Agent[AI Agent] + Agent --> Tool[Brave Search MCP] + Tool --> Agent + Agent --> Out[Out] + + style In fill:#8B0000,color:#fff + style Agent fill:#2E8B57,color:#fff + style Tool fill:#4169E1,color:#fff + style Out fill:#8B0000,color:#fff +``` + +## Quick Start + + + + Set your Brave Search API key as an environment variable in your terminal: + ```bash + export BRAVE_API_KEY=your_brave_api_key_here + export OPENAI_API_KEY=your_openai_api_key_here + ``` + + You can obtain a Brave Search API key from [Brave Search API](https://brave.com/search/api/). + + + + Create a new file `brave_search.py` with the following code: + ```python + from praisonaiagents import Agent, MCP + import os + + # Use the API key from environment or set it directly + brave_api_key = os.getenv("BRAVE_API_KEY") or "your_brave_api_key_here" + + # Use a single string command with environment variables + search_agent = Agent( + instructions="""You are a helpful assistant that can search the web for information. + Use the available tools when relevant to answer user questions.""", + llm="gpt-4o-mini", + tools=MCP("npx -y @modelcontextprotocol/server-brave-search", env={"BRAVE_API_KEY": brave_api_key}) + ) + + search_agent.start("Search more information about AI News") + ``` + + + + Make sure you have Node.js installed, as the MCP server requires it: + ```bash + pip install praisonaiagents + ``` + + + + Execute your script: + ```bash + python brave_search.py + ``` + + + + + **Requirements** + - Python 3.10 or higher + - Node.js installed on your system + - Brave Search API key + - OpenAI API key (for the agent's LLM) + + +## Features + + + + Search the web for up-to-date information. + + + Seamless integration with Model Context Protocol. + + + Secure API key handling through environment variables. + + + Leverages the official Brave Search MCP server package. + + diff --git a/docs/mcp/custom.mdx b/docs/mcp/custom.mdx new file mode 100644 index 000000000..38344b015 --- /dev/null +++ b/docs/mcp/custom.mdx @@ -0,0 +1,170 @@ +--- +title: "Custom Python MCP Server" +sidebarTitle: "Custom Python MCP" +description: "Guide for creating and using custom Python MCP servers with PraisonAI agents" +icon: "python" +--- + +# Custom Python MCP Server + +```mermaid +flowchart LR + In[In] --> Agent[AI Agent] + Agent --> Tool[Custom Python MCP] + Tool --> Agent + Agent --> Out[Out] + + style In fill:#8B0000,color:#fff + style Agent fill:#2E8B57,color:#fff + style Tool fill:#3776AB,color:#fff + style Out fill:#8B0000,color:#fff +``` + +## Quick Start + + + + Create a new file `app.py` with your custom MCP server implementation: + ```python + import yfinance as yf + from mcp.server.fastmcp import FastMCP + + mcp = FastMCP("stock_prices") + + @mcp.tool() + async def get_stock_price(ticker: str) -> str: + """Get the current stock price for a given ticker symbol. + + Args: + ticker: Stock ticker symbol (e.g., AAPL, MSFT, GOOG) + + Returns: + Current stock price as a string + """ + if not ticker: + return "No ticker provided" + try: + stock = yf.Ticker(ticker) + info = stock.info + current_price = info.get('currentPrice') or info.get('regularMarketPrice') + if not current_price: + return f"Could not retrieve price for {ticker}" + return f"${current_price:.2f}" + + except Exception as e: + return f"Error: {str(e)}" + + if __name__ == "__main__": + mcp.run(transport='stdio') + ``` + + + + Install the required dependencies in a conda environment: + ```bash + conda create -n mcp python=3.10 + conda activate mcp + pip install yfinance mcp-python-sdk + ``` + + + + Create a new file `stock_agent.py` with the following code: + ```python + from praisonaiagents import Agent, MCP + + agent = Agent( + instructions="""You are a helpful assistant that can check stock prices and perform other tasks. + Use the available tools when relevant to answer user questions.""", + llm="gpt-4o-mini", + tools = MCP("/path/to/python /path/to/app.py") + ) + + # NOTE: Replace with your actual Python path and app.py file path + + agent.start("What is the stock price of Tesla?") + ``` + + + + Execute your script: + ```bash + zsh -c "source $(conda info --base)/etc/profile.d/conda.sh && conda activate windsurf && python stock_agent.py" + ``` + + + + + **Requirements** + - Python 3.10 or higher + - Conda for environment management + - yfinance package for stock data + - mcp-python-sdk for MCP server implementation + - OpenAI API key (for the agent's LLM) + + +## Features + + + + Create your own custom tools with Python. + + + Seamless integration with Model Context Protocol. + + + Strong typing for better code reliability. + + + Built-in support for asynchronous functions. + + + +## Implementation Details + +### FastMCP Class + +The `FastMCP` class from the `mcp-python-sdk` package provides a simple way to create MCP servers in Python: + +```python +from mcp.server.fastmcp import FastMCP + +# Create an MCP server with a name +mcp = FastMCP("my_tools") + +# Define a tool using the @mcp.tool decorator +@mcp.tool() +async def my_tool(param1: str, param2: int) -> str: + """Tool description with clear documentation. + + Args: + param1: Description of param1 + param2: Description of param2 + + Returns: + Description of the return value + """ + # Tool implementation + return f"Processed {param1} with {param2}" + +# Run the server with stdio transport +if __name__ == "__main__": + mcp.run(transport='stdio') +``` + +### Agent Integration + +To use your custom MCP server with PraisonAI agents, use the `MCP` class to specify the command to run your Python script: + +```python +from praisonaiagents import Agent, MCP + +agent = Agent( + instructions="Agent instructions", + llm="gpt-4o-mini", + tools=MCP( + command="python", # Or full path to Python + args=["path/to/your/mcp_server.py"] # Path to your MCP server script + ) +) +``` diff --git a/docs/mint.json b/docs/mint.json index 48a36ad9d..2c3b275bb 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -75,6 +75,10 @@ "name": "Tools", "url": "/tools" }, + { + "name": "MCP", + "url": "/mcp" + }, { "name": "JS", "url": "/js" @@ -230,6 +234,14 @@ "agents/recommendation" ] }, + { + "group": "MCP", + "pages": [ + "mcp/bravesearch", + "mcp/airbnb", + "mcp/custom" + ] + }, { "group": "Tools", "pages": [ diff --git a/src/praisonai-agents/mcp-mini-airbnb.py b/src/praisonai-agents/mcp-mini-airbnb.py new file mode 100644 index 000000000..dabe2d4c7 --- /dev/null +++ b/src/praisonai-agents/mcp-mini-airbnb.py @@ -0,0 +1,9 @@ +from praisonaiagents import Agent, MCP + +search_agent = Agent( + instructions="""You help book apartments on Airbnb.""", + llm="gpt-4o-mini", + tools=MCP("npx -y @openbnb/mcp-server-airbnb --ignore-robots-txt") +) + +search_agent.start("I want to book an apartment in Paris for 2 nights. 03/28 - 03/30 for 2 adults") \ No newline at end of file diff --git a/src/praisonai-agents/mcp-mini-bravesearch.py b/src/praisonai-agents/mcp-mini-bravesearch.py new file mode 100644 index 000000000..30c9575f0 --- /dev/null +++ b/src/praisonai-agents/mcp-mini-bravesearch.py @@ -0,0 +1,15 @@ +from praisonaiagents import Agent, MCP +import os + +# Use the API key from environment or set it directly +brave_api_key = os.getenv("BRAVE_API_KEY") or "BSAbRwmwE-WV_7gKR1ZZIdE2Twa0l4w" + +# Use a single string command with environment variables +search_agent = Agent( + instructions="""You are a helpful assistant that can search the web for information. + Use the available tools when relevant to answer user questions.""", + llm="gpt-4o-mini", + tools=MCP("npx -y @modelcontextprotocol/server-brave-search", env={"BRAVE_API_KEY": brave_api_key}) +) + +search_agent.start("Search more information about AI News") \ No newline at end of file diff --git a/src/praisonai-agents/mcp-npx-brave.py b/src/praisonai-agents/mcp-npx-brave.py index 4cc367102..f42a4947c 100644 --- a/src/praisonai-agents/mcp-npx-brave.py +++ b/src/praisonai-agents/mcp-npx-brave.py @@ -1,24 +1,18 @@ from praisonaiagents import Agent, MCP +import os +brave_api_key = os.getenv("BRAVE_API_KEY") + +# Pass the environment variable directly to the MCP server search_agent = Agent( instructions="""You are a helpful assistant that can search the web for information. Use the available tools when relevant to answer user questions.""", llm="gpt-4o-mini", tools=MCP( command="npx", - args=[ - "-y", - "@smithery/cli@latest", - "install", - "@smithery-ai/brave-search", - "--client", - "claude", - "--config", - '{"braveApiKey":"BSANfDaqLKO9wq7e08mrPth9ZlJvKtc"}' - ], - timeout=30, # 3 minutes for brave-search - debug=True # Enable detailed logging + args=["-y", "@modelcontextprotocol/server-brave-search"], + env={"BRAVE_API_KEY": brave_api_key} ) ) -search_agent.start("Search more information about Praison AI") \ No newline at end of file +search_agent.start("Search more information about AI News") \ No newline at end of file diff --git a/src/praisonai-agents/mcp-npx-mini-airbnb-stockprice.py b/src/praisonai-agents/mcp-npx-mini-airbnb-stockprice.py new file mode 100644 index 000000000..f84321688 --- /dev/null +++ b/src/praisonai-agents/mcp-npx-mini-airbnb-stockprice.py @@ -0,0 +1,18 @@ +from praisonaiagents import Agent, MCP + +search_agent = Agent( + instructions="""You help book apartments on Airbnb.""", + llm="gpt-4o-mini", + tools=MCP("npx -y @openbnb/mcp-server-airbnb --ignore-robots-txt") +) + +search_agent.start("I want to book an apartment in Paris for 2 nights. 03/28 - 03/30 for 2 adults") + +agent = Agent( + instructions="""You are a helpful assistant that can check stock prices and perform other tasks. + Use the available tools when relevant to answer user questions.""", + llm="gpt-4o-mini", + tools = MCP("/Users/praison/miniconda3/envs/mcp/bin/python /Users/praison/stockprice/app.py") +) + +agent.start("What is the stock price of Tesla?") \ No newline at end of file diff --git a/src/praisonai-agents/mcp-python-stockprice.py b/src/praisonai-agents/mcp-python-stockprice.py new file mode 100644 index 000000000..a8f57e413 --- /dev/null +++ b/src/praisonai-agents/mcp-python-stockprice.py @@ -0,0 +1,13 @@ +from praisonaiagents import Agent, MCP + +agent = Agent( + instructions="""You are a helpful assistant that can check stock prices and perform other tasks. + Use the available tools when relevant to answer user questions.""", + llm="gpt-4o-mini", + tools = MCP("/Users/praison/miniconda3/envs/mcp/bin/python /Users/praison/stockprice/app.py") +) + +# NOTE: Python Path replace with yours: /Users/praison/miniconda3/envs/mcp/bin/python +# NOTE: app.py file path, replace it with yours: /Users/praison/stockprice/app.py + +agent.start("What is the stock price of Tesla?") \ No newline at end of file