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:

Step 2: Test with MCP Inspector

The server provides:

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

Step 3: Production HTTP Deployment

Once testing confirms everything works, deploy with HTTP transport for production:

Important: HTTP endpoint serves MCP JSON-RPC protocol, not REST API. See MCP Client Testing section for proper testing methods.

Alternative: Docker Deployment

Fallback: Explicit Dependencies

If fastmcp.json auto-detection fails:

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):

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:

Understanding MCP Transports

Why does the Quick Start prioritize

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

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

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

MCP Client Integration

JSON Configuration Generation (FastMCP V2)

Generate MCP client configuration files for different applications:

Manual Client Configuration

HTTP Transport Configuration (Recommended)

For HTTP-based MCP clients (production ready):

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:

Claude Desktop Configuration (STDIO - Development Only)

For local development with STDIO transport:

Cursor Configuration (STDIO - Development Only)

For local development with STDIO transport:

Inspector Testing Workflow

1. Start Inspector (Recommended - Auto-Configuration):

   # 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:

     { "persona_a_id": "lila", "persona_b_id": "alex" }

   • Test query_relationship_metrics with same parameters

   • Test get_attachment_style_insights:

     { "persona_id": "lila" }

5. Test Prompts:

   • Click Prompts tab

   • Test assess_attachment_style:

     { "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:

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)

Configuration

Environment variables:

Testing

Unit Tests

Interactive Testing with MCP Inspector

The MCP Inspector provides the best testing experience:

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.

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

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:

For FastMCP clients:

Development

Development Workflow

1. Start with MCP Inspector (Recommended - uv-Native):

2. Test Production HTTP Deployment:

3. Client Integration Testing:

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)

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:

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:

Virtual Environment Issues

Understanding VIRTUAL_ENV Mismatch Warnings

Warning: "VIRTUAL_ENV does not match the project environment path"

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:

Environment Validation Commands

Verify your environment is set up correctly:

Development Workflow Best Practices

Recommended Patterns (avoid VIRTUAL_ENV conflicts):

IDE Integration Tips:

Container Development:

FastMCP CLI Issues

Error: "No server object found"

Error: "Could not load module" or Import Failures Modern fastmcp.json configuration should work automatically:

Inspector Port Conflicts

Missing Always include --with fastmcp in dependency list:

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

Python Version Compatibility

uv Environment Issues

Testing and Validation

Verify Server Functionality

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.