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

Related MCP server: agent-comm

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.