adnanaq/anime-mcp-server

git clone <your-repo-url>
cd anime-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Start complete stack with Docker
docker compose up -d

# Services will be available at:
# - FastAPI REST API: http://localhost:8000
# - MCP Server (HTTP): http://localhost:8001 (if mcp-server container is enabled)
# - Qdrant Vector DB: http://localhost:6333

# Start Qdrant vector database
docker compose up -d qdrant

# Create environment file
cat > .env << EOF
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION_NAME=anime_database
HOST=0.0.0.0
PORT=8000
DEBUG=True
ENABLE_MULTI_VECTOR=true
EOF

# Start FastAPI server
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

# Start the full-update process (runs in background)
curl -X POST http://localhost:8000/api/admin/update-full

# Monitor indexing progress (check logs)
docker compose logs fastapi --tail 50 -f

# Expected output shows batch progress:
# INFO - Uploaded batch 29/389 (100 points)
# ...continues until batch 389/389

# Check system health
curl http://localhost:8000/health
# Response: {"status":"healthy","qdrant":"connected","timestamp":"..."}

# Check database stats (after indexing completes)
curl http://localhost:8000/stats
# Response: {"total_documents":38894,"vector_size":384,"status":"green"}

# Check indexing status
curl http://localhost:8000/api/admin/update-status
# Response: {"entry_count":38894,"last_full_update":"2025-06-29T19:00:00Z"}

# Local development (stdio) - default mode
python -m src.anime_mcp.server

# HTTP transport
python -m src.anime_mcp.server --mode http --host 0.0.0.0 --port 8001

# Server-Sent Events (SSE)
python -m src.anime_mcp.server --mode sse --host 0.0.0.0 --port 8001

# Streamable HTTP transport
python -m src.anime_mcp.server --mode streamable --host 0.0.0.0 --port 8001

# With verbose logging
python -m src.anime_mcp.server --mode sse --verbose

# Local development (stdio) - default mode
python -m src.anime_mcp.modern_server

# Server-Sent Events (SSE)
python -m src.anime_mcp.modern_server --mode sse --host 0.0.0.0 --port 8001

# With verbose logging
python -m src.anime_mcp.modern_server --mode sse --verbose

# Test MCP functionality
python scripts/test_mcp_server_comprehensive.py

# MCP Server Configuration
SERVER_MODE=stdio          # Core server: stdio, http, sse, streamable | Modern server: stdio, sse
MCP_HOST=0.0.0.0          # HTTP server host (for HTTP modes)
MCP_PORT=8001             # HTTP server port (for HTTP modes)

{
  "mcpServers": {
    "anime-search": {
      "command": "python",
      "args": ["-m", "src.anime_mcp.modern_server"],
      "cwd": "/path/to/anime-mcp-server"
    }
  }
}

# Text search (query only)
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "action adventure anime",
    "limit": 5
  }'

# Similar search (anime_id only)
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "anime_id": "cac1eeaeddf7",
    "limit": 5
  }'

# Image search with base64 data
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "image_data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "limit": 5
  }'

# Visual similarity search (anime_id + visual_similarity flag)
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "anime_id": "cac1eeaeddf7",
    "visual_similarity": true,
    "limit": 5
  }'

# Multimodal search (query + image_data)
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mecha anime",
    "image_data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...",
    "text_weight": 0.7,
    "limit": 10
  }'

# Text search with form data
curl -X POST http://localhost:8000/api/search/ \
  -F "query=action adventure anime" \
  -F "limit=5"

# Similar search with form data
curl -X POST http://localhost:8000/api/search/ \
  -F "anime_id=cac1eeaeddf7" \
  -F "limit=5"

# Image search with file upload
curl -X POST http://localhost:8000/api/search/ \
  -F "image=@anime_poster.jpg" \
  -F "limit=5"

# Visual similarity search with form data
curl -X POST http://localhost:8000/api/search/ \
  -F "anime_id=cac1eeaeddf7" \
  -F "visual_similarity=true" \
  -F "limit=5"

