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 fully self-contained with auto-configuration:

Important Configuration Note: The fastmcp.json file uses "project": "." configuration to avoid MCP Inspector bugs with version specifiers. See Troubleshooting section for details.

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

Server Selection: Mock vs Neo4j Data

The project includes two server implementations:

simple_lila_mcp_server.py (Default in fastmcp.json)

• In-memory mock data (Lila and Don personas)

• No Neo4j required

• Fast startup, ideal for development

• Graceful fallback if Neo4j unavailable

lila_mcp_server.py (Production)

• Full Neo4j database integration

• Real graph data queries

• Requires Neo4j running

To switch servers, edit fastmcp.json line 6:

Configuration

Environment Configuration (.env file): All settings are configured in .env - no manual environment variables needed:

• NEO4J_URI=bolt://localhost:7687

• NEO4J_USER=neo4j

• NEO4J_PASSWORD=passw0rd

• ENABLE_LOGFIRE_TELEMETRY=true

• LOGFIRE_PROJECT_NAME=lila-autonomous-agents

Critical Requirements:

• Neo4j Running (if using lila_mcp_server.py): docker compose up -d neo4j

• Configuration: Uses fastmcp.json with "project": "." (avoids Inspector bugs)

• 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

MCP Inspector Connection Issues

ERR_CONNECTION_REFUSED or [object Object] Error - CRITICAL

Problem: Inspector UI loads but clicking "Connect" shows:

• ERR_CONNECTION_REFUSED on port 6277, OR

• error: Failed to spawn: '[object Object]' in console

Root Cause: MCP Inspector's JavaScript argument parser incorrectly handles >= operators in dependency version strings. When fastmcp.json contains:

The Inspector splits neo4j>=5.15.0 into: neo4j, [object Object], =5.15.0, causing uv to fail.

Solution (Already Configured): Use "project": "." in fastmcp.json:

DO NOT USE explicit dependencies with >= operators in fastmcp.json - they will break the Inspector.

Port Already in Use - PORT IS IN USE at port 6277

Problem: fastmcp dev fails with "PORT IS IN USE at port 6277"

Root Cause: fastmcp dev spawns multiple background processes (Python, node, npm, mcp-inspector) that must ALL be killed.

Solution:

Check Running Processes:

Inspector Proxy Shows "Error Connecting"

Problem: Inspector web UI loads but shows connection error

Solution: Ensure you're using the default server configuration in fastmcp.json:

• Default: simple_lila_mcp_server.py (mock data, works without Neo4j)

• Production: lila_mcp_server.py (requires Neo4j running)

Validation:

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.