Skip to content

Update navigation and MCP integration #433

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MervinPraison merged 1 commit into from
Mar 29, 2025
Merged

Update navigation and MCP integration #433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 85 additions & 0 deletions docs/mcp/airbnb.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<Steps>
<Step title="Set API Key">
Set your OpenAI API key as an environment variable in your terminal:
```bash
export OPENAI_API_KEY=your_openai_api_key_here
```
</Step>

<Step title="Create a file">
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")
```
</Step>

<Step title="Install Dependencies">
Make sure you have Node.js installed, as the MCP server requires it:
```bash
pip install praisonaiagents
```
</Step>

<Step title="Run the Agent">
Execute your script:
```bash
python airbnb_search.py
```
</Step>
</Steps>

<Note>
**Requirements**
- Python 3.10 or higher
- Node.js installed on your system
- OpenAI API key (for the agent's LLM)
</Note>

## Features

<CardGroup cols={2}>
<Card title="Accommodation Search" icon="hotel">
Search for accommodations on Airbnb with natural language queries.
</Card>
<Card title="MCP Integration" icon="plug">
Seamless integration with Model Context Protocol.
</Card>
<Card title="Booking Details" icon="calendar">
Specify dates, guests, and location preferences in natural language.
</Card>
<Card title="NPM Package" icon="js">
Leverages the official Airbnb MCP server package.
</Card>
</CardGroup>
95 changes: 95 additions & 0 deletions docs/mcp/bravesearch.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<Steps>
<Step title="Set API Key">
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/).
</Step>

<Step title="Create a file">
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"
Comment on lines +42 to +43
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Mar 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

While using environment variables is great, providing a default value directly in the code can be a security risk. It's better to force users to explicitly set the environment variable to avoid accidental exposure of the API key. Consider raising an error if the environment variable is not set.

        # Use the API key from environment or set it directly
        brave_api_key = os.getenv("BRAVE_API_KEY")
        if not brave_api_key:
            raise ValueError("BRAVE_API_KEY environment variable must be set.")


# 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")
```
</Step>

<Step title="Install Dependencies">
Make sure you have Node.js installed, as the MCP server requires it:
```bash
pip install praisonaiagents
```
</Step>

<Step title="Run the Agent">
Execute your script:
```bash
python brave_search.py
```
</Step>
</Steps>

<Note>
**Requirements**
- Python 3.10 or higher
- Node.js installed on your system
- Brave Search API key
- OpenAI API key (for the agent's LLM)
</Note>

## Features

<CardGroup cols={2}>
<Card title="Web Search" icon="globe">
Search the web for up-to-date information.
</Card>
<Card title="MCP Integration" icon="plug">
Seamless integration with Model Context Protocol.
</Card>
<Card title="Environment Variables" icon="key">
Secure API key handling through environment variables.
</Card>
<Card title="NPM Package" icon="js">
Leverages the official Brave Search MCP server package.
</Card>
</CardGroup>
170 changes: 170 additions & 0 deletions docs/mcp/custom.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<Steps>
<Step title="Create MCP Server">
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')
```
</Step>

<Step title="Install Dependencies">
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
```
</Step>

<Step title="Create Agent Integration">
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")
)
Comment on lines +80 to +81
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Mar 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Hardcoding the path to the Python interpreter and the app.py file makes this example less portable. It would be better to use relative paths or environment variables to specify these locations.

        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("python app.py")
        )


# NOTE: Replace with your actual Python path and app.py file path

agent.start("What is the stock price of Tesla?")
```
</Step>

<Step title="Run the Agent">
Execute your script:
```bash
zsh -c "source $(conda info --base)/etc/profile.d/conda.sh && conda activate windsurf && python stock_agent.py"
```
</Step>
</Steps>

<Note>
**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)
</Note>

## Features

<CardGroup cols={2}>
<Card title="Custom Tools" icon="wrench">
Create your own custom tools with Python.
</Card>
<Card title="MCP Integration" icon="plug">
Seamless integration with Model Context Protocol.
</Card>
<Card title="Type Hints" icon="code">
Strong typing for better code reliability.
</Card>
<Card title="Async Support" icon="bolt">
Built-in support for asynchronous functions.
</Card>
</CardGroup>

## 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
)
)
```
12 changes: 12 additions & 0 deletions docs/mint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,10 @@
"name": "Tools",
"url": "/tools"
},
{
"name": "MCP",
"url": "/mcp"
},
{
"name": "JS",
"url": "/js"
Expand Down Expand Up @@ -230,6 +234,14 @@
"agents/recommendation"
]
},
{
"group": "MCP",
"pages": [
"mcp/bravesearch",
"mcp/airbnb",
"mcp/custom"
]
},
{
"group": "Tools",
"pages": [
Expand Down
9 changes: 9 additions & 0 deletions src/praisonai-agents/mcp-mini-airbnb.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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")
Loading
Loading