# Multimodal search with file upload
curl -X POST http://localhost:8000/api/search/ \
  -F "query=mecha anime" \
  -F "image=@robot_poster.jpg" \
  -F "text_weight=0.7" \
  -F "limit=10"

# Search by genre
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "action adventure", "limit": 5}'

# Search by studio
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "studio ghibli", "limit": 3}'

# Search by theme
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "romantic comedy", "limit": 5}'

# Complex semantic search
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mecha robots fighting in space",
    "limit": 10
  }'

# AI-powered natural language understanding
curl -X POST http://localhost:8000/api/workflow/smart-conversation \
  -H "Content-Type: application/json" \
  -d '{"message": "find me 5 mecha anime from 2020s but not too violent"}'

# Response includes extracted parameters:
# {
#   "current_context": {
#     "query": "mecha anime",           # Cleaned query
#     "limit": 5,                      # Extracted from "find me 5"
#     "filters": {
#       "year_range": [2020, 2029],    # From "2020s"
#       "genres": ["mecha"],           # Detected genre
#       "exclusions": ["violent"]      # From "but not too violent"
#     }
#   }
# }

# Start standard conversation
curl -X POST http://localhost:8000/api/workflow/conversation \
  -H "Content-Type: application/json" \
  -d '{"message": "Find me some good action anime"}'

# Smart orchestration for complex queries
curl -X POST http://localhost:8000/api/workflow/smart-conversation \
  -H "Content-Type: application/json" \
  -d '{
    "message": "find action anime but not horror and similar to attack on titan",
    "enable_smart_orchestration": true,
    "max_discovery_depth": 3
  }'

# Continue existing conversation
curl -X POST http://localhost:8000/api/workflow/conversation \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Find something similar but more romantic",
    "session_id": "existing-session-id"
  }'

# Multimodal conversation with image
curl -X POST http://localhost:8000/api/workflow/multimodal \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Find anime similar to this image",
    "image_data": "base64_encoded_image_data",
    "text_weight": 0.7
  }'

# Get conversation history
curl http://localhost:8000/api/workflow/conversation/session-id

# Check workflow system health
curl http://localhost:8000/api/workflow/health

{
  "query": "dragon ball",
  "results": [
    {
      "anime_id": "cac1eeaeddf7",
      "title": "Dragon Ball Z", 
      "synopsis": "Description text",
      "type": "TV",
      "episodes": 291,
      "tags": ["action", "adventure", "fighting"],
      "studios": ["toei animation co., ltd."],
      "picture": "https://cdn.myanimelist.net/images/anime/1277/142022.jpg",
      "score": 0.7822759,
      "year": 1989,
      "season": "spring",
      "myanimelist_id": 813,
      "anilist_id": 813
    }
  ],
  "total_results": 1,
  "processing_time_ms": 45.2
}

{
  "session_id": "string - Session identifier",
  "messages": "array - Conversation history", 
  "workflow_steps": "array - Executed workflow steps",
  "current_context": {
    "query": "string - Processed query",
    "limit": "integer - Result limit",
    "filters": "object - Applied filters", 
    "results": "array[AnimeResult] - Search results"
  },
  "user_preferences": "object - Learned user preferences"
}

{
  "error": "string - Error message",
  "detail": "string - Detailed error information", 
  "status_code": "integer - HTTP status code"
}

{
  "filters": {
    "year_range": [2020, 2029],        // From "2020s"
    "year": 2019,                      // From "2019" 
    "genres": ["mecha", "action"],     // From "mecha action anime"
    "exclusions": ["horror", "violent"], // From "but not horror or violent"
    "studios": ["Studio Ghibli"],      // From "Studio Ghibli movies"
    "anime_types": ["Movie"],          // From "movies" or "films"
    "mood": ["light", "funny"]         // From "light-hearted" or "funny"
  }
}

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

# Test search
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "dragon ball", "limit": 5}'

# Stats
curl http://localhost:8000/stats

# 1. Health check
curl http://localhost:8000/health

# 2. Database stats  
curl http://localhost:8000/stats

# 3. Simple search
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "dragon ball", "limit": 5}'

