common/mcp/README.md

MCP Tools Server

A Model Context Protocol (MCP) server that exposes all tools from the tools/ folder via stdio transport.

Features

• Dynamic Tool Discovery: Automatically discovers and registers all tools from the tools folder
• Stdio Transport: Compatible with Claude Desktop and other MCP clients
• Comprehensive Tool Coverage: Exposes ~13 tools across 6 categories:
  • Google Search (google_tools)
  • News API (news_tools)
  • DuckDuckGo Search (search_tools)
  • Time Utilities (time_tools)
  • Weather Forecast (weather_tools)
  • Yahoo Finance (yf_tools)

Installation

1. Install required dependencies:

pip install mcp requests beautifulsoup4 ddgs yfinance python-dotenv pydantic

2. Set up environment variables in .env:

# Google Search (Serper.dev)
SERPER_API_KEY=your_serper_api_key

# News API
NEWS_API_KEY=your_news_api_key

# Weather API
OPENWEATHER_API_KEY=your_openweather_api_key

# Google AI (for agents)
GOOGLE_API_KEY=your_google_api_key

# Groq (for agents)
GROQ_API_KEY=your_groq_api_key

Usage

Running the Server

cd common/mcp
python mcp_server.py

The server will:

1. Discover all tools from the tools/ folder
2. Print registered tools to stderr
3. Start listening on stdio for MCP protocol messages

Integrating with Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "tools-server": {
      "command": "python",
      "args": ["/absolute/path/to/agenticaiprojects/common/mcp/mcp_server.py"],
      "env": {
        "SERPER_API_KEY": "your_key",
        "NEWS_API_KEY": "your_key",
        "OPENWEATHER_API_KEY": "your_key"
      }
    }
  }
}

Available Tools

The server exposes the following tools:

Google Search:

• google_tools.google_search - General Google search
• google_tools.google_search_recent - Time-filtered Google search

News:

• news_tools.get_top_headlines - Top headlines by country
• news_tools.search_news - Search news by topic
• news_tools.get_news_by_category - News by category

Search & Content:

• search_tools.duckduckgo_search - DuckDuckGo search
• search_tools.fetch_page_content - Extract page content

Time:

• time_tools.current_datetime - Get current date/time

Weather:

• weather_tools.get_weather_forecast - Weather forecast via API
• weather_tools.search_weather_fallback_ddgs - Weather via DuckDuckGo
• weather_tools.search_weather_fallback_bs - Weather via web scraping

Finance:

• yf_tools.get_summary - Stock summary
• yf_tools.get_market_sentiment - Market sentiment analysis
• yf_tools.get_history - Historical stock data

Development

Adding New Tools

1. Create a new file in tools/ folder (e.g., my_tools.py)
2. Decorate functions with @function_tool
3. The server will automatically discover and register them on next restart

Testing

# Test the server
cd common/mcp
python mcp_server.py

# In another terminal, you can send MCP protocol messages via stdin
# Or use an MCP client library to test

Troubleshooting

Tools not discovered:

• Check that functions are decorated with @function_tool
• Verify the module is in the tools/ folder
• Check stderr output for registration messages

API errors:

• Verify environment variables are set correctly
• Check API key validity
• Review tool-specific error messages in stderr

License

Part of the agenticaiprojects repository.