mcp-ai-agent-server

MCP AI Agent Server

A dual-mode AI agent system that combines the Model Context Protocol (MCP) server capabilities with a standalone CLI agent, powered by LangChain.

🎯 Two Modes of Operation

1. MCP Server Mode

Run as an MCP server that can be connected to any MCP client (like Claude Desktop) or inspected using the MCP Inspector.

2. CLI Agent Mode

Run as a standalone command-line agent for direct interaction and task execution.

✨ Capabilities

• 🌐 API Interactions: Fetch weather data, news articles, and more
• 📁 File Management: Read, write, search, and organize files
• 🔍 Web Scraping: Extract data from websites
• 📊 Data Processing: Analyze and transform data
• 💡 AI-Powered Tasks: Use LangChain for intelligent decision-making

🛠️ Tools Available

1. Weather Tool: Get current weather for any location
2. News Tool: Fetch latest news articles by topic
3. File Manager: Create, read, update, delete files
4. Web Fetcher: Download and parse web content
5. Calculator: Perform complex calculations
6. Search Tool: Search files and data
7. AI Agent: LangChain MCP client powered reasoning and task execution

📦 Installation

Prerequisites

• Python 3.10+
• uv package manager
• Node.js (for MCP Inspector)

Setup

1. Clone the repository:

git clone https://github.com/elcaiseri/mcp-ai-agent-server.git
cd mcp-ai-agent-server

1. Install dependencies using uv:

uv pip install -e .

1. Set up environment variables:

cp .env.example .env
# Edit .env with your API keys

Required API keys in .env: ``env OPENAI_API_KEY=your_openai_api_key OPENWEATHER_API_KEY=your_openweather_api_key NEWS_API_KEY=your_news_api_key ``

🚀 Usage

Mode 1: MCP Server with Inspector

The MCP server can be tested and debugged using the official MCP Inspector tool.

Start the server with inspector: ``bash npx @modelcontextprotocol/inspector uv run python -m src.server ``

This will:

• Launch the MCP server
• Open the MCP Inspector in your browser
• Allow you to test all available tools interactively
• View request/response logs in real-time

Connect to MCP Clients:

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "ai-agent": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.server"],
      "cwd": "/path/to/mcp-ai-agent-server"
    }
  }
}

Mode 2: Standalone CLI Agent

Run the agent directly from the command line for interactive sessions.

Start the CLI agent: ``bash uv run python -m src.client ``

<p align="center"> <img src="assets/agent_cli.png" alt="AI Agent MCP Client Chat Interface" width="600"> </p>

Example interactions: `` > What's the weather in Tokyo? > Fetch the latest news about AI > Create a file called notes.txt with today's summary > Search for all Python files in the current directory ``

The CLI agent uses LangChain MCP Client to:

• Understand natural language commands
• Select appropriate tools automatically
• Chain multiple operations together
• Provide conversational responses

📚 Tool Examples

Weather Tool

# Get current weather for a location
get_weather(location="New York")
# Returns: temperature, conditions, humidity, wind speed

News Tool

# Get latest news on a topic
fetch_news(topic="technology", limit=5)
# Returns: list of articles with title, description, URL

File Operations

# Create a file
create_file(path="data/output.txt", content="Hello World")

# Read a file
read_file(path="data/input.txt")

# Search files
search_files(directory=".", pattern="*.py")

Web Fetching

# Fetch webpage content
fetch_webpage(url="https://example.com")
# Returns: parsed HTML content and text

AI Agent Tasks

# Execute complex multi-step tasks
execute_agent_task(task="Analyze the weather in Tokyo and write a report")

🏗️ Architecture

mcp-ai-agent-server/
├── src/
│   ├── server.py          # Main MCP server implementation
│   ├── client.py          # Standalone CLI agent implementation
│   ├── tools/             # Individual tool implementations
│   │   ├── weather.py
│   │   ├── news.py
│   │   ├── file_manager.py
│   │   ├── web_fetcher.py
│   │   └── calculator.py
│   └── utils/             # Utilities
│       └── config.py
├── tests/                 # Test suite
├── pyproject.toml         # Project configuration
├── .env.example           # Environment template
└── README.md

🔧 Development

Running Tests

uv run pytest

Code Formatting

uv run black src/
uv run ruff check src/

License

MIT License

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.