STARLOG MCP

STARLOG (Session, Task, and Activity Record LOG) is a comprehensive documentation workflow system designed for Claude Code integration via the Model Context Protocol (MCP).

Overview

STARLOG provides three integrated documentation types:

• RULES: Project guidelines with brain-agent enforcement
• DEBUG_DIARY: Real-time development tracking with GitHub issue integration
• STARLOG: Session history with START/END markers for context continuity

Features

🏗️ Project Initialization

• Automated project setup with registry creation
• Integrated starlog.hpi file generation
• Context-aware project configuration

📏 Rules System

• Hierarchical rule management with categories and priorities
• Brain-agent enforcement integration
• Dynamic rule validation and compliance checking

📓 Debug Diary

• Real-time development issue tracking
• Direct GitHub Issues API integration
• Automatic bug report and fix workflow

📋 Session Management

• Comprehensive session START/END tracking
• Goal-oriented work sessions with outcomes
• Historical context preservation

🧭 HPI (Human-Programming Interface) System

• Automatic context assembly from latest session + debug diary
• Project orientation for seamless context switching
• Documentation-driven development workflow

Installation

[Installation instructions pending PyPI publication]

Quick Start

Initialize a STARLOG Project

from starlog_mcp import Starlog

starlog = Starlog()
result = starlog.init_project("my_project", "My Project Name")
print(result)

Add Project Rules

result = starlog.add_rule("Always write tests", "my_project", "testing")
print(result)

Start a Development Session

session_data = {
    "session_title": "Feature Implementation",
    "start_content": "Implementing user authentication",
    "context_from_docs": "Based on security requirements doc",
    "session_goals": ["Add login", "Add logout", "Add password reset"]
}
result = starlog.start_starlog(session_data, "my_project")
print(result)

Get Project Context

context = starlog.orient("my_project")
print(context)  # Complete project context for AI assistance

MCP Server Usage

STARLOG includes a built-in MCP server for Claude Code integration:

starlog-server

Environment Variables

• HEAVEN_DATA_DIR: Directory for STARLOG data storage (default: /tmp/heaven_data)
• OPENAI_API_KEY: Required for brain-agent rule enforcement

MCP Configuration

Add to your Claude Code configuration:

{
  "mcpServers": {
    "starlog": {
      "command": "starlog-server",
      "env": {
        "HEAVEN_DATA_DIR": "/path/to/your/data",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Available MCP Tools

• init_project(path, name) - Initialize new STARLOG project
• rules(path) - View all project rules
• add_rule(rule, path, category) - Add new rule
• update_debug_diary(diary_entry, path) - Add debug diary entry
• view_debug_diary(path) - View debug diary
• start_starlog(session_data, path) - Start new session
• view_starlog(path) - View session history
• end_starlog(session_id, end_content, path) - End session
• orient(path) - Get complete project context
• check(path) - Check project status

Development

Running Tests

pytest tests/

Development Installation

pip install -e .[dev]

Architecture

STARLOG uses the HEAVEN framework's registry system for persistent storage and provides a clean FastMCP-based server implementation for seamless Claude Code integration.

Registry Pattern

Data is stored in isolated registries per project:

• {project_name}_rules - Project rules with enforcement metadata
• {project_name}_debug_diary - Development tracking entries
• {project_name}_starlog - Session history with goals and outcomes

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.