Coach MCP Server 🎯

A local-first AI-powered life coach Model Context Protocol (MCP) server that helps you track goals, manage todos, take notes, and provides daily guidance through structured prompts and intelligent tools. Your data stays on your machine - no cloud required.

✨ Features

🛠️ Core Tools

• Goal Management: Create, update, complete, and track long-term objectives
• Todo Management: Manage daily tasks with due dates and tags
• Note Taking: Capture thoughts, insights, and observations with flexible tagging
• Daily Briefings: Get personalized morning briefings with prioritized tasks
• Day Recaps: Generate comprehensive end-of-day summaries
• Conversation Memory: Remember and reference past conversations
• Smart Search: Find content using keywords or semantic search (with OpenAI integration)

📋 Smart Organization

• Priority Intelligence: Automatically prioritizes overdue and due-today items
• Context Awareness: Provides relevant historical context for better decision-making
• Tag-based Filtering: Organize and filter items using flexible tagging system
• Date-based Tracking: Track progress over time with date-aware queries

🔧 MCP Integration

• Tools: Easy, comprehensive tools for life management
• Resources: Daily tips and motivational content
• Prompts: Structured prompts for reflection and planning

🏠 Local-First Design

• Complete Data Ownership: Your data stays on your machine, always
• Privacy by Design: No cloud dependencies, tracking, or data uploads
• SQLite Database: Standard format for easy backup, export, and migration
• Offline Operation: Works without internet connection or external services

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/Linell/coach.git
cd coach

# Install dependencies
npm install

# Build the project
npm run build

# Run tests to verify installation
npm test

📖 Usage

With Claude Desktop

Add the following to your Claude Desktop MCP configuration file:

{
  "mcpServers": {
    "coach": {
      "command": "/path/to/coach/coach-mcp.sh"
    }
  }
}

Development tip: For active development, you can point directly to the TypeScript source:

"command": "npx",
"args": ["ts-node-esm", "/path/to/coach/src/index.ts"]

Development

# Run in development mode (with hot reload)
npm run dev

# Run linter
npm run lint

# Run tests with coverage
npm run test:coverage

🏠 Local-First Configuration & Data

Your data belongs to YOU. Coach MCP Server is built with a local-first philosophy - everything stays on your machine, giving you complete control, privacy, and ownership of your personal data.

🔧 Configuration

The server automatically creates a user-specific configuration file at ~/.config/coach/config.json

Example configuration:

{
  "database_path": "~/.local/share/coach/coach.sqlite"
}

The server also automatically loads your OpenAI API key from the OPENAI_API_KEY environment variable for enhanced search capabilities.

Customize your setup:

# Use a custom config directory
COACH_CONFIG_DIR=/custom/path npm start

# Point to a specific database location
# Edit ~/.config/coach/config.json:
{
  "database_path": "/path/to/your/coach-data.sqlite"
}

# Enable semantic search (optional)
export OPENAI_API_KEY="your-openai-api-key"

🗄️ SQLite Database - Your Personal Data Store

Your data is all stored in a single SQLite file that you completely control.

🎯 Why Local-First Matters

🔒 Privacy by Design

• No cloud dependencies or data uploads
• No third-party analytics or tracking
• Your personal insights stay personal

📊 Complete Data Control

• Standard SQLite format - use any SQLite browser/tool
• Easy backups: just copy the .sqlite file
• Export your data anytime, anywhere
• Migrate between systems effortlessly

⚡ Performance & Reliability

• Lightning-fast queries (no network latency)
• Works offline, always available
• No rate limits or service interruptions

View your data directly:

# Quick access via npm script (uses your configured database path)
npm run dbconsole

# Or access directly
sqlite3 ~/.local/share/coach/coach.sqlite

.schema                    # View table structure
SELECT * FROM goals;       # See all goals
SELECT * FROM notes WHERE tags LIKE '%work%';  # Filter by tags

🔍 Search

Coach includes intelligent search that works in multiple modes:

Basic Search (Always Available)

• Keyword matching across all your content
• Tag-based filtering for precise results
• No setup required - works immediately

Enhanced Search (Optional)

For more powerful semantic search that understands meaning and context:

# Set OpenAI API Key for enhanced search
export OPENAI_API_KEY="your-openai-api-key"

# Optional: Build initial search index
npm run reindex-search

Usage

Search across all your content (notes, todos, goals, workouts) using natural language:

# Use via MCP tools
search-content query="productivity tips for remote work"
search-content query="cardio workouts" content_types=["workout", "exercise"]

The system automatically updates search indices when content changes and gracefully falls back to keyword search when OpenAI integration is unavailable.

🛠️ Available Tools

Goal Management

• add-goal - Create a new goal with optional due date and metadata
• list-goals - View all goals with completion status and due dates
• update-goal - Modify goal text, due date, or mark as completed
• delete-goal - Remove a goal permanently

Todo Management

• add-todo - Create a new todo with optional due date and tags
• list-todos - View all todos with filtering options
• update-todo - Modify todo details or mark as completed
• delete-todo - Remove a todo permanently

Note Taking

• add-note - Capture thoughts and insights with optional tags
• list-notes - Browse notes with tag-based filtering
• update-note - Edit existing notes
• delete-note - Remove notes permanently

Daily Workflows

• start-day - Get a personalized morning briefing with priorities
• recap-day - Generate a comprehensive end-of-day summary
• remember-convo - Save important conversation points for future reference

Search & Discovery

• search-content - Semantic search across all content using OpenAI embeddings
• update-search-index - Rebuild search index with latest embeddings

Analytics

• user-summary - Get insights into your productivity patterns and progress

🏗️ Architecture

Database Schema

The server uses SQLite with the following tables:

• goals - Long-term objectives with completion tracking
• todos - Short-term tasks with due dates and tags
• notes - Free-form notes with tagging support
• workouts - Fitness activity tracking with flexible exercise support
• exercises - Detailed exercise tracking linked to workouts
• search_embeddings - Vector embeddings for semantic search
• search_vectors - Optimized vector storage (sqlite-vec)
• search_fts - Full-text search index (FTS5)

Project Structure

src/
├── tools/          # MCP tools (19 tools for life management + search)
├── resources/      # MCP resources (daily tips, etc.)
├── prompts/        # MCP prompts (reflection prompts)
├── db.ts          # Database connection and schema
├── search.ts      # Semantic search and embedding utilities
├── config.ts      # Configuration management
├── types.ts       # TypeScript type definitions
└── index.ts       # Server entry point

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

The test suite includes:

• Unit tests for all major tools
• Database integration tests
• Configuration validation tests

🔒 Security Considerations

• SQL Injection Prevention: All database queries use prepared statements
• Input Validation: Zod schemas validate all tool inputs
• User Isolation: Data is stored in user-specific directories
• No Network Access: Operates entirely locally for privacy

🤝 Contributing

Contributions are welcome! Please see the Contributing Guidelines for details.

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: npm test
5. Commit your changes: git commit -m "Add amazing feature"
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Code Standards

• Follow TypeScript best practices
• Maintain test coverage above 80%
• Use ESLint configuration provided
• Document new tools and features
• Vibe hardcore

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with the Model Context Protocol SDK
• Uses better-sqlite3 for reliable SQLite operations
• Inspired by untreated ADHD 😅

📞 Support

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Request a feature
• 💬 Questions: Start a discussion

---

⭐ Star this repository if you find it helpful!