# Complete Setup & Usage Guide
## 🎉 System Complete!
Your production-grade, LLM-agnostic MCP server is ready. Here's everything you need to know.
---
## 📦 Installation
```bash
cd /Users/saimanvithmacbookair/Desktop/Updation_MCP_Local
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install all dependencies
pip install -e .
# Or with UV (faster)
uv pip install -e .
```
---
## ⚙️ Configuration
### 1. Create .env file
```bash
cp .env.example .env
```
### 2. Configure for your provider
**Option A: OpenAI**
```bash
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o
```
**Option B: Claude**
```bash
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key-here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
```
**Option C: Gemini**
```bash
LLM_PROVIDER=google
GOOGLE_API_KEY=your-key-here
GOOGLE_MODEL=gemini-2.0-flash-exp
```
### 3. Configure Updation API
```bash
UPDATION_API_BASE_URL=http://your-updation-api.com/api
```
### 4. Optional: Redis (Recommended for Production)
```bash
# Install Redis
brew install redis # Mac
# or: apt-get install redis # Linux
# Start Redis
redis-server
# In .env:
REDIS_ENABLED=true
REDIS_URL=redis://localhost:6379/0
```
---
## 🚀 Running the System
### Development Mode (All in One Terminal)
```bash
# Terminal 1: Start MCP Server
python -m src.mcp_server.server
# Terminal 2: Start Web Chat API
python -m src.web_chat.main
# Terminal 3: Test
curl http://localhost:8002/health
```
### Production Mode (with Redis)
```bash
# Start Redis
redis-server &
# Start MCP Server
python -m src.mcp_server.server &
# Start Web Chat API
python -m src.web_chat.main &
```
---
## 🧪 Testing
### 1. Health Check
```bash
curl http://localhost:8002/health
```
Expected response:
```json
{
"status": "healthy",
"service": "updation_mcp_chat",
"version": "1.0.0",
"environment": "development"
}
```
### 2. Readiness Check
```bash
curl http://localhost:8002/ready
```
### 3. Test Chat
```bash
curl -X POST http://localhost:8002/chat \
-H "Content-Type: application/json" \
-d '{
"user_id": 1,
"organization_id": 1,
"role": 3,
"message": "Hello! What can you help me with?"
}'
```
### 4. Test with Different LLM
```bash
# Change in .env:
LLM_PROVIDER=anthropic # or google
# Restart services
# Test again - it just works!
```
---
## 🏗️ Architecture Overview
```
┌─────────────────────────────────────────────────────────────┐
│ Client Application │
│ (Your Frontend/Mobile App) │
└────────────────────────┬────────────────────────────────────┘
│ HTTP POST /chat
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Web Chat API (Port 8002) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ - Rate Limiting │ │
│ │ - CORS │ │
│ │ - Request Logging │ │
│ │ - Metrics Collection │ │
│ └──────────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Orchestrator │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Query Processor │ │
│ │ - Gets tools from MCP (RBAC-filtered) │ │
│ │ - Calls LLM with tools │ │
│ │ - Executes tool calls │ │
│ │ - Returns final answer │ │
│ └──────────────────────────────────────────────────────┘ │
└──────────┬────────────────────────────────┬─────────────────┘
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────────────┐
│ LLM Provider │ │ MCP Server (Port 8050) │
│ (via Abstraction) │ │ ┌────────────────────────┐ │
│ ┌────────────────┐ │ │ │ Auto-Discovery │ │
│ │ OpenAI │ │ │ │ Tool Registry │ │
│ │ Claude │ │ │ │ - Example Tools │ │
│ │ Gemini │ │ │ │ - (Your Updation │ │
│ │ Azure OpenAI │ │ │ │ tools go here) │ │
│ └────────────────┘ │ │ └────────────────────────┘ │
└──────────────────────┘ └──────────────────────────────┘
│ │
└────────────┬───────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ Supporting Services │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Redis │ │ Prometheus │ │ Updation │ │
│ │ (Conversations)│ │ (Metrics) │ │ API │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## 🔧 Adding Updation-Specific Tools
When you're ready to add contract/vendor/dealership tools:
### 1. Create Tool Package
```bash
mkdir -p src/mcp_server/tools/contracts
touch src/mcp_server/tools/contracts/__init__.py
touch src/mcp_server/tools/contracts/tool.py
touch src/mcp_server/tools/contracts/schemas.py
touch src/mcp_server/tools/contracts/service.py
```
### 2. Implement Tool
```python
# src/mcp_server/tools/contracts/tool.py
from mcp.server.fastmcp import FastMCP
from src.core import wrap_response
from src.observability import get_logger
logger = get_logger(__name__)
def register(mcp: FastMCP) -> None:
@mcp.tool()
async def get_contracts(
user_id: int,
organization_id: int,
platform_id: int = None,
dealership_id: int = None,
trace_id: str = None,
):
"""Get contracts for the user's hierarchy level."""
# Your implementation here
# - Fetch from Updation API
# - Filter by hierarchy (org/platform/dealership)
# - Return in envelope format
return wrap_response(
tool_name="get_contracts",
trace_id=trace_id,
data={"contracts": [...]},
)
```
### 3. Update RBAC
```python
# src/core/security.py
# Add to appropriate tool sets:
DEALERSHIP_TOOLS: Set[str] = {
"get_dealership_contracts", # Add your tools
"upload_contract",
...
}
```
### 4. Restart - Auto-Discovery Handles the Rest!
```bash
# Restart MCP server
python -m src.mcp_server.server
```
---
## 📊 Monitoring
### Logs
Structured JSON logs with trace IDs:
```bash
# View logs
tail -f logs/updation_mcp.log
# Or if logging to stdout:
python -m src.web_chat.main | jq .
```
### Metrics
Prometheus metrics at `http://localhost:9090/metrics`:
- `mcp_requests_total` - Tool usage
- `llm_api_calls_total` - LLM API calls by provider
- `llm_tokens_used_total` - Token usage
- `http_requests_total` - HTTP requests
### Grafana Dashboard
```bash
# Import metrics into Grafana
# Use Prometheus as data source
# Query: rate(mcp_requests_total[5m])
```
---
## 🔒 Security Best Practices
### 1. Environment Variables
```bash
# NEVER commit .env to git
# Use secrets management in production:
# - AWS Secrets Manager
# - HashiCorp Vault
# - Kubernetes Secrets
```
### 2. API Keys
```bash
# Rotate keys regularly
# Use different keys per environment
# Monitor usage for anomalies
```
### 3. Rate Limiting
```bash
# Adjust in .env:
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_PER_HOUR=1000
```
### 4. CORS
```bash
# Production: Use specific origins
CORS_ORIGINS=https://app.updation.com,https://staging.updation.com
# Development: Can use localhost
CORS_ORIGINS=http://localhost:3000
```
---
## 🐛 Troubleshooting
### MCP Server Won't Start
```bash
# Check if port is in use
lsof -i :8050
# Check logs
python -m src.mcp_server.server
# Verify configuration
python -c "from src.config import settings; print(settings.model_dump())"
```
### LLM Provider Errors
```bash
# Verify API key
python -c "from src.llm import get_llm_provider; print(get_llm_provider())"
# Check provider status
# OpenAI: https://status.openai.com
# Anthropic: https://status.anthropic.com
# Google: https://status.cloud.google.com
```
### Redis Connection Issues
```bash
# Check Redis is running
redis-cli ping
# Test connection
python -c "import redis; r = redis.from_url('redis://localhost:6379/0'); print(r.ping())"
# Fallback to in-memory
REDIS_ENABLED=false
```
### Rate Limiting Too Strict
```bash
# Increase limits in .env
RATE_LIMIT_PER_MINUTE=120
RATE_LIMIT_PER_HOUR=5000
# Or disable for testing
RATE_LIMIT_ENABLED=false
```
---
## 🚢 Deployment
### Docker (Recommended)
```dockerfile
# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -e .
CMD ["python", "-m", "src.web_chat.main"]
```
```bash
# Build
docker build -t updation-mcp:latest .
# Run
docker run -p 8002:8002 --env-file .env updation-mcp:latest
```
### Docker Compose
```yaml
# docker-compose.yml
version: '3.8'
services:
redis:
image: redis:7-alpine
ports:
- "6379:6379"
mcp-server:
build: .
command: python -m src.mcp_server.server
ports:
- "8050:8050"
env_file: .env
depends_on:
- redis
web-api:
build: .
command: python -m src.web_chat.main
ports:
- "8002:8002"
env_file: .env
depends_on:
- mcp-server
- redis
```
```bash
docker-compose up -d
```
---
## 📚 Next Steps
1. **Test the System**: Run through all the test commands above
2. **Add Your Tools**: Create Updation-specific tools (contracts, vendors, etc.)
3. **Configure Production**: Set up Redis, proper secrets, monitoring
4. **Deploy**: Use Docker/Kubernetes for production deployment
5. **Monitor**: Set up Grafana dashboards for metrics
---
## 🆘 Getting Help
- Check logs: Structured JSON with trace IDs
- Review metrics: Prometheus endpoint
- Test components: Health and readiness checks
- Verify config: `python -c "from src.config import settings; print(settings.model_dump())"`
---
## 🎯 Key Takeaways
✅ **LLM-Agnostic**: Switch providers by changing ONE env var
✅ **Production-Ready**: Logging, metrics, error handling, rate limiting
✅ **Scalable**: Redis-backed, horizontal scaling ready
✅ **Secure**: RBAC, input validation, secret management
✅ **Maintainable**: Auto-discovery, clear structure, comprehensive docs
✅ **Type-Safe**: Pydantic everywhere, catch errors early
**You now have a solid foundation that's 10x better than your old project!**
