Execution Journal

An MCP server that helps AI coordinate sequential tool calls and maintain a comprehensive journal of execution workflows, decisions, and actions.

What This System Does

Execution Journal is a tool execution planning system that provides:

• Sequential Planning: Design and execute sequences of tool calls
• Execution Tracking: Monitor progress and status of each step
• Decision Recording: Log all decisions made during execution
• Action Journal: Record manual actions taken for audit trails
• Contextual Awareness: Understand relationships between tool calls
• Failure Policies: Define how failures in one step affect other steps
• History Management: Query and clean up execution history

Core Concept

This system acts as a durable memo pad for AI actions and decisions. It doesn't execute rollbacks automatically - instead, it provides a comprehensive record of what was planned, what was executed, and what decisions were made along the way.

Available Tools

Plan Management

• record_plan - Create and store execution plans with cancellability metadata and failure policies
• record_execution_start - Start executing a plan and track progress

Execution Control

• query_ledger - Check execution status, progress, and history for a specific execution
• query_history - Query execution history with comprehensive filtering and pagination
• record_decision - Log decisions made during execution (stop/continue)
• record_action - Record manual actions taken for audit purposes

History Management

• cleanup_history - Clean up old and completed execution history to free up space

Usage Examples

1. Create a Travel Planning Plan

{
  "name": "Summer Vacation Planning",
  "description": "Plan a complete summer vacation with hotel, car, and activities",
  "steps": [
    {
      "id": "book_hotel",
      "name": "Book Hotel",
      "tool": "book_hotel",
      "parameters": {"destination": "Paris", "dates": "2024-07-15 to 2024-07-22"},
      "cancellable": "partially-reversible",
      "failure_policy": {
        "propagate_to": ["book_car", "book_activities"],
        "action": "cancel_dependent",
        "reason": "Hotel is essential for vacation planning"
      }
    },
    {
      "id": "book_car",
      "name": "Book Rental Car",
      "tool": "book_car",
      "parameters": {"pickup_location": "Paris Airport", "dates": "2024-07-15 to 2024-07-22"},
      "cancellable": "reversible",
      "failure_policy": {
        "propagate_to": ["book_activities"],
        "action": "continue_others",
        "reason": "Car is nice to have but not essential"
      }
    }
  ]
}

2. Start Execution

{
  "plan_id": "plan_abc123",
  "notes": "Starting vacation planning execution"
}

3. Monitor Progress

{
  "execution_id": "exec_xyz789",
  "include_step_details": true,
  "include_events": true
}

4. Query History

{
  "query_type": "recent",
  "limit": 10,
  "include_plans": true,
  "include_step_details": false
}

5. Clean Up History

{
  "cleanup_type": "completed_old",
  "older_than_days": 30,
  "dry_run": true
}

6. Record Decisions and Actions

{
  "execution_id": "exec_xyz789",
  "action": "stop",
  "reason": "Hotel booking failed, stopping related bookings"
}

Project Structure

src/
├── tools/                    # Tool implementations
│   ├── RecordPlanTool.ts     # Plan creation
│   ├── RecordExecutionStartTool.ts   # Execution start
│   ├── QueryLedgerTool.ts    # Status monitoring
│   ├── QueryHistoryTool.ts   # History querying
│   ├── RecordDecisionTool.ts # Decision logging
│   ├── RecordActionTool.ts   # Action recording
│   └── CleanupHistoryTool.ts # History cleanup
├── prompts/                  # AI guidance
│   └── ExecutionPlanningPrompt.ts
├── resources/                # Documentation and examples
│   ├── ExecutionDocumentationResource.ts
│   └── ExecutionExamplesResource.ts
├── core/                     # Core system components
│   ├── db.ts                # Database setup
│   └── execution-manager.ts # Execution orchestration
└── types/                    # TypeScript definitions
    └── execution.ts         # Core interfaces

Installation & Setup

# Clone the repository
git clone <repository-url>
cd execution-journal

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

MCP Client Configuration

Add this to your MCP client configuration:

{
  "mcpServers": {
    "execution-journal": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {}
    }
  }
}

Key Features

• Sequential Execution: Tools are called one after another
• Cancellability Metadata: Each step indicates reversibility level
• Failure Policies: Define how failures propagate to other steps
• Comprehensive Journaling: All decisions and actions are recorded
• Execution Monitoring: Real-time status tracking
• History Management: Query and clean up execution history
• Audit Trail: Complete history for compliance and debugging

Cancellability Levels

• reversible: Can be completely undone
• partially-reversible: Can be partially undone
• irreversible: Cannot be undone

Failure Policy Options

• cancel_all: Cancel all remaining steps when this step fails
• cancel_dependent: Cancel only steps that depend on this step
• continue_others: Continue with other steps even if this fails
• manual_decision: Require manual decision on how to proceed

History Query Types

• recent: Most recently updated executions
• incomplete: Pending or running executions
• failed: Failed or cancelled executions
• completed: Successfully completed executions
• all: All executions with pagination

Cleanup Options

• completed_old: Remove old completed executions
• failed_old: Remove old failed executions
• orphaned_plans: Remove plans with no executions
• all_old: Remove all old items

Best Practices

1. Plan Design: Keep steps focused and consider failure scenarios
2. Failure Policies: Design policies that make business sense
3. Monitoring: Check execution status regularly
4. Decision Recording: Log all decisions promptly
5. Action Documentation: Record what was done and why
6. Context Awareness: Understand how tool failures affect related operations
7. History Management: Regularly clean up old data to maintain performance

Development Status

• ✅ Core tools implemented
• ✅ MCP integration complete
• ✅ Database-backed journaling
• ✅ Failure policy support
• ✅ History management tools
• ✅ Comprehensive documentation

Contributing

This project focuses on simplicity and clarity. Contributions should maintain the core principle of providing execution support while improving the user experience for AI-driven tool coordination.

License

MIT License - See LICENSE file for details.