README.md•35.6 kB
# Comprehensive Lila MCP Server
A standalone, comprehensive implementation of the Lila psychological intelligence system as an MCP (Model Context Protocol) server.
## Overview
This is a **truly standalone** implementation that provides complete psychological intelligence capabilities without requiring the main Lila system. It includes:
- **Complete MCP Interface**: 8 tools, 3 prompts, 9 resources (2 direct + 7 templated)
- **Comprehensive Psychology**: Full PersonaAgent system, attachment theory, Big Five traits
- **Neo4j Integration**: Complete graph database operations with automatic connection
- **Autonomous Workflows**: PydanticAI-based decision making and strategy selection
- **Logfire Telemetry**: Native observability and monitoring
- **Self-Contained**: No dependencies on main Lila codebase
## Features
### Resources (9 total: 2 direct + 7 templated)
**Direct Resources:**
- `neo4j://personas/all` - All personas with complete psychological profiles
- `config://workflow-strategies` - Available autonomous workflow strategies
**Templated Resources:**
- `neo4j://personas/{persona_id}/relationships` - All relationships for a specific persona
- `neo4j://interactions/recent/{count}` - Recent interactions with psychological analysis
- `neo4j://relationships/{persona1_id}/{persona2_id}/current` - Current relationship state
- `neo4j://relationships/{persona1_id}/{persona2_id}/history` - Complete interaction history
- `telemetry://workflow-traces/{timerange}` - Telemetry traces from autonomous workflows
- `telemetry://conversation-quality/{persona_id}` - Conversation quality metrics
- `config://goal-templates/{scenario}` - Goal templates for relationship scenarios
### Tools (8 comprehensive psychological intelligence tools)
- `update_relationship_metrics` - Update trust, intimacy, and strength between personas
- `record_interaction` - Record interactions with psychological analysis
- `commit_relationship_state` - Explicitly persist relationship state (CQRS Command)
- `finalize_demo_session` - Finalize all relationship states at session end
- `analyze_persona_compatibility` - Assess relationship potential using attachment theory
- `autonomous_strategy_selection` - Select optimal strategy based on psychological modeling
- `assess_goal_progress` - Assess progress towards relationship goals
- `generate_contextual_response` - Generate psychologically authentic responses
### Prompts (3 comprehensive assessment prompts)
- `assess_attachment_style` - Determine persona's attachment style from behavioral observations
- `analyze_emotional_climate` - Evaluate conversation emotional dynamics and safety levels
- `generate_secure_response` - Create attachment-security-building responses for scenarios
## Quick Start
**Development Flow**: Test → Develop → Deploy
The recommended approach is to start with immediate visual testing (`fastmcp dev`), then move to production deployment (`fastmcp run`) once everything works.
### Step 1: Start the Server
The Lila MCP Server is now fully self-contained with no external dependencies:
```bash
# Navigate to standalone MCP directory
cd docker/mcp-standalone
# Start the server with Inspector
fastmcp dev simple_lila_mcp_server.py
# ✅ No external dependencies required
# ✅ Complete psychological intelligence system
# ✅ All 8 tools, 3 prompts, 9 resources working
# ✅ FastMCP debug logging enabled
```
### Step 2: Test with MCP Inspector
**The server provides:**
```bash
# Inspector provides:
# ✅ Immediate web UI for testing (opens with auth token)
# ✅ Visual testing of all 8 tools, 3 prompts, resources
# ✅ Real-time protocol debugging
# ✅ STDIO transport (works immediately)
```
**What you'll see:**
- Inspector URL with token: `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>`
- Click the URL to open the web interface
- Test resources like `neo4j://personas/all`
- Test tools like `analyze_persona_compatibility`
- Verify all functionality works before deployment
**Expected Components:**
- **Simplified Server**: 6 resources, 8 tools, 3 prompts (mock data)
- **Full Server**: 9 resources, 8 tools, 3 prompts (live Neo4j data)
### Step 2: Quick Capabilities Check
```bash
# Verify server capabilities without full Inspector
fastmcp inspect # Uses fastmcp.json auto-configuration
# Should show:
# Server: lila-psychological-relationships
# Components: Tools: 8, Prompts: 3, Resources: 2, Templates: 7
# Environment: FastMCP: 2.12.3, MCP: 1.14.0
# ✅ Successfully connected to Neo4j GraphDB
```
### Step 3: Production HTTP Deployment
Once testing confirms everything works, deploy with HTTP transport for production:
```bash
# HTTP transport for production deployment
fastmcp run # Uses fastmcp.json (port 8765)
fastmcp run --port 9000 # Override port if needed
# This provides:
# 🚀 Production-ready HTTP transport
# 🌐 Network accessible (can migrate to external server)
# 📡 Compatible with MCP clients (Claude Desktop, Cursor, etc.)
# 🔄 Scalable for multiple concurrent connections
```
**Important**: HTTP endpoint serves MCP JSON-RPC protocol, not REST API. See [MCP Client Testing](#mcp-client-testing) section for proper testing methods.
### Alternative: Docker Deployment
```bash
cd docker/mcp-standalone
# Full stack deployment
docker compose up -d # Includes Neo4j + MCP server
# Or minimal deployment
docker compose up -d mcp-server # MCP server only
```
### Fallback: Explicit Dependencies
If `fastmcp.json` auto-detection fails:
```bash
# Development with explicit dependencies
fastmcp dev simple_lila_mcp_server.py --with fastmcp --with neo4j --with pydantic --with python-dotenv
# Custom Inspector port if needed
fastmcp dev simple_lila_mcp_server.py --with fastmcp --with neo4j --with pydantic --with python-dotenv --server-port 6350
# HTTP deployment with explicit dependencies
fastmcp run simple_lila_mcp_server.py --transport http --port 8765 --with fastmcp --with neo4j --with pydantic --with python-dotenv
```
**Environment Configuration**:
All settings are configured in `.env` file - no need to pass environment variables manually:
- `NEO4J_URI=bolt://localhost:7687`
- `NEO4J_USER=neo4j`
- `NEO4J_PASSWORD=passw0rd`
- `ENABLE_LOGFIRE_TELEMETRY=true`
- `LOGFIRE_PROJECT_NAME=lila-autonomous-agents`
**Critical Requirements**:
- **Directory**: Must be in `docker/mcp-standalone/` directory
- **Neo4j Running**: Use `docker compose up -d neo4j` from project root
- **Configuration**: Uses `fastmcp.json` auto-configuration (recommended) or `--with` flags (fallback)
- **Transport**: Inspector uses STDIO transport automatically (not HTTP)
**Recommended uv-Native Workflow** (avoids VIRTUAL_ENV conflicts):
```bash
# BEST: Use fastmcp.json auto-configuration
fastmcp dev # Auto-detects everything from fastmcp.json
fastmcp run # HTTP transport with auto-configuration
fastmcp inspect # View capabilities with auto-configuration
# FALLBACK: Explicit dependencies (if auto-detection fails)
fastmcp dev simple_lila_mcp_server.py --with fastmcp --with neo4j --with pydantic --with python-dotenv
```
**Inspector URL**: `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>`
- Token is displayed in console output when server starts
- Use "Connect" button in Inspector interface
- Transport dropdown should show "STDIO" selected
### Quick Inspection
Verify the MCP server capabilities before starting development:
```bash
# Quick capabilities check using fastmcp.json - SIMPLEST!
fastmcp inspect
# Should show:
# Server: lila-psychological-relationships
# Components: Tools: 8, Prompts: 3, Resources: 2, Templates: 7
# Environment: FastMCP: 2.12.3, MCP: 1.14.0
# ✅ Successfully connected to Neo4j GraphDB
# For detailed JSON output:
fastmcp inspect --format fastmcp # FastMCP-specific format
fastmcp inspect --format mcp # Standard MCP protocol format
```
## Understanding MCP Transports
**Why does the Quick Start prioritize `fastmcp dev` (Inspector) over `fastmcp run` (HTTP)?**
The Model Context Protocol (MCP) supports multiple transport mechanisms, each optimized for different use cases:
### STDIO Transport (`fastmcp dev`)
**Use for**: Development, testing, immediate feedback
```bash
fastmcp dev # Creates Inspector web UI
```
**Benefits:**
- ✅ **Immediate visual testing** - Opens web UI with auth token automatically
- ✅ **Interactive debugging** - Click to test resources, tools, prompts in real-time
- ✅ **Protocol inspection** - View JSON-RPC messages in developer tools
- ✅ **Works immediately** - No client library configuration required
- ✅ **Zero setup** - Just one command to start testing
**How it works:**
- FastMCP creates a proxy server that bridges STDIO ↔ HTTP for the web Inspector
- Inspector connects via STDIO (standard input/output) to the MCP server
- Developer gets web UI for interactive testing without HTTP complexity
### HTTP Transport (`fastmcp run`)
**Use for**: Production deployment, client integration
```bash
fastmcp run # Serves MCP over HTTP JSON-RPC
```
**Benefits:**
- ✅ **Production ready** - Network accessible, scalable, SSL-capable
- ✅ **Client compatible** - Works with Claude Desktop, Cursor, custom clients
- ✅ **Multiple connections** - Supports concurrent client connections
- ✅ **Deployable** - Can be containerized, load-balanced, monitored
**How it works:**
- Serves MCP protocol as JSON-RPC over HTTP
- Clients send POST requests with MCP protocol messages
- **Not a REST API** - requires MCP-aware clients, not simple curl/browser access
### Development vs Production Flow
**Recommended workflow:**
1. **Development**: `fastmcp dev` → Visual testing in Inspector
2. **Validation**: `fastmcp inspect` → Verify capabilities
3. **Production**: `fastmcp run` → Deploy with HTTP for clients
**Why this order works:**
- Inspector provides immediate feedback on whether server works
- Once verified with Inspector, HTTP deployment "just works"
- Avoids confusion from HTTP testing complexity during development
### Transport Comparison
| Aspect | STDIO (`fastmcp dev`) | HTTP (`fastmcp run`) |
|--------|----------------------|---------------------|
| **Primary use** | Development testing | Production deployment |
| **Testing method** | Inspector web UI | MCP client libraries |
| **Setup complexity** | One command | Requires client configuration |
| **Debugging** | Interactive web UI | Client library + logs |
| **Accessibility** | Local only | Network accessible |
| **Concurrency** | Single session | Multiple clients |
| **Browser testing** | ✅ Yes (Inspector UI) | ❌ No (needs MCP client) |
## MCP Client Integration
### JSON Configuration Generation (FastMCP V2)
Generate MCP client configuration files for different applications:
```bash
# Auto-configuration using fastmcp.json (Recommended)
fastmcp install claude-desktop # Uses fastmcp.json dependencies
fastmcp install cursor # Uses fastmcp.json dependencies
fastmcp install mcp-json # Generic MCP JSON configuration
# Explicit dependencies (fallback if auto-detection fails)
fastmcp install claude-desktop simple_lila_mcp_server.py --with neo4j --with pydantic --with python-dotenv
fastmcp install cursor simple_lila_mcp_server.py --with neo4j --with pydantic --with python-dotenv
fastmcp install mcp-json simple_lila_mcp_server.py --with neo4j --with pydantic --with python-dotenv
```
### Manual Client Configuration
#### HTTP Transport Configuration (Recommended)
For HTTP-based MCP clients (production ready):
```json
{
"mcpServers": {
"lila-psychology": {
"url": "http://localhost:8765/mcp/",
"transport": "http"
}
}
}
```
**Benefits of HTTP Transport:**
- ✅ **Network accessible** - can deploy to external servers
- ✅ **MCP client compatible** - works with Claude Desktop, Cursor, MCP libraries
- ✅ **Production ready** - supports load balancing, SSL termination
- ✅ **Scalable** - works with container orchestration
## MCP Client Testing
**Important**: MCP HTTP serves JSON-RPC protocol, not REST API. Use MCP-aware clients for testing:
```bash
# ✅ CORRECT: Test with FastMCP client library
python -c "
from fastmcp import Client
import asyncio
async def test():
client = Client('http://localhost:8765/mcp/')
async with client:
# Test resource access
personas = await client.get_resource('neo4j://personas/all')
print('✅ Resources work:', len(personas) if personas else 'No data')
# Test tool execution
result = await client.call_tool('analyze_persona_compatibility', {
'persona_a_id': 'lila',
'persona_b_id': 'alex'
})
print('✅ Tools work:', bool(result))
asyncio.run(test())
"
# ❌ INCORRECT: Don't use simple HTTP tools
# curl http://localhost:8765/mcp/ # Returns 406 Not Acceptable
# Browser access also won't work - MCP needs proper JSON-RPC requests
```
#### Claude Desktop Configuration (STDIO - Development Only)
For local development with STDIO transport:
```json
{
"mcpServers": {
"lila-psychology": {
"command": "fastmcp",
"args": ["run", "/path/to/docker/mcp-standalone/simple_lila_mcp_server.py", "--transport", "stdio"],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "passw0rd",
"ENABLE_LOGFIRE_TELEMETRY": "true"
}
}
}
}
```
#### Cursor Configuration (STDIO - Development Only)
For local development with STDIO transport:
```json
{
"mcpServers": {
"lila-psychology": {
"command": "fastmcp",
"args": ["run", "/path/to/docker/mcp-standalone/simple_lila_mcp_server.py", "--transport", "stdio"],
"env": {
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "passw0rd"
}
}
}
}
```
### Inspector Testing Workflow
1. **Start Inspector (Recommended - Auto-Configuration)**:
```bash
# BEST: Uses fastmcp.json auto-configuration
fastmcp dev # Automatically detects all dependencies and configuration
# Custom Inspector port if needed:
fastmcp dev --server-port 6350 # Avoids port conflicts
# FALLBACK: Explicit dependencies (if auto-detection fails)
fastmcp dev simple_lila_mcp_server.py --with fastmcp --with neo4j --with pydantic --with python-dotenv
```
2. **Access Web Interface**:
- Copy URL with token from console output
- Open in browser: `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<your-token>`
3. **Test Resources**:
- Click **Resources** tab
- Test `neo4j://personas/all` - should return sample personas (Lila, Alex)
- Test `neo4j://personas/lila` - should return detailed Lila profile
- Test `neo4j://interactions/recent/5` - should return interaction history
4. **Test Tools**:
- Click **Tools** tab
- Test `analyze_persona_compatibility`:
```json
{
"persona_a_id": "lila",
"persona_b_id": "alex"
}
```
- Test `query_relationship_metrics` with same parameters
- Test `get_attachment_style_insights`:
```json
{
"persona_id": "lila"
}
```
5. **Test Prompts**:
- Click **Prompts** tab
- Test `assess_attachment_style`:
```json
{
"behavior_description": "Shows consistent emotional availability and comfort with both intimacy and independence"
}
```
- Test `analyze_emotional_climate` with interaction history
- Test `suggest_relationship_interventions` with relationship challenges
6. **Monitor Protocol**:
- View real-time MCP JSON requests/responses
- Check for any errors in console logs
- Verify all capabilities are properly exposed
**FastMCP V2 Configuration Methods**:
```bash
# Option 1: Using fastmcp.json (Recommended - auto-detects everything)
fastmcp dev # Automatically uses fastmcp.json in current directory
# Option 2: Explicit dependency management (fallback)
fastmcp dev simple_lila_mcp_server.py --with fastmcp --with neo4j --with pydantic --with python-dotenv
# Option 3: Project-based configuration
fastmcp project prepare fastmcp.json --output-dir ./env
fastmcp dev --project ./env
# Option 4: Requirements file (alternative)
fastmcp dev simple_lila_mcp_server.py --with-requirements requirements.txt
```
The Inspector provides:
- **Protocol Debugging**: Real-time MCP message inspection
- **Resource Testing**: Interactive resource querying with live data
- **Tool Execution**: Test psychological analysis tools with sample data
- **Prompt Testing**: Validate psychological assessment prompts
- **Schema Validation**: Verify tool/prompt schemas are correct
### Local Development (Alternative)
```bash
cd docker/mcp-standalone
# Install dependencies manually
pip install -r requirements.txt
# Run the server directly
python main.py
```
## Configuration
Environment variables:
```bash
# Database (optional - uses fallback if unavailable)
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=mcp_standalone_password_2025
# Logging
LOG_LEVEL=INFO
LOG_FORMAT=json
# MCP Server
MCP_HOST=0.0.0.0
MCP_PORT=8765
```
## Testing
### Unit Tests
```bash
# Test the implementation
python test_minimal.py
# Should output:
# 🎉 All tests passed! Minimal MCP server is ready.
```
### Interactive Testing with MCP Inspector
The **MCP Inspector** provides the best testing experience:
```bash
# Make sure you're in the docker/mcp-standalone/ directory
cd docker/mcp-standalone
# Start development server with Inspector
fastmcp dev main.py --with neo4j --with pydantic --with python-dotenv
# Or test HTTP server manually
fastmcp run main.py --transport http --port 8765
# Then open Inspector: https://github.com/modelcontextprotocol/inspector
```
**Inspector Testing Workflow**:
1. **Connect**: Select "STDIO" transport in Inspector (for `fastmcp dev`)
2. **Resources**: Test `neo4j://personas/all` - should return sample personas
3. **Tools**: Try `analyze_persona_compatibility` with `{"persona_a_id": "lila", "persona_b_id": "alex"}`
4. **Prompts**: Test `assess_attachment_style` with behavior descriptions
5. **Debug**: View JSON protocol messages, validate schemas
### HTTP Endpoint Testing
**Note**: This section is for validating HTTP deployment. For development, use Inspector (`fastmcp dev`) instead.
```bash
# ✅ CORRECT: Test with MCP client library
python -c "
from fastmcp import Client
import asyncio
async def test():
print('Testing MCP HTTP endpoint...')
client = Client('http://localhost:8765/mcp/')
async with client:
# Test server capabilities
print('✅ Server connected')
# Test resource access
personas = await client.get_resource('neo4j://personas/all')
print(f'✅ Resources: {len(personas) if personas else 0} personas loaded')
# Test tool execution
result = await client.call_tool('analyze_persona_compatibility', {
'persona_a_id': 'lila',
'persona_b_id': 'alex'
})
print(f'✅ Tools: compatibility analysis {"succeeded" if result else "failed"}')
asyncio.run(test())
"
# ❌ INCORRECT: Simple HTTP tools don't work with MCP
# curl http://localhost:8765/mcp/ # Returns 406 Not Acceptable
# Browser access also won't work - MCP requires JSON-RPC protocol
```
## Architecture
### Minimal Components
- **`minimal_models.py`** - Simple data models (Persona, Relationship, Interaction)
- **`minimal_neo4j.py`** - Neo4j interface with fallback database
- **`minimal_mcp_server.py`** - FastMCP server with resources, tools, and prompts
- **`main.py`** - Server entry point with configuration
### Size Comparison
- **Full Lila System**: 1.3MB+ with complex dependencies
- **Minimal MCP Server**: ~100KB with only essential components
### Dependencies
```
fastmcp>=2.12.3 # MCP server framework with HTTP transport
neo4j>=5.15.0 # Database driver
pydantic>=2.6.0 # Data validation
python-dotenv # Environment configuration
```
### Transport Protocol
This server uses **HTTP transport** (FastMCP 2.0 standard):
- Runs as a web service accessible via URL
- Supports concurrent client connections
- Full bidirectional communication over HTTP
- Ideal for Docker deployment and network access
**Not STDIO transport** (which is for client-launched subprocesses)
## Sample Data
The system includes sample personas for demonstration:
- **Lila**: AI Research Assistant (Secure attachment)
- **Alex**: Software Engineer (Secure attachment)
These can be queried through the MCP resources to test functionality.
## Integration
Use this MCP server with MCP-compatible clients via HTTP transport:
```json
{
"mcpServers": {
"lila-psychology": {
"url": "http://localhost:8765/mcp/",
"transport": "http"
}
}
}
```
For FastMCP clients:
```python
from fastmcp import Client
# Connect to HTTP MCP server
client = Client("http://localhost:8765/mcp/")
async with client:
# Query personas
personas = await client.get_resource("neo4j://personas/all")
# Analyze compatibility
result = await client.call_tool("analyze_persona_compatibility", {
"persona_a_id": "lila",
"persona_b_id": "alex"
})
```
## Development
### Development Workflow
**1. Start with MCP Inspector (Recommended - uv-Native)**:
```bash
# BEST: Auto-configuration with fastmcp.json (uv-native)
fastmcp dev # Automatically detects all dependencies
# Custom port if needed:
fastmcp dev --server-port 6350 # Avoids port conflicts
# FALLBACK: Explicit dependencies (if auto-detection fails)
fastmcp dev simple_lila_mcp_server.py --with fastmcp --with neo4j --with pydantic --with python-dotenv
```
**2. Test Production HTTP Deployment**:
```bash
# BEST: Auto-configuration HTTP transport (uv-native)
fastmcp run # Uses fastmcp.json auto-configuration
# Custom port if needed:
fastmcp run --port 9000 # Override port
# Docker deployment (for full production testing)
docker compose up -d
```
**3. Client Integration Testing**:
```bash
# BEST: Auto-configuration for MCP clients (uv-native)
fastmcp install claude-desktop # Uses fastmcp.json auto-configuration
fastmcp install cursor # Uses fastmcp.json auto-configuration
fastmcp install mcp-json # Generic MCP JSON config
# FALLBACK: Explicit dependencies (if auto-detection fails)
fastmcp install claude-desktop simple_lila_mcp_server.py --with neo4j --with pydantic --with python-dotenv
fastmcp install cursor simple_lila_mcp_server.py --with neo4j --with pydantic --with python-dotenv
```
### Development Features
The minimal implementation is designed for:
- **Fast startup** - No complex initialization
- **Low resource usage** - Minimal memory footprint
- **Inspector Integration** - Built-in development and testing tools
- **Simple deployment** - Single container with few dependencies
- **Easy maintenance** - Clear, focused codebase
### FastMCP CLI Commands (V2)
```bash
# Development with Inspector (fastmcp.json - Recommended)
fastmcp dev # Uses fastmcp.json auto-configuration
fastmcp dev --server-port 6300 # Custom Inspector port
# Development with explicit dependencies (fallback)
fastmcp dev simple_lila_mcp_server.py --with fastmcp --with neo4j --with pydantic --with python-dotenv
# Run with different transports (HTTP recommended for production)
fastmcp run --transport http # HTTP transport (production ready)
fastmcp run --transport http --port 8765 # HTTP with custom port
fastmcp run --transport stdio # STDIO for Inspector development only
# Explicit transport configuration
fastmcp run simple_lila_mcp_server.py --transport http --port 8765 --with fastmcp --with neo4j --with pydantic
fastmcp run simple_lila_mcp_server.py --transport stdio --with fastmcp --with neo4j --with pydantic # Dev only
# Install in MCP clients (uses fastmcp.json automatically)
fastmcp install claude-desktop # Auto-configuration
fastmcp install cursor # Auto-configuration
fastmcp install mcp-json # Generic MCP JSON config
# Explicit client installation
fastmcp install claude-desktop simple_lila_mcp_server.py --with neo4j --with pydantic --with python-dotenv
fastmcp install cursor simple_lila_mcp_server.py --with neo4j --with pydantic --with python-dotenv
# Inspect server capabilities
fastmcp inspect # Uses fastmcp.json (Recommended)
fastmcp inspect --format fastmcp # Detailed FastMCP info
fastmcp inspect --format mcp # Standard MCP protocol info
fastmcp inspect simple_lila_mcp_server.py # Explicit entrypoint (fallback)
```
For full Lila system capabilities, use the main system at the repository root.
## Troubleshooting
### Inspector Connection Issues
#### "Error Connecting to MCP Inspector Proxy" - SOLVED
**Problem**: Inspector web UI loads but shows "Error Connecting to MCP Inspector Proxy - Check Console logs"
**Root Cause**: Complex module import failures in the original server cause FastMCP to fall back to "⚠️ MCP client using enhanced mock responses (server disabled)"
**Solution**: Use the simplified server instead:
```bash
# ✅ WORKING: Use simplified server
fastmcp dev simple_simple_lila_mcp_server.py
# ❌ BROKEN: Original server has import issues
# fastmcp dev simple_lila_mcp_server.py # This may fail with import errors
```
**What was happening:**
1. Original `simple_lila_mcp_server.py` imports local modules: `config`, `graph.database`, `system`
2. FastMCP runs in isolated environment that can't access these modules
3. Server fails initialization, falls back to mock responses
4. Inspector proxy starts but has no real MCP server to connect to
5. Web UI shows connection error
**Validation Commands:**
```bash
# Test that simplified server works
python test_mcp_validation.py
# Expected output:
# ✅ Resources found: 6
# ✅ Tools found: 8
# ✅ Prompts found: 3
# ✅ All tests completed successfully!
# Check Inspector is accessible
# http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>
```
### Virtual Environment Issues
#### Understanding VIRTUAL_ENV Mismatch Warnings
**Warning: "VIRTUAL_ENV does not match the project environment path"**
```bash
warning: `VIRTUAL_ENV=/home/donbr/midlife/lila-pydanticai-phase1/.venv` does not match the project environment path `.venv` and will be ignored; use `--active` to target the active environment instead
```
**Root Cause Analysis:**
This warning occurs due to **uv's strict virtual environment path resolution logic**:
1. **uv Project Environment Detection**: When uv operates in a project directory, it expects to find or create a virtual environment at `.venv` (the default project environment path)
2. **VIRTUAL_ENV Environment Variable**: This variable points to an active virtual environment, often set by:
- Manual `source .venv/bin/activate`
- IDE integrations (VS Code, PyCharm)
- Container environments
- Previous virtualenv/conda activations
3. **Path Mismatch Logic**: uv compares `$VIRTUAL_ENV` against the expected project environment path:
```
VIRTUAL_ENV=/app/.venv (from Docker container)
Project expects: /home/donbr/midlife/lila-pydanticai-phase1/docker/mcp-standalone/.venv
Result: MISMATCH → Warning + Ignore VIRTUAL_ENV
```
**When This Warning Appears:**
- **Container Development**: Docker containers set `VIRTUAL_ENV=/app/.venv` but host expects different path
- **IDE Environment Conflicts**: VS Code or other IDEs activate environments with different paths
- **Cross-Platform Development**: Windows/Linux path differences
- **Manual Environment Activation**: Using `source .venv/bin/activate` when uv expects different path
**Why It's Usually Harmless:**
**The warning is informational, not an error**:
- uv **ignores** the conflicting `VIRTUAL_ENV` and uses its project environment logic
- uv **creates or uses** the correct `.venv` directory regardless
- **Functionality is preserved** - packages install to the right location
- **No data loss** occurs
**When It Could Be Problematic:**
1. **Multiple environments exist** with different dependency versions
2. **Shared development** where team members expect consistent paths
3. **CI/CD pipelines** that rely on specific environment variables
4. **Automated scripts** that depend on `VIRTUAL_ENV` accuracy
**Solutions:**
```bash
# Option 1: Do nothing (recommended)
# Commands work correctly despite the warning
# Option 2: Clear environment variable before running
unset VIRTUAL_ENV
fastmcp run
# Option 3: Use UV_PROJECT_ENVIRONMENT to override default path
export UV_PROJECT_ENVIRONMENT=/path/to/desired/venv
fastmcp run
# Option 4: Use --quiet flag to suppress warnings
fastmcp run --quiet
# Option 5: Deactivate parent environment first
deactivate # If in activated environment
cd docker/mcp-standalone
fastmcp run
# Option 6: Use environment-specific commands
# For development (avoids manual activation)
fastmcp dev # Uses uv's environment management automatically
# For production (Docker handles environments)
docker compose up -d
```
#### Environment Validation Commands
**Verify your environment is set up correctly:**
```bash
# 1. Check current environment status
echo "VIRTUAL_ENV: $VIRTUAL_ENV"
echo "Current directory: $(pwd)"
# 2. Test uv environment detection
fastmcp inspect # Should work regardless of VIRTUAL_ENV warning
# 3. Verify FastMCP can create isolated environment
fastmcp dev --server-port 6350 # Creates isolated environment
# 4. Check if dependencies are available
python -c "import fastmcp, neo4j, pydantic; print('Dependencies OK')"
# 5. Validate .env file loading
python -c "
import os
from dotenv import load_dotenv
load_dotenv()
print('Neo4j URI:', os.getenv('NEO4J_URI', 'Not found'))
print('Logfire enabled:', os.getenv('ENABLE_LOGFIRE_TELEMETRY', 'Not found'))
"
```
#### Development Workflow Best Practices
**Recommended Patterns (avoid VIRTUAL_ENV conflicts):**
```bash
# GOOD: Use uv-native commands (automatic environment management)
fastmcp dev # Auto-detects and manages environment
fastmcp run # Uses project environment correctly
fastmcp inspect # Works regardless of active environment
# GOOD: Use .env files instead of manual activation
# All environment variables loaded automatically from .env
# AVOID: Manual virtual environment activation before fastmcp
source .venv/bin/activate # Can cause path conflicts
fastmcp dev # May show VIRTUAL_ENV warning
# BETTER: Let fastmcp handle environment management
fastmcp dev # Creates isolated environment automatically
```
**IDE Integration Tips:**
```bash
# VS Code: Use Python interpreter selection instead of manual activation
# 1. Open Command Palette (Ctrl+Shift+P)
# 2. "Python: Select Interpreter"
# 3. Choose the correct .venv/bin/python
# 4. VS Code will handle environment automatically
# PyCharm: Configure Project Interpreter
# File → Settings → Project → Python Interpreter
# Add interpreter from .venv directory
```
**Container Development:**
```bash
# Host development (recommended for FastMCP)
cd docker/mcp-standalone
fastmcp dev # Uses host environment management
# Container development (for production testing)
docker compose up -d
# Environment handled by Docker automatically
```
### FastMCP CLI Issues
**Error: "No server object found"**
```bash
# Make sure you're in the correct directory
cd docker/mcp-standalone
# Use explicit entrypoint syntax if auto-detection fails
fastmcp dev simple_lila_mcp_server.py:mcp --with fastmcp --with neo4j --with pydantic --with python-dotenv
fastmcp inspect simple_lila_mcp_server.py:mcp
```
**Error: "Could not load module" or Import Failures**
Modern fastmcp.json configuration should work automatically:
```bash
# WORKING: Auto-detection with fastmcp.json
fastmcp dev # Uses fastmcp.json automatically
fastmcp run # Uses fastmcp.json automatically
fastmcp inspect # Uses fastmcp.json automatically
# FALLBACK: Use explicit dependencies if auto-detection fails
fastmcp dev simple_lila_mcp_server.py --with fastmcp --with neo4j --with pydantic --with python-dotenv
```
**Inspector Port Conflicts**
```bash
# Error: "PORT IS IN USE at port 6277"
# Solution: Specify different server port
fastmcp dev main.py --with fastmcp --with neo4j --with pydantic --with python-dotenv --server-port 6280
```
**Missing `--with fastmcp` Dependency**
Always include `--with fastmcp` in dependency list:
```bash
# CORRECT: Include fastmcp dependency
fastmcp dev main.py --with fastmcp --with neo4j --with pydantic --with python-dotenv
# WRONG: Missing fastmcp dependency
fastmcp dev main.py --with neo4j --with pydantic --with python-dotenv # May fail
```
### Transport and Connection Issues
**Inspector Transport Selection**
- Inspector automatically uses STDIO transport (correct)
- Do NOT manually select HTTP transport in Inspector UI
- STDIO transport is required for Inspector proxy communication
**Neo4j Connection Warnings**
- Neo4j warnings are normal when running locally without Docker
- Server automatically falls back to in-memory database with sample data
- For full Neo4j features, use `docker compose up -d neo4j` first
**HTTP vs STDIO Transport Confusion**
- **STDIO**: For Inspector testing and client integration (`fastmcp dev`)
- **HTTP**: For Docker deployment and network access (`docker compose up -d`)
- **SSE**: Deprecated, avoid using
### Dependency Management Issues
**Missing Dependencies**
```bash
# Install FastMCP globally if missing
pip install fastmcp
# Or use uv
uv add fastmcp
# Verify installation
fastmcp --version
```
**Python Version Compatibility**
```bash
# Specify Python version if needed
fastmcp dev main.py --python 3.11 --with fastmcp --with neo4j --with pydantic --with python-dotenv
```
**uv Environment Issues**
```bash
# If uv is not available, install it first
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or use pip
pip install uv
```
### Testing and Validation
**Verify Server Functionality**
```bash
# 1. Test basic server inspection
fastmcp inspect main.py
# 2. Test Inspector integration
fastmcp dev main.py --with fastmcp --with neo4j --with pydantic --with python-dotenv
# 3. Test HTTP deployment
fastmcp run main.py --transport http --port 8765
# 4. Test Docker deployment + MCP client validation
docker compose up -d
python -c "
from fastmcp import Client
import asyncio
async def test():
client = Client('http://localhost:8765/mcp/')
async with client:
personas = await client.get_resource('neo4j://personas/all')
print(f'✅ Docker deployment working: {len(personas) if personas else 0} personas')
asyncio.run(test())
"
```
**Common Testing Workflow**
1. Start with `fastmcp inspect main.py` to verify basic functionality
2. Use `fastmcp dev` for interactive testing with Inspector
3. Test HTTP transport for production deployment scenarios
4. Use Docker for full stack testing with Neo4j database
**Expected Inspector Behavior**
- Console shows: "Starting MCP inspector..."
- Proxy server starts on specified port (default 6277, custom with `--server-port`)
- Inspector URL with token is displayed
- Web interface should connect successfully via STDIO transport
- All resources, tools, and prompts should be visible and testable
## License
Same as main Lila project.