Simple MCP Data Manager with AI

Simple MCP Data Manager with AI (Python)

A simple Model Context Protocol (MCP) server built with Python, FastAPI, and local AI model integration for managing data stored in a local data folder.

Features

• 🐍 Python Backend: FastAPI-based REST API with automatic documentation
• 🔧 MCP Server: Implements the Model Context Protocol for AI tool integration
• 🤖 Local AI Models: Multiple AI model types running locally on your machine
• 📊 RESTful API: Full CRUD operations with Pydantic validation
• 💾 Data Persistence: JSON-based data storage in a local data folder
• 🎨 Modern Web Interface: Beautiful, responsive UI with AI features
• 🔍 Smart Search: AI-powered similarity search and traditional search
• 📚 Auto-generated Docs: Interactive API documentation with Swagger/ReDoc
• ⚡ Async Operations: High-performance async/await patterns

AI Model Support

The application supports multiple types of local AI models:

Supported Model Types

1. Sentence Transformers: For text embeddings and similarity search
   • Default: all-MiniLM-L6-v2 (fast and efficient)
   • Others: all-mpnet-base-v2, multi-qa-MiniLM-L6-cos-v1
2. Text Generation: For text completion and generation
   • Models: gpt2, distilgpt2, microsoft/DialoGPT-medium
3. Text Classification: For categorizing text
   • Models: distilbert-base-uncased-finetuned-sst-2-english
4. Sentiment Analysis: For analyzing text sentiment
   • Models: cardiffnlp/twitter-roberta-base-sentiment-latest
5. TF-IDF: Traditional text analysis (no external dependencies)

AI Features

• Text Analysis: Analyze individual text pieces
• Item Analysis: Analyze data items using AI
• Similarity Search: Find similar items using embeddings
• Smart Search: Combine traditional and AI search
• Batch Analysis: Analyze all items at once
• Model Switching: Change AI models on the fly

Project Structure

Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package installer)
• Sufficient RAM for AI models (2-4GB recommended)

Setup

1. Clone or download the project
2. Install dependencies:
   pip install -r requirements.txt
3. Run the FastAPI server:
   python run.py
   or
   python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Usage

Web Interface

Visit http://localhost:8000 to access the web interface with two main tabs:

📊 Data Management Tab

• Create Items: Add new items with name, description, and category
• View Items: See all items in a beautiful card layout
• Search Items: Traditional text search across all item fields
• Edit/Delete Items: Update and remove items

🤖 AI Features Tab

• AI Model Control: Change AI model type and name
• Text Analysis: Analyze individual text pieces
• AI-Powered Search: Find similar items using embeddings
• Smart Search: Combine traditional and AI search results
• Batch Analysis: Analyze all items using AI

REST API Endpoints

Base URL: http://localhost:8000/api

Data Management Endpoints

AI Model Endpoints

API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Example API Usage

Create an item:

Analyze text with AI:

Find similar items:

Smart search:

MCP Server

The MCP server provides tools that can be used by AI assistants:

Available Tools

Data Management Tools:

1. get_all_items - Retrieve all items from the data store
2. get_item_by_id - Get a specific item by its ID
3. create_item - Create a new item with name, description, and category
4. update_item - Update an existing item by ID
5. delete_item - Delete an item by ID
6. search_items - Search items by query string

AI Model Tools: 7. get_ai_model_info - Get information about the loaded AI model 8. change_ai_model - Change the AI model type and name 9. analyze_text - Analyze text using the AI model 10. analyze_all_items - Analyze all items using the AI model 11. find_similar_items - Find items similar to a query using AI embeddings 12. analyze_single_item - Analyze a specific item using the AI model 13. smart_search - Smart search combining traditional search with AI similarity

Running the MCP Server

AI Model Configuration

Model Types and Examples

1. Sentence Transformers (Recommended for similarity search):
   model_type = "sentence_transformer" model_name = "all-MiniLM-L6-v2" # Fast and efficient
2. Text Generation:
   model_type = "text_generation" model_name = "gpt2" # or "distilgpt2"
3. Sentiment Analysis:
   model_type = "sentiment_analysis" model_name = "cardiffnlp/twitter-roberta-base-sentiment-latest"