# 4. Semantic search
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{"query": "mecha robots fighting in space", "limit": 10}'

# Test natural language parameter extraction
curl -X POST http://localhost:8000/api/workflow/smart-conversation \
  -H "Content-Type: application/json" \
  -d '{"message": "find me 5 mecha anime from 2020s but not too violent"}'

# Test studio + year extraction
curl -X POST http://localhost:8000/api/workflow/smart-conversation \
  -H "Content-Type: application/json" \
  -d '{"message": "show me top 3 Studio Ghibli movies from 90s"}'

# Test complex exclusions
curl -X POST http://localhost:8000/api/workflow/smart-conversation \
  -H "Content-Type: application/json" \
  -d '{"message": "find action adventure anime but not romance or horror"}'

# Image search with base64 data
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{"image_data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...", "limit": 5}'

# Visual similarity search
curl -X POST http://localhost:8000/api/search/ \
  -H "Content-Type: application/json" \
  -d '{"anime_id": "cac1eeaeddf7", "visual_similarity": true, "limit": 5}'

# Multimodal workflow
curl -X POST http://localhost:8000/api/workflow/multimodal \
  -H "Content-Type: application/json" \
  -d '{"message": "find anime similar to this style", "image_data": "base64_data", "text_weight": 0.7}'

# Standard conversation
curl -X POST http://localhost:8000/api/workflow/conversation \
  -H "Content-Type: application/json" \
  -d '{"message": "Find me some good action anime"}'

# Smart orchestration with complex query
curl -X POST http://localhost:8000/api/workflow/smart-conversation \
  -H "Content-Type: application/json" \
  -d '{
    "message": "find mecha anime but not too violent and similar to gundam",
    "enable_smart_orchestration": true,
    "max_discovery_depth": 3
  }'

# Session management
curl http://localhost:8000/api/workflow/conversation/session-id  # Get history
curl -X DELETE http://localhost:8000/api/workflow/conversation/session-id  # Delete session

# Test MCP server (comprehensive verification)
python scripts/test_mcp_server_comprehensive.py

# With detailed output and image testing
python scripts/test_mcp_server_comprehensive.py --detailed

# Skip image tests (if CLIP not available)
python scripts/test_mcp_server_comprehensive.py --skip-image-tests

# Expected output:
# Starting comprehensive FastMCP Anime Server verification...
# MCP session initialized
# Available tools: ['search_anime', 'get_anime_details', 'find_similar_anime', 'get_anime_stats', 'search_anime_by_image', 'find_visually_similar_anime', 'search_multimodal_anime']
# All expected MCP tools are available
# Basic search test successful
# Stats test successful
# Testing image search functionality...
# Image search returned 3 results
# Visual similarity search returned 2 results
# Multimodal search returned 3 results
# Testing database health and statistics...
# Qdrant connection verified
# Total anime entries: 38,894
# All tests completed successfully!

# Start MCP server in one terminal
source venv/bin/activate
python -m src.anime_mcp.modern_server

# Use the automated test script (recommended approach)
python scripts/test_mcp_server_comprehensive.py

# Start SSE MCP server
python -m src.anime_mcp.modern_server --mode sse --port 8001

# Test SSE endpoint accessibility
curl http://localhost:8001/sse/

# Test with compatible MCP clients
# Endpoint: http://localhost:8001/sse/

# Run full test suite
python run_tests.py

# Run specific test categories
pytest tests/unit/ -v
pytest tests/integration/ -v

# Test AI-powered query understanding
pytest tests/unit/services/test_llm_service.py -v
pytest tests/unit/langgraph/test_llm_integration.py -v

# Test smart orchestration features
pytest tests/unit/langgraph/test_smart_orchestration.py -v

# Run tests with coverage
pytest tests/ --cov=src --cov-report=html

# Qdrant Configuration
QDRANT_URL=http://localhost:6333          # Vector database URL
QDRANT_COLLECTION_NAME=anime_database     # Collection name

# Server Configuration
HOST=0.0.0.0                              # FastAPI bind host
PORT=8000                                 # FastAPI port
DEBUG=True                                # Debug mode

