cpuchip/journal-mcp

Journal MCP

A Model Context Protocol (MCP) server for task-based work journaling with AI integration.

Features

• Task-based logging - Organize work by tasks/issues rather than just chronologically
• Issue integration - Link tasks to GitHub issues or Jira tickets
• Structured 1-on-1s - Capture meeting insights, todos, and feedback
• Time-based views - Daily and weekly activity summaries
• Tagging system - Flat tag structure for easy categorization
• Human-readable storage - All data stored as JSON and Markdown
• Search and export - Find entries and export to various formats
• Web interface - View and edit journal entries through a REST API and planned web UI

Installation

1. Clone the repository:

   git clone https://github.com/cpuchip/journal-mcp.git
   cd journal-mcp
   

2. Install dependencies:

   go mod tidy
   

3. Build the server:

   go build -o journal-mcp
   

Usage

Running Modes

MCP Server Only (Default)

./journal-mcp

Web Server Only

./journal-mcp --web
# API available at http://localhost:8080/api
# Documentation at http://localhost:8080/api/docs

Dual Mode (MCP + Web)

./journal-mcp --dual
# Both MCP stdio and web server running

Configuration

The journal data is stored in ~/.journal-mcp/ with the following structure:

~/.journal-mcp/
├── tasks/          # Individual task files (JSON)
├── daily/          # Daily activity summaries  
├── weekly/         # Weekly summaries
└── one-on-ones/    # 1-on-1 meeting records

MCP Tools

Task Management

• create_task - Create new tasks with issue linking
• add_task_entry - Add timestamped entries to tasks
• update_task_entry - Modify existing entries
• get_task - Retrieve complete task history
• list_tasks - List tasks with filtering options
• update_task_status - Change task status (active/completed/paused/blocked)

Time-based Views

• get_daily_log - View all activity for a specific date
• get_weekly_log - View activity for a week

1-on-1 Management

• create_one_on_one - Record structured meeting notes
• get_one_on_one_history - Retrieve meeting history

Search & Export

• search_entries - Search through all journal content
• export_data - Export to JSON, Markdown, or CSV

GitHub Integration

• sync_with_github - Sync assigned GitHub issues with tasks
• pull_issue_updates - Pull latest comments and events from GitHub issues
• create_task_from_github_issue - Create task from GitHub issue URL

Data Management

• create_data_backup - Create comprehensive data backups
• restore_data_backup - Restore from backup files
• get_configuration - Get current configuration
• update_configuration - Update system configuration
• migrate_data - Data migration framework (future SQLite support)

Task Types

• work - Regular work tasks and bug fixes
• learning - Skill development and research projects
• personal - Personal projects and side work
• investigation - Research and exploration tasks

Example Workflow

1. Start a new task:

   {
     "id": "MDU-1450",
     "title": "Fix payment timeout issues", 
     "type": "work",
     "tags": ["api", "debugging", "payment"],
     "issue_url": "https://github.com/company/repo/issues/1450",
     "priority": "high"
   }
   

2. Add work entries throughout the day:

   {
     "timestamp": "2025-09-05T14:30:00Z",
     "content": "Started investigation - customer reports 8s timeouts in payment flow"
   }
   

3. Update status when complete:

   {
     "status": "completed",
     "reason": "Fixed database query optimization, reduced to 200ms"
   }
   

Phase 3 Features (NEW!)

Enhanced GitHub Integration

• Automatic sync with assigned GitHub issues
• Bidirectional updates - issue status changes update tasks
• Comment integration - pull issue comments as task entries
• Event tracking - track labels, assignments, and status changes

Web Interface Foundation

• Complete REST API for all MCP functionality
• Real-time updates via WebSocket
• CORS support for frontend development
• OpenAPI documentation at /api/docs

Data Management

• Backup & restore with ZIP compression
• Configuration management with YAML support
• Migration framework for future database support
• Data integrity validation and versioning

See for complete documentation.

AI Integration

This MCP is designed to work with AI coding assistants to:

• Automatically log work - AI can create entries as you work
• Suggest tasks - Based on patterns and priorities
• Generate summaries - For daily standups or reviews
• Track learning - Monitor skill development over time
• Prepare 1-on-1s - Surface relevant updates and blockers
• GitHub automation - Auto-create tasks from assigned issues

Development

Prerequisites

• Go 1.21+
• Git

Building

go build -o journal-mcp

Testing

go test ./...

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details