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

Related MCP server: mcp-codex-dev

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.