Number531/Super-Legal

Super-Legal MCP Server

A comprehensive legal research MCP (Model Context Protocol) server with modular architecture, providing access to multiple legal databases and APIs.

🏗️ Architecture Overview

This refactored version transforms the original monolithic 5000+ line server into a clean, modular architecture:

Super-Legal/
├── index.js                           # Main entry point
├── package.json                       # Project configuration
├── src/
│   ├── server/
│   │   └── claude-server-v2.js        # Advanced Claude integration server
│   ├── tools/
│   │   ├── toolDefinitions.js         # MCP tool schemas (51+ tools)
│   │   └── toolImplementations.js     # Tool-to-method mappings
│   ├── api-clients/                   # 35+ specialized API clients
│   │   ├── CourtListenerWebSearchClient.js
│   │   ├── SECWebSearchClient.js
│   │   ├── UsptoWebSearchClient.js
│   │   ├── FederalRegisterWebSearchClient.js
│   │   ├── EPAWebSearchClient.js
│   │   ├── FDAWebSearchClient.js
│   │   ├── CPSCWebSearchClient.js
│   │   ├── FTCWebSearchClient.js
│   │   ├── NHTSAWebSearchClient.js
│   │   └── ... (and many more)
│   └── utils/
│       └── parameterValidation.js     # Input validation helpers
└── test/
    └── claude-playground.html         # Advanced legal document interface

🚀 Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn package manager

Installation

1. Clone the repository:

   git clone https://github.com/Number531/Super-Legal.git
   cd Super-Legal
   

2. Install dependencies:

   npm install
   

3. Set up environment variables: Create a .env file in the root directory (copy from .env.example):

   # Required for CourtListener functionality
   COURTLISTENER_API_TOKEN=your_courtlistener_token_here
   
   # Optional API keys (features will be disabled if not provided)
   USPTO_API_KEY=your_uspto_api_key_here
   GOVINFO_API_KEY=your_govinfo_api_key_here
   EXA_API_KEY=your_exa_api_key_here
   FDA_API_KEY=your_fda_api_key_here
   

Running the Server

# Standard MCP server
npm start

# Development mode with debugging
npm run dev

# Claude integration server (port 8090)
npm run claude

# GPT-5 orchestrator (port 8089)
npm run orchestrator

🔧 Configuration

Environment Variables

API Rate Limits

The server automatically handles rate limiting for all APIs:

• SEC EDGAR: 9 requests/second (conservative under 10/sec limit)
• Federal Register: 5 requests/second
• USPTO Patents: 40 requests/minute (conservative under 45/min limit)
• GovInfo: 9 requests/second (conservative under 10/sec limit)
• Exa: 5 requests/second

📚 Available Tools (51+ Legal Research Tools)

CourtListener Tools (13 tools)

• search_cases - Search legal cases with advanced filtering
• get_case_details - Get detailed case information
• lookup_citation - Look up cases by citation
• search_judges - Search for judges with appointment details
• get_judge_details - Get detailed judge information
• get_court_info - Get court information and jurisdiction
• list_courts - List available courts by jurisdiction
• search_opinions - Search court opinions with full text
• search_audio - Search oral argument audio recordings
• get_audio_details - Get audio details with transcripts
• get_opinion_with_citations - Get opinions with citation analysis
• search_dockets - Search federal court dockets

Financial Disclosure Tools (9 tools)

• search_financial_disclosures - Search judicial financial disclosures
• get_financial_disclosure_details - Get detailed disclosure information
• search_judge_investments - Search judicial investments by company/ticker
• get_judge_gifts - Get gifts received by judges
• get_judge_positions - Get positions held by judges (directorships, etc.)
• search_judge_spouse_income - Search spouse income disclosures
• search_judge_reimbursements - Search judge reimbursements
• search_judge_debts - Search judge debt disclosures
• get_disclosure_positions - Get positions from financial disclosures

SEC EDGAR Tools (4 tools)

• search_sec_filings - Search SEC corporate filings (10-K, 10-Q, 8-K, etc.)
• get_sec_company_facts - Get XBRL financial data and company facts
• get_sec_xbrl_frames - Get aggregated XBRL data across companies
• search_sec_company_tickers - Search companies by ticker/name to get CIK

