mcp-limitless: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that provides scientifically validated analysis of conversational speech patterns from Limitless Pendant recordings. It implements empirically validated metrics derived from real-world transcription data analysis (2,500+ conversation segments).

Key capabilities:

• Speech Vitality Index with validated metrics (engagement, fluency, interaction)
• Meeting detection and action item extraction
• Natural language time queries
• Speaker analytics and daily summaries
• Transparent data quality assessment

Common Development Commands

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Development mode with auto-reload
npm run dev

# Start the built server
npm start

# Publish to npm (includes build)
npm publish

Architecture Overview

Core Components

1. MCP Server Setup (src/server.ts):

   • Entry point using MCP SDK
   • Tool registration and request handling
   • Environment variable validation for LIMITLESS_API_KEY

2. Limitless API Client (src/limitless-client.ts):

   • HTTP client for Limitless API
   • Pagination handling
   • Error management with specific error classes

3. Speech Vitality Index (src/speech-vitality-index.ts):

   • Scientifically validated metrics calculation
   • Data quality assessment
   • Conversation context detection

4. Advanced Features (src/advanced-features.ts):

   • Natural time expression parsing
   • Meeting detection algorithms
   • Action item extraction

5. Search & Analytics (src/search-and-analytics.ts):

   • Advanced search with filters
   • Daily summary generation
   • Speaker analytics

6. Transcript Extraction (src/transcript-extraction.ts):

   • Raw transcript processing
   • Speaker identification
   • Timeline reconstruction

Key Design Patterns