ashutosh-rath02/mcp-ai-assistant

LangChain MCP Server - Clean Architecture

A Model Context Protocol (MCP) server built with LangChain and Google Gemini, following clean architecture principles. This server provides specialized AI tools for various tasks like poetry generation, character creation, system design, market analysis, workout planning, recipe generation, trip planning, and puzzle solving.

🏗️ Architecture

The project follows Clean Architecture principles with clear separation of concerns:

src/
├── domain/                 # Core business logic
│   ├── entities/          # Domain entities (Tool, ToolResult)
│   └── services/          # Domain services (ToolService)
├── application/           # Application layer
│   ├── use_cases/        # Use cases (ListTools, ExecuteTool)
│   └── services/         # Application services (MCPService)
├── infrastructure/        # External dependencies
│   ├── ai/              # AI service implementations
│   ├── config/          # Configuration management
│   └── repositories/    # Data access implementations
└── presentation/         # User interface layer
    ├── api/             # Web API handlers
    ├── cli/             # Command-line interface
    └── models/          # Presentation models

🚀 Features

• Clean Architecture: Proper separation of concerns with domain, application, infrastructure, and presentation layers
• Specialized AI Tools: 8 different AI-powered tools for various tasks
• Smart CLI: AI-powered tool selection based on natural language input
• WebSocket API: Real-time communication via MCP protocol
• REST API: Additional HTTP endpoints for health checks and tool listing
• Comprehensive Testing: Test scripts to verify functionality

🛠️ Available Tools

1. generate_poem - Create poems in various styles (haiku, sonnet, free verse, limerick)
2. create_character - Generate detailed fictional characters for storytelling
3. design_system - Design software system architectures
4. analyze_market - Conduct market analysis and competitive research
5. create_workout - Generate personalized workout plans
6. generate_recipe - Create recipes based on available ingredients
7. plan_trip - Plan travel itineraries
8. solve_puzzle - Solve logic puzzles and brain teasers

📋 Prerequisites

• Python 3.8+
• Google Gemini API key
• Required Python packages (see requirements.txt)

🚀 Quick Start

1. Setup Environment

# Clone the repository
git clone <repository-url>
cd langchain-mcp

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp env_example.txt .env
# Edit .env with your Google API key

2. Run the Server

# Start the MCP server
python run_server.py

The server will start on http://localhost:8000 with WebSocket endpoint at ws://localhost:8000/ws.

3. Use the Smart CLI

# Run the interactive CLI
python run_cli.py

# Or run a single request
python run_cli.py --request "Write a poem about AI"

4. Test the Server

# Run the test script
python run_test.py

🏗️ Architecture Details

Domain Layer

• Entities: Core business objects (Tool, ToolResult)
• Services: Domain business logic (ToolService)

Application Layer

• Use Cases: Application-specific business rules
• Services: Orchestration of domain services

Infrastructure Layer

• AI Service: LLM integration with Google Gemini
• Configuration: Environment and settings management
• Repositories: Data access implementations

Presentation Layer

• API: WebSocket and HTTP handlers
• CLI: Command-line interface with AI tool selection
• Models: Request/response data structures

🔧 Configuration

The application uses environment variables for configuration:

# MCP Server
MCP_HOST=localhost
MCP_PORT=8000

# Google Gemini
GOOGLE_API_KEY=your_api_key_here
DEFAULT_MODEL=gemini-2.0-flash
MAX_TOKENS=4000
TEMPERATURE=0.7

# Logging
LOG_LEVEL=INFO

📚 API Usage

WebSocket MCP Protocol

Connect to ws://localhost:8000/ws and use the MCP protocol:

// Initialize
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {}
}

// List tools
{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/list",
  "params": {}
}

// Execute tool
{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "generate_poem",
    "arguments": {
      "theme": "artificial intelligence",
      "style": "haiku",
      "mood": "contemplative"
    }
  }
}

REST API Endpoints

• GET / - Server information
• GET /health - Health check
• GET /tools - List available tools

🤖 Smart CLI Features

The CLI uses AI to automatically select the appropriate tool based on natural language input:

# Examples
python run_cli.py --request "Write a poem about love"
python run_cli.py --request "Create a hero for a fantasy story"
python run_cli.py --request "Design a website for selling products"
python run_cli.py --request "Analyze the market for electric cars"
python run_cli.py --request "Create a workout for beginners"
python run_cli.py --request "Make a recipe with chicken and rice"
python run_cli.py --request "Plan a trip to Japan"
python run_cli.py --request "Solve this puzzle: A farmer has 17 sheep..."

🧪 Testing

Run the comprehensive test suite:

python run_test.py

This will test:

• Server connection and initialization
• Tool listing
• Tool execution (poem generation, puzzle solving, workout creation)

🔄 Development

Adding New Tools

1. Domain Layer: Add tool definition in ToolRepositoryImpl._initialize_tools()
2. Infrastructure Layer: Add AI method in AIService
3. Repository Layer: Add execution logic in ToolRepositoryImpl.execute_tool()

Project Structure Benefits

• Maintainability: Clear separation of concerns
• Testability: Easy to unit test each layer independently
• Scalability: Easy to add new tools and features
• Flexibility: Easy to swap implementations (e.g., different AI providers)

📄 License

This project is licensed under the MIT License.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes following clean architecture principles
4. Add tests for new functionality
5. Submit a pull request

📞 Support

For issues and questions, please open an issue on the repository.