# Vector Search Configuration
FASTEMBED_MODEL=BAAI/bge-small-en-v1.5    # Embedding model
QDRANT_VECTOR_SIZE=384                    # Vector dimensions
QDRANT_DISTANCE_METRIC=cosine             # Distance function

# Multi-Vector Configuration (Image Search)
ENABLE_MULTI_VECTOR=true                  # Enable image search features
IMAGE_VECTOR_SIZE=512                     # CLIP embedding dimensions
CLIP_MODEL=ViT-B/32                       # CLIP model for image processing

# API Configuration
API_TITLE=Anime MCP Server                # API title
API_VERSION=1.0.0                         # API version
ALLOWED_ORIGINS=*                         # CORS origins

# LLM Configuration (AI-Powered Query Understanding)
OPENAI_API_KEY=your_openai_key_here       # OpenAI API key for intelligent query parsing
ANTHROPIC_API_KEY=your_anthropic_key_here # Anthropic API key (alternative)
LLM_PROVIDER=openai                       # Default LLM provider: openai, anthropic

# Test MCP server communication
python scripts/test_mcp.py

# Start MCP server for AI integration
python -m src.anime_mcp.server

# MCP Server Management
python -m src.anime_mcp.modern_server                            # Start MCP server (stdio mode)
python -m src.anime_mcp.modern_server --mode sse --port 8001     # Start MCP server (SSE mode)
python -m src.anime_mcp.modern_server --help                     # View all CLI options

# Data Management
python scripts/migrate_to_multivector.py --dry-run    # Test collection migration
python scripts/migrate_to_multivector.py             # Migrate to multi-vector
python scripts/add_image_embeddings.py --batch-size 100  # Process image embeddings

# Testing & Verification
python scripts/test_mcp_server_comprehensive.py                 # Comprehensive MCP server testing
python scripts/test_mcp_server_comprehensive.py --detailed      # Detailed testing with sample data
python scripts/test_mcp_server_comprehensive.py --skip-image-tests  # Skip image tests if CLIP unavailable
python run_tests.py                                 # Run full test suite

# Data Pipeline
curl -X POST http://localhost:8000/api/admin/update-full    # Full database update
curl -X POST http://localhost:8000/api/admin/update-incremental  # Incremental update

# Code formatting and linting (recommended order)
autoflake --recursive --in-place --remove-all-unused-imports --remove-unused-variables src/ tests/ scripts/
isort src/ tests/ scripts/
black src/ tests/ scripts/

# Check formatting (CI/pre-commit)
autoflake --check --recursive --remove-all-unused-imports src/ tests/ scripts/
isort --check-only src/ tests/ scripts/
black --check src/ tests/ scripts/

# Type checking
mypy src/

# Run tests
pytest tests/ -v

# Check if port is in use
netstat -tulpn | grep :8001

# Use different port
python -m src.anime_mcp.modern_server --mode sse --port 8002

# Check server logs with verbose output
python -m src.anime_mcp.modern_server --mode sse --verbose

# Verify Qdrant connection
curl http://localhost:6333/health

# Check container logs
docker compose logs fastapi --tail 50
docker compose logs mcp-server --tail 50
docker compose logs qdrant --tail 50

# Monitor real-time logs (useful during indexing)
docker compose logs fastapi -f

# Check container status
docker compose ps

# Restart specific service
docker compose restart fastapi
docker compose restart mcp-server

# Rebuild containers after code changes
docker compose build --no-cache
docker compose up -d --force-recreate

# Check indexing progress
curl http://localhost:8000/api/admin/update-status

# Monitor indexing in real-time
docker compose logs fastapi -f | grep "batch"

# Check database statistics
curl http://localhost:8000/stats

# Restart indexing if it fails
curl -X POST http://localhost:8000/api/admin/update-full

# Core server valid modes: stdio, http, sse, streamable
python -m src.anime_mcp.server --mode invalid
# Error: argument --mode: invalid choice: 'invalid'

# Modern server valid modes: stdio, sse
python -m src.anime_mcp.modern_server --mode invalid
# Error: argument --mode: invalid choice: 'invalid'