Federal Register Tools (6 tools)

• search_federal_register - Search federal regulations and notices
• search_federal_register_notices - Search Federal Register notices
• search_federal_register_proposed_rules - Search proposed rules
• search_federal_register_final_rules - Search final rules and regulations
• search_federal_register_presidential_documents - Search executive orders
• search_federal_register_public_inspection - Search pre-publication documents

USPTO Patent Tools (6 tools)

• search_patents - Search patents, inventors, and assignees
• search_patent_locations - Search patent geographic data
• search_cpc_classifications - Search CPC patent classifications
• search_cpc_groups - Search CPC classification groups
• search_uspc_classifications - Search USPC classifications
• search_wipo_classifications - Search WIPO technology fields

GovInfo USC Tools (4 tools)

• search_us_code - Search United States Code
• get_usc_section - Get specific USC sections with full text
• get_usc_title_structure - Get USC title structure and organization
• list_usc_titles - List all USC titles (1-54)

State Statute Tools (1 tool)

• search_state_statute - Search state statutory law across all 50 states

EPA Environmental Tools (3 tools)

• search_epa_facilities - Search EPA-regulated facilities
• get_epa_facility_compliance_report - Get facility compliance history
• search_epa_violations - Search environmental violations

FDA Safety Tools (12 tools)

• search_fda_drug_adverse_events - Search drug adverse event reports (FAERS)
• search_fda_device_events - Search medical device adverse events (MAUDE)
• search_fda_drug_labels - Search drug labeling information
• search_fda_recalls - Search FDA recalls (drugs, devices, food)
• search_fda_warning_letters - Search FDA warning letters
• search_fda_drug_safety_communications - Search drug safety communications
• search_fda_device_safety_communications - Search device safety communications
• search_fda_drug_shortages - Search drug shortage information
• search_fda_510k - Search 510(k) medical device clearances
• search_fda_pma_approvals - Search PMA device approvals
• search_fda_orange_book - Search Orange Book (approved drugs)
• search_fda_purple_book - Search Purple Book (biosimilars)

CPSC Consumer Safety Tools (7 tools)

• search_cpsc_recalls - Search consumer product recalls
• search_cpsc_enforcement - Search CPSC enforcement actions
• search_cpsc_business_guidance - Search business guidance documents
• search_cpsc_safety_standards - Search safety standards and regulations
• search_cpsc_injury_data - Search injury and incident data
• search_cpsc_news - Search CPSC news and announcements
• search_cpsc_reports_studies - Search reports and studies

FTC Enforcement Tools (6 tools)

• search_ftc_enforcement_cases - Search FTC enforcement cases
• search_ftc_competition_matters - Search competition and antitrust matters
• search_ftc_guidance_policy - Search guidance and policy documents
• search_ftc_rulemaking - Search FTC rulemaking proceedings
• search_ftc_consumer_alerts - Search consumer alerts and warnings
• search_ftc_news - Search FTC news and press releases

NHTSA Vehicle Safety Tools (6 tools)

• nhtsa_decode_vin - Decode vehicle VIN numbers
• nhtsa_models_for_make - Get vehicle models for manufacturer
• nhtsa_recalls_by_vin - Get recalls by VIN number
• nhtsa_recalls_by_make_model_year - Get recalls by make/model/year
• nhtsa_search_complaints - Search vehicle safety complaints
• nhtsa_safety_ratings - Get vehicle safety ratings

PTAB Patent Trial Tools (4 tools)

• search_ptab_proceedings - Search PTAB proceedings (IPR, PGR, CBM)
• search_ptab_ipr_proceedings - Search Inter Partes Review proceedings
• search_ptab_pgr_proceedings - Search Post-Grant Review proceedings
• search_ptab_cbm_proceedings - Search Covered Business Method proceedings

Comprehensive Analysis Tools (3 tools)

• comprehensive_legal_entity_analysis - Cross-API entity analysis
• draft_legal_filing - Draft legal documents and filings
• search_court_rules - Search court rules and procedures

🌐 Claude Playground Interface

The repository includes a sophisticated web-based testing interface at test/claude-playground.html featuring:

✨ Advanced Features

