Cerberoseee/ai-agents-mcp-server

AI Agents MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI agents with access to e-commerce backend APIs, data schemas, and intelligent prompts for automated business operations.

🚀 Overview

The AI Agents MCP Server is a sophisticated implementation of the Model Context Protocol that bridges AI clients with e-commerce backend systems. It exposes a rich set of tools, resources, and prompts that enable AI agents to perform complex business operations including customer management, order processing, product analysis, and market intelligence.

✨ Key Features

🛠️ API Tools Suite

• Customer Management: Get customer details, activity, and order history
• Order Processing: Retrieve order details, update status, and send confirmations
• Product Operations: Get product details and update product information
• Market Intelligence: Access market trends and shipping rates
• Data Retrieval: Comprehensive order history and analytics

📊 Resource Management

• Schema Definitions: Structured schemas for all data models
• Database Integration: Direct MongoDB access for real-time data
• Document Resources: Comprehensive documentation and guides
• Dynamic Schema Inference: Automatic schema generation from data samples

🧠 AI Prompt Library

• Product Analysis: Performance analysis and optimization prompts
• Content Generation: Product description and listing optimization
• Data Analytics: Collection analysis and market trend evaluation
• Order Processing: Intelligent order workflow automation

🔧 Infrastructure Features

• Error Handling: Comprehensive error management with detailed responses
• Request Validation: Robust input validation using Pydantic models
• Logging: Colorized logging for enhanced debugging
• Configuration Management: Environment-based configuration system

📋 Prerequisites

• Python 3.11 or higher
• Poetry for dependency management
• MongoDB database access
• Access to e-commerce backend API
• Valid API authentication keys

🛠️ Installation

1. Clone the repository

   git clone <repository-url>
   cd ai-agents-mcp-server
   

2. Install dependencies using Poetry

   poetry install
   

3. Activate the virtual environment

   poetry shell
   

⚙️ Environment Configuration

Create a .env file in the root directory with the following variables:

Required Environment Variables

# Database Configuration
DB_HOST=your_mongodb_host
DB_PORT=27017
DB_NAME=your_database_name
DB_USERNAME=your_db_username
DB_PASSWORD=your_db_password

# API Configuration
API_BASE_URL=http://localhost:8000
API_KEY=your_backend_api_key
API_TIMEOUT=30

# Environment Settings
ENVIRONMENT=development
HOST=localhost
PORT=3000

Environment Variable Details

🚀 How to Run

Development Mode

# Using Poetry
poetry run python src/ai-agents-mcp-server/main.py

# Or if virtual environment is activated
python src/ai-agents-mcp-server/main.py

Production Mode

# Direct execution
python -m ai-agents-mcp-server.main

# Or with specific Python path
PYTHONPATH=src python -m ai-agents-mcp-server.main

Integration with MCP Client

The server is designed to be used with MCP clients. Configure your client to connect to this server:

# Example client configuration
server_script_path = "/path/to/ai-agents-mcp-server/src/ai-agents-mcp-server/main.py"

🛠️ Available Tools

Customer Management Tools

• get_customer_details - Retrieve detailed customer information
• get_customer_activity - Get customer activity logs
• get_customer_order_history - Fetch customer's order history

Order Management Tools

• get_order_details - Get specific order information
• get_order_history - Retrieve order history data
• update_order_status - Update order status
• send_order_confirmation - Send order confirmation emails

Product Management Tools

• get_product_details - Retrieve product information
• update_product - Update product data

Market Intelligence Tools

• get_market_trends - Access market trend analysis
• get_shipping_rates - Calculate shipping costs

📚 Available Resources

Database Schemas

• product_schema - Product catalog structure
• customer_segments_schema - Customer segmentation data
• order_history_schema - Order transaction structure
• market_trends_schema - Market analysis data
• category_schema - Product category definitions
• product_item_schema - Individual product item structure

Document Resources

• MCP Python SDK documentation
• Implementation guides and best practices
• API reference materials

🧠 Available Prompts

Analysis Prompts

• analyze_collection - Analyze MongoDB collection structure
• analyze_product_performance - Product performance analysis

Content Generation Prompts

• generate_product_description - Create product descriptions
• optimize_product_listing - Optimize product listings

Data Retrieval Prompts

• get_product_data - Retrieve product information
• get_order_history - Fetch order history
• get_market_trends - Access market trends

🔧 Development

Project Structure

