# Updation MCP Local Server

**Production-grade Model Context Protocol (MCP) server with LLM-agnostic architecture**

## 🌟 Key Features

- ✅ **LLM-Agnostic**: Seamlessly switch between OpenAI, Claude, Gemini, or Azure OpenAI
- ✅ **Production-Ready**: Structured logging, metrics, error handling, and observability
- ✅ **Scalable**: Redis-backed state management for horizontal scaling
- ✅ **Secure**: RBAC, rate limiting, input validation, and secret management
- ✅ **Modular**: Auto-discovery tool architecture for easy extensibility
- ✅ **Type-Safe**: Full Pydantic validation throughout
- ✅ **Resilient**: Circuit breakers, retries, and graceful degradation

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    FastAPI Web Chat API                      │
│                    (Port 8002)                               │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  LLM Orchestrator                            │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  LLM Provider Abstraction Layer                      │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │   │
│  │  │ OpenAI   │ │ Claude   │ │ Gemini   │            │   │
│  │  └──────────┘ └──────────┘ └──────────┘            │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    MCP Server (Port 8050)                    │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Auto-Discovery Tool Registry                        │   │
│  │  ├── User Tools (subscriptions, bookings, etc.)     │   │
│  │  ├── Organization Tools (locations, resources)      │   │
│  │  └── Payment Tools                                  │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              External Services                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Updation API │  │    Redis     │  │  Prometheus  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
```

## 🚀 Quick Start

### 1. Prerequisites

- **Python 3.11+**
- **Redis** (required for conversation memory - see setup below)
- **UV package manager** (recommended) or pip

### 2. Installation

```bash
# Clone or navigate to project
cd /Users/saimanvithmacbookair/Desktop/Updation_MCP_Local

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Or with UV (faster)
uv pip install -e .
```

### 3. Install Redis (Mac M2)

**Redis is required for conversation memory to work!**

```bash
# Install Redis via Homebrew
brew install redis

# Start Redis (background service)
brew services start redis

# Verify it's running
redis-cli ping  # Should return: PONG
```

**See `REDIS_SETUP.md` for detailed instructions and troubleshooting.**

### 4. Configuration

```bash
# Copy environment template
cp .env.example .env

# Edit .env with your actual values
nano .env  # or use your favorite editor
```

**Required settings:**
```bash
# LLM Provider
LLM_PROVIDER=openai
OPENAI_API_KEY=your-key-here

# Laravel API
UPDATION_API_BASE_URL=http://127.0.0.1:8000/api

# Redis (should already be correct)
REDIS_ENABLED=true
REDIS_URL=redis://localhost:6379/0

# Enable auto-reload for development (optional)
WEB_CHAT_RELOAD=true  # Auto-restart on code changes
```

### 5. Run the Services

**Terminal 1: MCP Server**
```bash
source .venv/bin/activate
python -m src.mcp_server.server
```

**Terminal 2: Web Chat API (with auto-reload)**
```bash
source .venv/bin/activate
python -m src.web_chat.main
```

**Note:** With `WEB_CHAT_RELOAD=true`, Terminal 2 will auto-restart when you edit code!

# Terminal 3 (optional): Start metrics server
python -m src.observability.metrics_server
```

### 6. Test the Setup

**Quick health check:**
```bash
curl http://localhost:8002/health
```

**Test chat with Bearer token:**
```bash
# Replace with your actual Laravel token
TOKEN="11836|UAc9YiEKc9zO9MvNHKQqY9WwdkxW7qQyw3mqyNK5"

curl -X POST http://localhost:8002/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message": "What can I do?"}'
```

**Test conversation memory:**
```bash
# First message
curl -X POST http://localhost:8002/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "My name is John"}'

# Second message (should remember)
curl -X POST http://localhost:8002/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is my name?"}'
```

**Expected:** AI should respond "Your name is John" ✅

**Check cache stats:**
```bash
# User cache (Bearer tokens)
curl http://localhost:8002/cache/stats

# Redis conversation keys
redis-cli keys "conversation:*"
```

**See `BEARER_TOKEN_AUTH.md` for complete API documentation.**

## 📁 Project Structure

