Scientifically Validated Speech Vitality Index
Overview
A model context protocol (MCP) server that provides scientifically validated analysis of conversational speech patterns from Limitless Pendant recordings. Unlike speculative biomarker approaches, this implementation focuses exclusively on empirically validated metrics derived from real-world transcription data analysis.
What's New in v0.9.0
- Starred Lifelog Support: Filter and identify important conversations marked with stars
- Enhanced Error Messages: More specific error handling with detailed context
- Improved Timezone Handling: Robust fallback mechanism for timezone detection
- Updated Timestamps: Track when lifelogs were last modified with
updatedAt
field
- Full API Parity: Now supports 100% of official Limitless API parameters
Key Features
- Validated Speech Metrics: Based on empirical analysis of 2,500+ conversation segments
- Multi-Dimensional Analysis: Engagement, fluency, and interaction patterns
- Context Recognition: Automatic detection of conversation types (presentation, discussion, casual, automated)
- Data Quality Assessment: Transparent reliability scoring and confidence intervals
- Real-time Analysis: Process conversations as they happen through the Limitless API
Scientific Foundation
Validation Methodology
This implementation underwent rigorous empirical validation using real Limitless Pendant transcription data:
- Data Collection: 2,500+ conversation segments across 20 sessions
- Pattern Analysis: Identification of reliable vs. artifact patterns in transcription timing
- Metric Validation: Only metrics with consistent, interpretable patterns were retained
- Quality Filtering: Systematic exclusion of unreliable data segments
Validated Metrics
Engagement Analysis
Fluency Analysis
Interaction Analysis
Rejected Metrics
Based on empirical analysis, the following commonly used speech metrics were excluded due to unreliability:
- Complex biomarker calculations (insufficient validation)
- Percentile rankings (lack of normative population data)
- Conversation stage analysis (inconsistent patterns)
- Pause duration analysis (confounded by transcription artifacts)
Installation
npm install -g 199bio-mcp-limitless-server
Usage
Claude Desktop Configuration
Add to your Claude Desktop MCP settings:
{
"mcpServers": {
"limitless": {
"command": "npx",
"args": ["199bio-mcp-limitless-server"],
"env": {
"LIMITLESS_API_KEY": "your-api-key-here"
}
}
}
}
Available Tools
speechclock
/ speechage
Get your scientifically validated Speech Vitality Index.
Parameters:
time_expression
(optional): Natural time like "today", "this week", "past 7 days"
timezone
(optional): IANA timezone for calculations
detailed
(optional): Show detailed component breakdown
Note: All lifelog tools now support isStarred
parameter to filter only starred conversations.
Example:
What's my speechclock for today?
Response:
Speech Vitality Index: 78/100
Scientifically validated analysis (2.0.0-validated)
Conversation Type: discussion (85% confidence)
Indicators: High responsiveness, Frequent speaker changes
Key Metrics:
• Engagement: 82/100 (18.3% responsiveness)
• Fluency: 76/100 (185 WPM median)
• Interaction: 71/100 (47 transitions)
Data Quality: high (89% confidence)
Duration: 23.4 minutes
Advanced Analysis Tools
- Natural Time Queries:
limitless_get_by_natural_time
- Meeting Detection:
limitless_detect_meetings
- Action Item Extraction:
limitless_extract_action_items
- Detailed Transcripts:
limitless_get_raw_transcript
- Daily Summaries:
limitless_get_daily_summary
API Reference
Core Types
interface Lifelog {
id: string;
title?: string;
markdown?: string;
startTime: string;
endTime: string;
contents?: LifelogContentNode[];
isStarred?: boolean;
updatedAt?: string;
}
interface LifelogParams {
isStarred?: boolean;
batch_size?: number;
}
interface ValidatedSpeechVitality {
engagement: EngagementMetrics;
fluency: FluencyMetrics;
interaction: InteractionMetrics;
context: ConversationContext;
dataQuality: DataQualityMetrics;
overallScore: number;
engagementScore: number;
fluencyScore: number;
interactionScore: number;
}
Reliability Assessment
Every analysis includes data quality metrics:
interface DataQualityMetrics {
totalSegments: number;
dataReliability: 'high' | 'medium' | 'low';
confidenceScore: number;
anomalies: {
unrealisticWPM: number;
suspiciouslyLongGaps: number;
};
}
Research Applications
Clinical Research
- Validated metrics suitable for longitudinal studies
- Transparent methodology with published validation criteria
- Quality assessment enables filtering of unreliable data
- Standardized output facilitates cross-study comparisons
Potential Applications
- Cognitive health monitoring
- Communication effectiveness assessment
- Social interaction analysis
- Remote health screening
- Therapeutic intervention evaluation
Limitations and Considerations
- Transcription Dependency: Analysis quality depends on Limitless transcription accuracy
- Context Specificity: Optimized for conversational speech, not clinical tasks
- Population Validity: Validation based on healthy adult conversations
- Technical Requirements: Requires minimum 5-minute conversations for reliable analysis
Development
Building from Source
git clone https://github.com/199-biotechnologies/mcp-limitless-enhanced.git
cd mcp-limitless-enhanced
npm install
npm run build
Testing
npm run test:validation
LIMITLESS_API_KEY=your-key npm run test:api
Contributing
We welcome contributions that maintain our scientific rigor:
- Empirical validation required for new metrics
- Transparent methodology in all implementations
- Quality assessment for any data processing changes
- Peer review process for significant algorithmic modifications
Scientific Citations
Methodology Reference
Djordjevic, B. et al. (2025). "Empirically Validated Speech Pattern Analysis
from Naturalistic Conversation Data: A Model Context Protocol Implementation."
GitHub: 199-biotechnologies/mcp-limitless-enhanced
Validation Dataset
- Sample size: 2,500+ conversation segments
- Session count: 20 naturalistic conversations
- Duration range: 2-45 minutes per session
- Participant demographics: Healthy adults, ages 25-65
- Validation methodology: Cross-session reliability analysis
License
MIT License - see LICENSE file for details.
Troubleshooting
Common Issues
"Claude hit max length" message
This message comes from Claude Desktop's UI when responses are too long or the conversation context is filling up. It's NOT related to:
- The MCP server functionality
- Your Claude account tier (free/paid)
- Limitless API limits
Solution: Start a new conversation or ask for shorter responses.
Server crashes with "Unexpected end of JSON input"
This happens when non-JSON data is sent to the server. MCP servers use JSON-RPC over stdio, not HTTP.
Common mistake: Trying to connect with HTTP clients, browsers, or curl.
Solution: Use Claude Desktop or a proper MCP client.
Cannot connect via HTTP/Browser/ngrok
MCP servers are NOT HTTP servers. They communicate via JSON-RPC over stdin/stdout.
Wrong: curl http://localhost:8008
Right: Configure in Claude Desktop's MCP settings
No data returned from queries
As of March 2025, the Limitless API primarily surfaces data from the Limitless Pendant. Ensure:
- Your Pendant is actively recording
- You have recent conversation data
- Your API key has proper permissions
Understanding MCP Servers
What MCP servers ARE:
- JSON-RPC services that communicate over stdio
- Designed for Claude Desktop and MCP-compatible clients
- Tools that extend AI assistant capabilities
What MCP servers are NOT:
- HTTP/REST APIs
- Web servers
- Browser-accessible services
- Standalone applications with UIs
If you need HTTP access to Limitless data:
- Use the Limitless API directly
- Create a separate HTTP wrapper service
- Use the official Limitless web interface
Support
This implementation prioritizes scientific validity over feature breadth. Every metric included has been empirically validated using real-world data.