MCP ToolBridge Assistant

Short Description

MCP ToolBridge Assistant is an MCP-based AI assistant that connects an LLM to external tools. It solves the problem of making an assistant useful beyond chat by allowing it to calculate, read files, fetch web content, and call a weather service through safe tool interfaces.

The project is built as a clean Python portfolio project for AI engineering, backend engineering, and agentic AI roles.

Features

✅ MCP server built with FastMCP
✅ Calculator tool with safe expression parsing
✅ Weather lookup using an external public service
✅ Local text file reader
✅ URL fetcher for web page previews
✅ Demo script without needing an LLM
✅ Unit tests with pytest
✅ GitHub Actions CI workflow
✅ Docker setup
✅ Recruiter-friendly documentation and examples

Architecture Diagram

User
  ↓
MCP Client, such as Claude Desktop or another AI app
  ↓
FastMCP Python Server
  ↓
Tool Layer
  ↓
External Systems, APIs, local files, and web pages

Tech Stack

• Python
• Model Context Protocol, MCP
• FastMCP
• httpx
• Pydantic
• python-dotenv
• pytest
• ruff
• Docker
• GitHub Actions

Skills Demonstrated ⭐

• AI agents
• MCP development
• Tool calling
• External API integration
• Backend development
• Python software engineering
• Modular architecture
• Safe tool design
• Error handling
• Unit testing
• CI/CD
• Docker
• Documentation
• GitHub project packaging

Project Structure

mcp-toolbridge-assistant/
├── .github/
│   └── workflows/
│       └── python-ci.yml
├── docker/
│   └── Dockerfile
├── docs/
│   ├── architecture.png
│   ├── demo.md
│   └── evaluation.md
├── examples/
│   ├── claude_desktop_config.json
│   └── sample_notes.txt
├── screenshots/
│   ├── example_output.png
│   └── terminal_demo.png
├── src/
│   └── mcp_ai_assistant/
│       ├── __init__.py
│       ├── config.py
│       ├── demo.py
│       ├── server.py
│       └── tool_logic.py
├── tests/
│   └── test_tool_logic.py
├── .env.example
├── .gitignore
├── app.py
├── docker-compose.yml
├── LICENSE
├── pyproject.toml
├── requirements.txt
└── README.md

Installation

Clone the repository:

git clone https://github.com/ParisaArbab/mcp-toolbridge-assistant.git
cd mcp-toolbridge-assistant

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate

On Windows:

python -m venv .venv
.venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt
pip install -e .

Create the environment file:

cp .env.example .env

Run the demo:

python app.py --demo

Run the MCP server:

python app.py

You can also run:

python -m mcp_ai_assistant.server

Usage

Connect the server to an MCP-compatible client.

Example MCP client configuration:

{
  "mcpServers": {
    "mcp-toolbridge-assistant": {
      "command": "python",
      "args": ["-m", "mcp_ai_assistant.server"],
      "env": {}
    }
  }
}

Example user requests after connection:

Calculate 25 * (7 + 3).

What is the weather in New York?

Read examples/sample_notes.txt and summarize it.

Fetch https://example.com and tell me what it says.

Screenshots

Terminal Demo

Example Tool Output

Example Output

Request:
Read examples/sample_notes.txt and summarize it.

Tool Used:
read_file

Result:
The file explains that this project is an MCP-based AI assistant. It exposes tools that an AI client can use for calculator tasks, weather lookup, file reading, and URL fetching.

Recommendation:
Use this file as a simple test input when checking that the MCP server works.

Confidence:
95%

How It Works

The user sends a request to an MCP-compatible AI client. The AI client decides whether it needs an external tool. If a tool is needed, the request goes to the FastMCP server. The server calls the correct Python function, such as calculator, weather, file reader, or URL fetcher. The tool returns structured text back to the AI client, and the AI uses that result to answer the user.

User Request
  ↓
MCP Client
  ↓
Tool Selection
  ↓
FastMCP Server
  ↓
Python Tool Logic
  ↓
External API / Local File / Web Page
  ↓
Final Response

Evaluation / Results

Metric	Result	Notes
Unit test pass rate	100%	Calculator and file reader tests pass with pytest.
Tool coverage	4 tools	Calculator, weather, file reader, URL fetcher.
Calculator latency	< 50 ms	Local tool, no network needed.
External API latency	Network-dependent	Weather and URL tools depend on external services.
Safety checks	Basic	Calculator avoids eval and only accepts math operators.

More details are in docs/evaluation.md.

Challenges

• Tool safety, because file and URL tools can expose sensitive or unsafe content.
• External API reliability, because weather and URL tools depend on network availability.
• Error handling, because AI assistants need clear messages when a tool fails.
• Tool descriptions, because the AI client must understand when to use each tool.
• Local setup, because MCP clients may need the correct Python path.

Future Improvements

• Add a RAG tool with ChromaDB or PostgreSQL.
• Add GitHub issue and pull request tools.
• Add memory for past user preferences.
• Add streaming responses.
• Add authentication and permission checks.
• Add Docker deployment examples.
• Add Kubernetes deployment.
• Add LLM-based evaluation for tool-selection accuracy.

Tests

Run unit tests:

pytest

Run style checks:

ruff check .

The project also includes a GitHub Actions workflow:

.github/workflows/python-ci.yml

Demo

A short demo guide is available in docs/demo.md.

For a quick local demo:

python app.py --demo

Project Status

Under Active Development

This is a portfolio-ready project. It is not a production system yet. Production use would need stronger permissions, monitoring, authentication, and security controls.

License

This project is for educational and portfolio purposes. All rights reserved by the author.

Author

GitHub: https://github.com/ParisaArbab
LinkedIn: https://www.linkedin.com/in/parisa-arbab