```
Updation_MCP_Local/
├── src/
│   ├── config/              # Configuration management
│   │   ├── __init__.py
│   │   └── settings.py      # Pydantic settings with validation
│   │
│   ├── core/                # Core shared utilities
│   │   ├── __init__.py
│   │   ├── envelope.py      # Standard response envelope
│   │   ├── exceptions.py    # Custom exceptions
│   │   └── security.py      # RBAC and auth helpers
│   │
│   ├── llm/                 # LLM abstraction layer
│   │   ├── __init__.py
│   │   ├── base.py          # Abstract base provider
│   │   ├── openai.py        # OpenAI implementation
│   │   ├── anthropic.py     # Claude implementation
│   │   ├── google.py        # Gemini implementation
│   │   └── factory.py       # Provider factory
│   │
│   ├── mcp_server/          # MCP server implementation
│   │   ├── __init__.py
│   │   ├── server.py        # Main MCP server
│   │   └── tools/           # Tool modules
│   │       ├── __init__.py  # Auto-discovery
│   │       ├── users/       # User-related tools
│   │       ├── organizations/ # Org-related tools
│   │       └── payments/    # Payment tools
│   │
│   ├── orchestrator/        # LLM orchestration
│   │   ├── __init__.py
│   │   ├── client.py        # MCP client wrapper
│   │   ├── processor.py     # Query processing logic
│   │   └── policy.py        # RBAC policies
│   │
│   ├── web_chat/            # FastAPI web interface
│   │   ├── __init__.py
│   │   ├── main.py          # FastAPI app
│   │   ├── routes/          # API routes
│   │   ├── middleware/      # Custom middleware
│   │   └── dependencies.py  # FastAPI dependencies
│   │
│   ├── observability/       # Logging, metrics, tracing
│   │   ├── __init__.py
│   │   ├── logging.py       # Structured logging setup
│   │   ├── metrics.py       # Prometheus metrics
│   │   └── tracing.py       # Distributed tracing
│   │
│   └── storage/             # State management
│       ├── __init__.py
│       ├── redis_client.py  # Redis wrapper
│       └── memory.py        # In-memory fallback
│
├── tests/                   # Test suite
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
├── scripts/                 # Utility scripts
│   ├── setup_redis.sh
│   └── health_check.sh
│
├── .env.example            # Environment template
├── .gitignore
├── pyproject.toml          # Dependencies
├── README.md
└── docker-compose.yml      # Local development stack
```

## 🔧 Configuration

All configuration is managed through environment variables (see `.env.example`).

### Switching LLM Providers

Simply change the `LLM_PROVIDER` environment variable:

```bash
# Use OpenAI
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

# Use Claude
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Use Gemini
LLM_PROVIDER=google
GOOGLE_API_KEY=...
```

No code changes required! The system automatically routes to the correct provider.

## 🛠️ Development

### Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

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

# Run specific test file
pytest tests/unit/test_llm_providers.py
```

### Code Quality

```bash
# Format code
ruff format .

# Lint
ruff check .

# Type checking
mypy src/
```

## 📊 Monitoring

### Metrics

Prometheus metrics available at `http://localhost:9090/metrics`:

- `mcp_requests_total` - Total requests by tool and status
- `mcp_request_duration_seconds` - Request latency histogram
- `mcp_active_connections` - Current active connections
- `llm_api_calls_total` - LLM API calls by provider
- `llm_tokens_used_total` - Token usage tracking

### Logs

Structured JSON logs with trace IDs for correlation:

```json
{
  "timestamp": "2024-01-15T10:30:00Z",
  "level": "info",
  "event": "tool_executed",
  "tool_name": "get_user_subscriptions",
  "user_id": 123,
  "duration_ms": 245,
  "trace_id": "abc-123-def"
}
```

## 🔒 Security

- **RBAC**: Role-based access control for all tools
- **Rate Limiting**: Per-user and global rate limits
- **Input Validation**: Pydantic schemas for all inputs
- **Secret Management**: Never log or expose API keys
- **CORS**: Configurable allowed origins
- **HTTPS**: Enforce HTTPS in production

## 🚢 Deployment

### Docker

```bash
docker build -t updation-mcp:latest .
docker run -p 8050:8050 -p 8002:8002 --env-file .env updation-mcp:latest
```

### Docker Compose

```bash
docker-compose up -d
```

## 📝 Adding New Tools

1. Create tool module in `src/mcp_server/tools/your_domain/`
2. Implement `tool.py` with `register(mcp)` function
3. Add schemas in `schemas.py`
4. Add business logic in `service.py`
5. Auto-discovery handles the rest!

Example:
```python
# src/mcp_server/tools/your_domain/tool.py
from mcp.server.fastmcp import FastMCP

def register(mcp: FastMCP) -> None:
    @mcp.tool()
    async def your_tool(param: str):
        \"\"\"Tool description for LLM.\"\"\"
        return {"result": "data"}
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run quality checks: `ruff check . && pytest`
5. Submit a pull request

## 📄 License

[Your License Here]

## 🆘 Support

For issues or questions:
- GitHub Issues: [Your Repo]
- Email: [Your Email]
- Docs: [Your Docs URL]