mcp-server-ai-bot

🤖 AI Assistant Platform

A Model Context Protocol (MCP) server integrated with Google Gemini LLM for intelligent customer service assistance. This platform provides natural language chat capabilities and AI-powered customer data analysis and summarization.

  

🌟 Features

• 🔧 MCP Tool Integration: Standardized tool interface following Model Context Protocol
• 🤖 AI-Powered Chat: Natural language interaction using Google Gemini 1.5 Flash
• 📊 Smart Analytics: AI-generated customer insights and summaries
• 🔒 Secure API: Bearer token authentication for external API calls
• 🌐 Professional Web Interface: Modern UI for customer service operations
• 📖 Auto-Generated Docs: FastAPI automatic API documentation

📁 Project Structure

ai-assistant-platform/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI application entry point
│   ├── server.py               # MCP server setup
│   ├── llm_agent.py            # Gemini LLM integration
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py           # Configuration management
│   ├── tools/
│   │   ├── __init__.py
│   │   └── user_tools.py       # MCP tools implementation
│   └── static/
│       └── index.html          # Web interface
├── .env                        # Environment variables (not in git)
├── .env.example                # Environment template
├── .gitignore                  # Git ignore rules
├── requirements.txt            # Python dependencies
├── LICENSE                     # MIT License
└── README.md                   # This file

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• pip package manager
• Google Gemini API key (Get one here)
• External API credentials (for customer data integration)

Installation

1. Clone the repository

   git clone https://github.com/yourusername/ai-assistant-platform.git
   cd ai-assistant-platform

1. Create and activate virtual environment

Windows: ``bash python -m venv venv venv\Scripts\activate ``

Linux/Mac: ``bash python -m venv venv source venv/bin/activate ``

1. Install dependencies

   pip install -r requirements.txt

1. Configure environment variables

   # Copy the example file
   cp .env.example .env
   
   # Edit .env with your actual credentials
   # On Windows: notepad .env
   # On Linux/Mac: nano .env

Required environment variables: ``env API_KEY=your_api_key_here API_URL=https://your-api-url.com GEMINI_API_KEY=your_gemini_api_key_here ``

1. Run the server

   # Using uvicorn directly
   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
   
   # OR using Python module
   python -m app.main

1. Access the application

• 🏠 Home/Health Check: http://localhost:8000/
• 📖 API Documentation: http://localhost:8000/docs
• 🌐 Web Interface: http://localhost:8000/ui
• 🔧 List Tools: http://localhost:8000/tools

📚 API Endpoints

Core Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | / | Health check | | GET | /ui | Web interface | | GET | /tools | List available MCP tools | | GET | /config | View current configuration | | GET | /docs | Interactive API documentation |

MCP Tool Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /test/get_user_details | Test MCP tool with file number |

Request Body: ``json { "file_number": "ABC123" } ``

LLM Endpoints

Chat with LLM

POST /llm/chat

Natural language chat with optional customer context.