4. Text Classification:
   model_type = "text_classification" model_name = "distilbert-base-uncased-finetuned-sst-2-english"
5. TF-IDF (No external dependencies):
   model_type = "tfidf" model_name = "TF-IDF"

Model Caching

Models are automatically cached in the models/ directory to avoid re-downloading. The cache directory is created automatically.

Data Structure

Items are stored with the following structure:

API Response Format

All API responses follow a consistent format:

Success Response

Error Response

Development

Project Structure Details

• app/models/data_model.py: Handles all data operations (CRUD)
• app/schemas/item.py: Pydantic models for request/response validation
• app/api/routes.py: FastAPI route definitions for data management
• app/api/ai_routes.py: FastAPI route definitions for AI operations
• app/ai/local_model.py: AI model manager with multiple model types
• app/main.py: Main FastAPI application with middleware
• app/mcp_server.py: MCP server implementation with AI tools
• static/index.html: Web interface with AI features

Adding New Features

1. New API Endpoints: Add routes in app/api/routes.py or app/api/ai_routes.py
2. Data Model Changes: Modify app/models/data_model.py
3. Schema Updates: Update app/schemas/item.py
4. AI Model Types: Add new model types in app/ai/local_model.py
5. MCP Tools: Add new tools in app/mcp_server.py
6. UI Updates: Modify static/index.html

Testing

You can test the API using:

• Web Interface: http://localhost:8000
• Swagger UI: http://localhost:8000/docs
• cURL: Command line examples above
• Postman: Import the OpenAPI spec from /docs

Environment Variables

You can customize the server behavior with environment variables:

Dependencies

Core Dependencies

• fastapi: Modern web framework for building APIs
• uvicorn: ASGI server for running FastAPI
• pydantic: Data validation using Python type annotations
• mcp: Model Context Protocol implementation
• aiofiles: Async file operations
• python-multipart: Form data parsing

AI/ML Dependencies

• transformers: Hugging Face transformers library
• torch: PyTorch for deep learning
• sentence-transformers: Sentence embeddings
• numpy: Numerical computing
• scikit-learn: Machine learning utilities

Development Dependencies

• python-json-logger: Structured logging

Performance Features

• Async/Await: All database and AI operations are asynchronous
• Pydantic Validation: Automatic request/response validation
• CORS Support: Cross-origin resource sharing enabled
• Static File Serving: Efficient static file delivery
• JSON Storage: Simple, fast file-based storage
• Model Caching: AI models are cached locally
• Memory Efficient: Models are loaded on-demand

Security Features

• Input Validation: Pydantic schemas validate all inputs
• CORS Configuration: Configurable cross-origin policies
• Error Handling: Proper error responses without data leakage
• File Path Safety: Secure file operations with path validation
• Local AI: All AI processing happens locally on your machine

Deployment

Local Development

Production

Docker (Optional)

Troubleshooting

Common Issues

1. Port already in use: Change the port with --port 8001
2. Import errors: Ensure you're in the correct directory
3. Permission errors: Check file permissions for the data directory
4. MCP connection issues: Verify the MCP server is running correctly
5. AI model loading errors: Check internet connection for model download
6. Memory issues: Use smaller models or increase system RAM

AI Model Issues

1. Model not loading: Check internet connection and model name
2. Memory errors: Use smaller models like all-MiniLM-L6-v2
3. Slow performance: Models are cached after first load
4. CUDA errors: Models run on CPU by default

Logs

The application provides detailed logging. Check the console output for error messages and debugging information.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - feel free to use this project for your own purposes.

Support

If you encounter any issues or have questions:

1. Check the API documentation at /docs
2. Review the logs for error messages
3. Verify AI dependencies are installed
4. Open an issue on the repository

Roadmap

• Database integration (PostgreSQL, SQLite)
• Authentication and authorization
• File upload support
• Real-time updates with WebSockets
• Docker containerization
• Unit and integration tests
• CI/CD pipeline
• More AI model types (image analysis, audio processing)
• Model fine-tuning capabilities
• Batch processing for large datasets