Execution-Journal-MCP

kuil09/Execution-Journal-MCP

3.1

If you are the rightful owner of Execution-Journal-MCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Execution Journal is an MCP server designed to help AI coordinate sequential tool calls and maintain a comprehensive journal of execution workflows, decisions, and actions.

Tools
7
Resources
0
Prompts
0

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.