Request Body: ``json { "message": "What's my current balance?", "file_number": "ABC123" // Optional } ``

Response: ``json { "success": true, "response": "Based on your account, your current balance is $1,500.00..." } ``

AI Summary

POST /llm/summarize

Generate AI-powered summary of customer account.

Request Body: ``json { "file_number": "ABC123" } ``

Response: ``json { "success": true, "summary": "Account Summary for John Doe:\n\nCurrent Balance: $1,500.00..." } ``

🔧 Configuration

All configuration is managed through environment variables in the .env file:

# API Configuration
API_KEY=your_api_key_here
API_URL=https://api.example.com
API_TIMEOUT=30

# LLM Configuration
GEMINI_API_KEY=your_gemini_key_here

# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
DEBUG=false

# MCP Configuration
MCP_SERVER_NAME=company-mcp-server
MCP_SERVER_VERSION=1.0.0

🏗️ Architecture

Data Flow

User Request → FastAPI → LLM Agent → MCP Tools → External API
                           ↓
                    Gemini AI Processing
                           ↓
                    AI-Enhanced Response

Components

1. FastAPI Server (main.py): Handles HTTP requests and routing
2. LLM Agent (llm_agent.py): Manages Gemini AI interactions
3. MCP Server (server.py): Implements Model Context Protocol
4. User Tools (user_tools.py): External API integration
5. Configuration (config.py): Environment management

💡 Usage Examples

Example 1: Get Customer Details

import requests

response = requests.post(
    "http://localhost:8000/test/get_user_details",
    json={"file_number": "CUST123"}
)
print(response.json())

Example 2: Chat with Context

import requests

response = requests.post(
    "http://localhost:8000/llm/chat",
    json={
        "message": "What payment options are available?",
        "file_number": "CUST123"
    }
)
print(response.json()["response"])

Example 3: Get AI Summary

import requests

response = requests.post(
    "http://localhost:8000/llm/summarize",
    json={"file_number": "CUST123"}
)
print(response.json()["summary"])

🔌 MCP Client Integration

To use this server with an MCP client (like Claude Desktop):

{
  "mcpServers": {
    "company-mcp-server": {
      "command": "python",
      "args": [
        "/path/to/mcp-llm-server/app/main.py"
      ],
      "env": {
        "API_KEY": "your_api_key_here",
        "GEMINI_API_KEY": "your_gemini_key_here",
        "API_URL": "https://api.example.com"
      }
    }
  }
}

🧪 Testing

Using the Web Interface

1. Open http://localhost:8000/ui
2. Enter a file number (default: 14226904)
3. Test different features:

• MCP Tool Testing
• LLM Chat
• AI Summary

Using curl

# Test health check
curl http://localhost:8000/

# Test MCP tool
curl -X POST http://localhost:8000/test/get_user_details \
  -H "Content-Type: application/json" \
  -d '{"file_number": "14226904"}'

# Test LLM chat
curl -X POST http://localhost:8000/llm/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the current balance?", "file_number": "14226904"}'

🛠️ Development

Adding New MCP Tools

1. Define the tool in app/tools/user_tools.py:

   async def new_tool(self, param: str) -> Dict[str, Any]:
       """Your tool implementation"""
       pass

1. Register in app/server.py:

   @mcp_server.list_tools()
   async def list_tools() -> list[Tool]:
       return [
           Tool(name="new_tool", description="...", inputSchema={...})
       ]

1. Add handler in app/server.py:

   @mcp_server.call_tool()
   async def call_tool(name: str, arguments: dict):
       if name == "new_tool":
           result = await user_tools.new_tool(arguments["param"])

Running in Development Mode

# Enable debug mode in .env
DEBUG=true

# Run with auto-reload
uvicorn app.main:app --reload --log-level debug

📦 Dependencies

• FastAPI: Modern web framework for building APIs
• uvicorn: ASGI server for FastAPI
• google-generativeai: Google Gemini AI SDK
• httpx: Async HTTP client for external APIs
• python-dotenv: Environment variable management
• mcp: Model Context Protocol SDK

See requirements.txt for complete list with versions.

🔒 Security Best Practices

1. Never commit .env file - Already in .gitignore
2. Use environment variables for all secrets
3. Rotate API keys regularly
4. Use HTTPS in production
5. Implement rate limiting for production use
6. Validate all inputs before processing
7. Log security events for monitoring

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🐛 Troubleshooting

Common Issues

Problem: Could not import module "main"

• Solution: Use uvicorn app.main:app instead of uvicorn main:app

Problem: Server not accessible at http://0.0.0.0:8000

• Solution: Use http://localhost:8000 or http://127.0.0.1:8000 in browser

Problem: API_KEY must be set in environment variables

• Solution: Create .env file from .env.example and fill in your keys

Problem: Gemini API errors

• Solution: Verify your GEMINI_API_KEY is valid and has sufficient quota

📞 Support

For issues, questions, or contributions:

• 🐛 Report bugs via GitHub Issues
• 💬 Discussions via GitHub Discussions
• 📧 Email: your.email@example.com

🙏 Acknowledgments

• FastAPI for the excellent web framework
• Google Gemini for LLM capabilities
• Model Context Protocol for standardized tool interfaces

---

Made with ❤️ for intelligent debt collection assistance