SueChef - Legal Research MCP

Your AI sous chef for cooking up winning legal strategies

Features • Quick Start • Installation • Usage • Architecture • License

SueChef is a powerful legal research MCP (Model Context Protocol) that combines PostgreSQL, Qdrant vector database, and Graphiti knowledge graphs to help you prepare the perfect legal case - with all the right ingredients!

• add_event: Add chronology events with automatic vector and knowledge graph storage
• get_event: Get a single event by ID
• list_events: List events with filtering by date, parties, or tags
• update_event: Update existing event (partial updates supported)
• delete_event: Delete an event from all systems
• create_snippet: Create legal research snippets (case law, precedents, statutes)
• get_snippet: Get a single snippet by ID
• list_snippets: List snippets with filtering by case type or tags
• update_snippet: Update existing snippet (partial updates supported)
• delete_snippet: Delete a snippet from all systems

Search & Discovery

• unified_legal_search: Hybrid search across PostgreSQL + Qdrant + Graphiti
• postgres_full_text_search: Advanced PostgreSQL full-text search with relevance ranking
• postgres_advanced_query: Execute complex PostgreSQL queries with JSONB operations

• ingest_legal_document: Feed entire legal documents for automatic entity extraction and knowledge graph building

• temporal_legal_query: Ask temporal questions about legal knowledge evolution

• create_manual_link: Create explicit relationships between events and legal precedents

• get_legal_analytics: Comprehensive legal research analytics
• get_system_status: Health check for all system components

• search_courtlistener_opinions: Search millions of court opinions by query, court, date, and citation count
• import_courtlistener_opinion: Import opinions as snippets with automatic event linking
• search_courtlistener_dockets: Find active cases, parties, and procedural history
• find_citing_opinions: Discover all cases that cite a specific precedent
• analyze_courtlistener_precedents: Analyze how legal precedents evolved over decades

• build_legal_communities: Build communities to identify legal concept clusters
• search_legal_communities: Search for communities related to legal queries
• enhanced_legal_search: Configurable search with SearchConfig for nodes/edges/communities

The fastest way to get SueChef running is with Docker Compose:

git clone https://github.com/medelman17/suechef.git
cd suechef
cp .env.example .env
# Edit .env with your OpenAI API key

# Start everything including SueChef MCP server with Streaming HTTP
docker compose up -d

# Note: Main architecture now uses modular design by default

# Run setup script to create schemas
uv run python setup.py

• SueChef MCP Server: http://localhost:8000/mcp (Streaming HTTP endpoint)
• SueChef MCP Server: Primary service with modular architecture
• PostgreSQL: localhost:5432 (user: postgres, password: suechef_password)
• Qdrant: http://localhost:6333 (dashboard at /dashboard)
• Neo4j: http://localhost:7474 (user: neo4j, password: suechef_neo4j_password)

docker compose down
# Add -v to remove volumes and reset data
docker compose down -v

• Python 3.12+
• Docker & Docker Compose (for quick setup)
• OpenAI API key (for embeddings)
• CourtListener API key (optional, for enhanced access)

NEW: SueChef now integrates seamlessly with Claude Desktop for enhanced AI-powered legal research!

1. Start SueChef: docker compose up -d
2. Configure Claude Desktop with the provided config
3. Access 26+ legal research tools directly in Claude Desktop

→ See docs/CLAUDE_DESKTOP_SETUP.md for complete integration guide
→ See docs/example-workflows.md for real-world usage examples

If you encounter trigger duplication errors after upgrading:

Error: trigger "update_events_updated_at" for relation "events" already exists

Quick Fix:

# Update to latest version and restart
git pull origin main
docker compose restart suechef

→ See docs/DATABASE_MIGRATION_FIX.md for detailed resolution steps

If you encounter array parameter or connection errors:

Error: Input should be a valid list [type=list_type] or Connection error.

Quick Fix:

# Update to latest version with enhanced parameter parsing
git pull origin main
docker compose restart suechef

→ See docs/CHRONOLOGY_FIXES.md for detailed resolution steps

Follow the Quick Start above.

1. Clone the repository:

git clone https://github.com/medelman17/suechef.git
cd suechef

2. Install dependencies using uv:

uv sync

3. Set up local databases:

   • Install PostgreSQL, Qdrant, and Neo4j locally
   • Or use Docker for databases only: docker compose up -d postgres qdrant neo4j

4. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

5. Run the setup script:

uv run python setup.py

SueChef runs as an HTTP server that implements the MCP (Model Context Protocol) over streaming HTTP. You can connect to it from any MCP-compatible client:

Endpoint: http://localhost:8000/mcp

The easiest way to use SueChef is through Claude Desktop. See CLAUDE_DESKTOP_SETUP.md for setup instructions.

from mcp import Client

async with Client("http://localhost:8000/mcp") as client:
    # List available tools
    tools = await client.list_tools()
    print(f"Available tools: {len(tools.tools)}")
    
    # Call a tool
    result = await client.call_tool("get_system_status", {})
    print(result)

# Test server health
curl http://localhost:8000/mcp

# Send MCP request (example)
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list", "params": {}}'

# SueChef MCP server (now uses modular architecture)
uv run python main.py

# 1. Ingest legal documents
ingest_legal_document(
    document_text="Full text of court filing...",
    title="Smith v. Landlord Corp (1995)",
    date="1995-03-15",
    document_type="court_filing"
)

# 2. Build detailed timeline
add_event(
    date="2023-05-14",
    description="Tenant reports flooding to property management",
    parties=["John Smith", "Property Management LLC"],
    document_source="Email correspondence",
    tags=["water damage", "notice", "maintenance"],
    significance="First documented notice of water damage"
)

# 3. Add legal precedents
create_snippet(
    citation="Johnson v. Property Mgmt Co., 123 F.3d 456 (2010)",
    key_language="Landlord has duty to repair once on notice of defects",
    tags=["landlord liability", "notice", "duty to repair"],
    case_type="premises liability"
)

# 4. Search for related content
unified_legal_search(
    query="landlord knowledge of defects water damage",
    search_type="all"
)

# 5. Analyze temporal patterns
temporal_legal_query(
    question="How has landlord liability for water damage evolved?",
    time_focus="1995-2023",
    entity_focus="premises liability"
)

# 6. Get analytics
get_legal_analytics()

# 1. Search for relevant precedents
opinions = search_courtlistener_opinions(
    query="landlord liability water damage notice",
    court="ca9",  # Ninth Circuit
    cited_gt=10,  # Well-cited cases
    date_after="2000-01-01"
)

# 2. Import a key precedent
import_courtlistener_opinion(
    opinion_id=12345,
    add_as_snippet=True,
    auto_link_events=True
)

# 3. Find cases that cite your precedent
citing_cases = find_citing_opinions(
    citation="Johnson v. Property Mgmt Co., 123 F.3d 456"
)

# 4. Analyze precedent evolution
analysis = analyze_courtlistener_precedents(
    topic="landlord liability water damage",
    jurisdiction="ca9",
    date_range_years=30
)

# 5. Search active litigation
dockets = search_courtlistener_dockets(
    case_name="tenant water damage",
    date_filed_after="2020-01-01"
)

SueChef's kitchen uses three complementary technologies to serve up legal insights:

1. PostgreSQL (The Pantry): Structured data storage with JSONB support for flexible schemas and full-text search capabilities
2. Qdrant (The Spice Rack): Vector database for semantic search using OpenAI embeddings - finding the perfect flavor matches
3. Graphiti + Neo4j (The Recipe Book): Knowledge graph for entity extraction and relationship mapping - understanding how ingredients work together

SueChef now features a modern, layered architecture for enhanced maintainability:

src/
├── config/         # 📁 Centralized configuration management
├── core/           # 🗄️ Database managers and clients  
├── services/       # 🔧 Business logic layer
├── tools/          # 🛠️ MCP interface layer
├── utils/          # 🧰 Shared utilities
└── models/         # 📊 Data models and schemas

Benefits:

• ✅ 70% reduction in main server complexity
• ✅ Type-safe configuration with validation
• ✅ Modular services for easy testing and maintenance
• ✅ Zero breaking changes - full backward compatibility
• ✅ Plugin-ready architecture for rapid feature development

Migration Status:

• 🟢 Events: Fully migrated to new EventService
• 🟡 Other tools: Still using legacy architecture (migration ongoing)

See MODULARIZATION_PROPOSAL.md and MODULARIZATION_COMPLETED.md for detailed information.

uv add <package-name>

uv run pytest

# Rebuild after code changes
docker compose build suechef

# View logs
docker compose logs -f suechef

# Access running container
docker compose exec suechef bash

MIT License