src/ai-agents-mcp-server/
├── main.py                     # MCP server entry point
├── common/                     # Shared configuration
│   └── config.py              # Configuration keys
├── config/                     # Configuration modules
│   ├── api_config.py          # API configuration
│   └── database_config.py     # Database configuration
├── tools/                      # MCP tools
│   ├── tool_manager.py        # Tool management
│   └── api/                   # API interaction tools
│       ├── base_api_tool.py   # Base tool class
│       ├── get_customer_*.py  # Customer tools
│       ├── get_order_*.py     # Order tools
│       ├── get_product_*.py   # Product tools
│       └── update_*.py        # Update tools
├── resources/                  # MCP resources
│   ├── resource_manager.py    # Resource management
│   ├── base_resources.py      # Base resource class
│   └── schemas/               # Schema definitions
├── prompts/                    # MCP prompts
│   ├── prompt_manager.py      # Prompt management
│   ├── prompt_service.py      # Prompt processing
│   └── prompt_payload.py      # Prompt data models
├── exception/                  # Error handling
│   ├── tool_exceptions.py     # Custom exceptions
│   ├── exception_schema.py    # Error schemas
│   └── exception_response.py  # Error responses
└── mcp-documents/             # Documentation resources

Adding New Tools

1. Create a new tool class inheriting from BaseAPITool:

   from .base_api_tool import BaseAPITool
   
   class YourNewTool(BaseAPITool):
       name = "your_tool_name"
       description = "Tool description"
       endpoint = "/api/your-endpoint"
       # ... implement execute method
   

2. Register the tool in tool_manager.py:

   self.tools = {
       # ... existing tools
       "your_tool_name": YourNewTool(api_base_url),
   }
   

Adding New Resources

1. Create a schema resource in resources/schemas/:

   from resources.base_resources import BaseResource
   
   class YourSchemaResource(BaseResource):
       # ... implement get_metadata and get_resource methods
   

2. Register the resource in resource_manager.py:

   RESOURCE_TYPES = {
       # ... existing resources
       "your_schema": YourSchemaResource(),
   }
   

Adding New Prompts

1. Define the prompt in prompt_manager.py:

   PROMPTS = {
       # ... existing prompts
       "your_prompt": types.Prompt(
           name="your_prompt",
           description="Prompt description",
           arguments=[...],
       ),
   }
   

2. Implement the handler in prompt_service.py:

   def your_prompt_handler(self, arguments):
       # ... implement prompt logic
   

🔍 API Tool Categories

📖 Read-Only Tools (Data Retrieval)

• Customer details and activity
• Order details and history
• Product information
• Market trends and analytics
• Shipping rate calculations

✏️ Write Tools (Data Modification)

• Product updates
• Order status changes
• Order confirmation sending

🐛 Troubleshooting

Common Issues

1. Database Connection Failed

   • Verify MongoDB credentials and connection string
   • Check if MongoDB service is running
   • Ensure network connectivity to database

2. API Authentication Errors

   • Verify API_KEY environment variable
   • Check API key permissions and validity
   • Ensure backend API is accessible

3. Tool Execution Failures

   • Check API endpoint availability
   • Verify input data format and validation
   • Review server logs for detailed error messages

4. MCP Client Connection Issues

   • Ensure server script path is correct
   • Check that all dependencies are installed
   • Verify environment variables are properly set

Logging

The server provides detailed logging with color coding:

• INFO: General information (White)
• ERROR: Error messages (Red)
• WARNING: Warnings (Blue)
• DEBUG: Debug information (White)

🧪 Testing

Testing Tools

# Test specific tool
python -c "
import asyncio
from tools.tool_manager import ToolManager

async def test():
    manager = ToolManager()
    result = await manager.call_tools('get_customer_details', {'customer_id': '123'})
    print(result)

asyncio.run(test())
"

Testing Resources

# Test resource access
python -c "
from resources.resource_manager import ResourceManager

manager = ResourceManager()
resources = manager.handle_list_all_resources_request()
print(resources)
"

🔐 Security Considerations

• API Key Management: Store API keys securely in environment variables
• Input Validation: All inputs are validated using Pydantic models
• Error Handling: Sensitive information is not exposed in error messages
• Database Security: Use strong authentication for MongoDB connections
• Rate Limiting: Consider implementing rate limiting for API calls

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Implement your changes following the existing patterns
4. Add tests for new functionality
5. Update documentation as needed
6. Commit your changes (git commit -m 'Add some amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📖 MCP Specification

This server implements the Model Context Protocol specification. For more details about MCP concepts:

• Tools: Functions that can be called by AI agents
• Resources: Data and content exposed to AI agents
• Prompts: Template prompts for AI interactions

📄 License

This project is licensed under the terms specified in the project configuration.

🆘 Support

For support, please:

1. Check the troubleshooting section
2. Review the MCP documentation
3. Check server logs for detailed error information
4. Contact the development team

Note: Ensure all environment variables are properly configured and that the backend API and MongoDB database are accessible before starting the server. The server must be running for MCP clients to connect and use the available tools, resources, and prompts.