• Legal Document Formatting: Specialized markdown rendering for legal citations, precedents, and footnotes
• Streaming Interface: Real-time visualization of Claude's thinking process and tool execution
• Session Management: Conversation memory and context preservation
• Export Functionality: Generate properly formatted legal memoranda
• Interleaved Thinking: Advanced reasoning visualization
• Fine-grained Tool Streaming: Real-time tool execution feedback
• Parallel Tool Execution: Efficient multi-tool processing

🎨 Legal Document Styling

• Case Citations: Proper italicization and court formatting
• Statute Citations: Monospace formatting for USC, CFR references
• Legal Emphasis: Highlighting of key legal terms and holdings
• Footnote System: Automatic footnote generation and linking
• Print Optimization: Professional legal document printing styles

🚀 Usage

1. Start the Claude server: npm run claude
2. Open test/claude-playground.html in your browser
3. Configure server URL (default: http://localhost:8090)
4. Begin legal research with natural language queries

Example queries:

• "Research manufacturing companies in western Pennsylvania which have previously filed for bankruptcy"
• "Find EPA violations for chemical facilities in Pittsburgh"
• "Search for patent disputes involving AI technology"
• "Analyze SEC filings for tech companies with recent acquisitions"

⚠️ EPA Search Requirements

Important: Specific Location Criteria Required

The EPA ECHO API requires specific search criteria to prevent overwhelming result sets:

✅ Valid Search Patterns

• City-based: state + city + company_name
• ZIP-based: state + zip_code + company_name
• Facility-specific: facility_name (with or without state)

❌ Invalid Search Patterns (Will Be Rejected)

• State-only: Too broad, will be rejected
• Generic company names: Terms like "chemical", "manufacturing" are too vague
• Missing location data: Must include city, ZIP, or specific facility name

🔄 Migration from Original

The refactored version maintains 100% API compatibility while providing:

✅ Benefits

• Modular Architecture: Easy to maintain and extend
• Advanced Claude Integration: Session memory, streaming, thinking visualization
• Enhanced Web Interface: Professional legal document formatting
• Better Error Handling: Isolated error handling per module
• Improved Performance: Lazy loading, intelligent caching, optimized rate limiting
• Comprehensive Testing: Individual module testing capabilities

🔧 Key Improvements

• File Structure: Organized into logical, maintainable modules
• Rate Limiting: Centralized, intelligent API rate management
• Parameter Validation: Comprehensive input validation and sanitization
• Documentation: Extensive inline documentation and architectural guides
• Legal Formatting: Specialized legal document rendering and export

🛠️ Development

Project Structure

Each module has a specific responsibility:

• src/server/: Core MCP server and Claude integration
• src/tools/: MCP tool definitions and mappings
• src/api-clients/: Individual API client implementations
• src/utils/: Shared utilities and validation helpers
• test/: Testing interfaces and playground

Adding New APIs

1. Create a new client in src/api-clients/
2. Add tool definitions in src/tools/toolDefinitions.js
3. Map tools in src/tools/toolImplementations.js
4. Update server initialization as needed

Testing

# Run MCP server in development mode
npm run dev

# Run Claude integration server
npm run claude

# Test with the web playground
# Open test/claude-playground.html in browser

🌐 GPT‑5 Orchestrator Integration

Advanced backend orchestrator for OpenAI GPT‑5 integration:

Prerequisites

• OPENAI_API_KEY (required)
• Optional downstream API keys for full functionality

Usage

npm run orchestrator

# Health check
curl http://localhost:8089/health

# Research query
curl -X POST http://localhost:8089/api/gpt5/research \
  -H 'content-type: application/json' \
  -d '{"query":"Find Chapter 11 bankruptcies for chemical manufacturers in Pennsylvania"}'

📝 License

MIT License - Open source legal research platform.

🤝 Contributing

Contributions welcome! The modular architecture makes it easy to:

• Add new legal APIs and databases
• Enhance the Claude playground interface
• Improve legal document formatting
• Extend tool capabilities

📞 Support

For issues:

• Architecture: Check module-specific implementations
• API Integration: Review individual client files
• Tool Configuration: Check src/tools/ directory
• Web Interface: Review test/claude-playground.html

The refactored architecture provides clear separation of concerns for easier debugging and maintenance.