MCP Orchestrator Workflow Engine

This is an open-source, Model Context Protocol (MCP) compliant backend service, implemented atop Cloudflare Workers, dedicated to the rigorous administration and sequential dispatch of operational units (tasks). It establishes a reliable backbone for AI assistants navigating multi-stage objectives, utilizing Cloudflare KV for transactional data persistence and state integrity.

🌟 Core Capabilities

• Complex Directive Decomposition: Facilitates the breakdown of high-level objectives into discrete, manageable steps.
• Stateful Task Governance: Full lifecycle management (creation, modification, archival) and status oversight for every component task.
• Mandatory Gatekeeping: Integrated mechanisms requiring explicit authorization for advancing task or overall request closure.
• Visibility & Auditing: Provides granular views into progress tables and exhaustive records of all task metadata.
• Data Durability: Leverages Cloudflare KV bindings to ensure reliable, non-volatile storage of all workflow states.
• Global Edge Runtime: Deployment exclusively as a Cloudflare Worker guarantees low-latency accessibility worldwide.
• Standardized Interfacing: Exposes conventional RESTful HTTP interfaces for broad application connectivity.
• Web Compatibility: Full Cross-Origin Resource Sharing (CORS) facilitation for seamless integration with front-end interfaces.

📦 Deployment & Setup

Prerequisites

• Active Cloudflare subscription (Free tier is sufficient).
• Installation of the Wrangler CLI tool.
• Node.js environment (version 18 or newer) with npm/pnpm/yarn.
• Git client initialized for repository cloning.

Initial Deployment Sequence

1. Repository Acquisition & Setup bash git clone https://github.com/Rudra-ravi/mcp-taskmanager.git cd mcp-taskmanager npm install

2. Cloudflare Authentication bash npx wrangler login

(This initiates a browser-based authorization flow with Cloudflare.)

1. KV Namespace Provisioning bash npx wrangler kv namespace create "WORKFLOW_STATE_STORE"

Record the returned namespace identifier.

1. Configuration File Adjustment Modify wrangler.toml to incorporate the newly obtained namespace ID: toml [[kv_namespaces]] binding = "WORKFLOW_STATE_STORE" id = "your-newly-generated-kv-identifier"

2. Build and Publish bash npm run build npx wrangler deploy

The operational endpoint will be accessible at a URL similar to: https://mcp-taskmanager.your-subdomain.workers.dev

Advanced Configuration

Custom Service Naming

Adjust the name field in wrangler.toml for deployment branding: toml name = "custom-orchestrator-v1" main = "worker.ts" compatibility_date = "2024-03-12"

[build] command = "npm run build"

[[kv_namespaces]] binding = "WORKFLOW_STATE_STORE" id = "your-kv-namespace-id-here"

Environment Segregation

Define distinct configurations for isolated operational stages: toml [env.testing] name = "orch-test-instance" [[env.testing.kv_namespaces]] binding = "WORKFLOW_STATE_STORE" id = "testing-kv-identifier"

[env.production] name = "orch-live-instance" [[env.production.kv_namespaces]] binding = "WORKFLOW_STATE_STORE" id = "production-kv-identifier"

Deployments targeting specific environments: bash npx wrangler deploy --env testing

🔧 Operational Interface (API)

Interactions adhere to the MCP specification, routed through the Worker's HTTP interface:

• POST /list-tools - Queries and returns the registry of available functions.
• POST /call-tool - Initiates execution of a specified tool function.

Verification Commands

(Ensure to substitute $WORKER_URL with your actual deployment address)

Tool Registry Check: bash curl -X POST $WORKER_URL/list-tools \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Initial Request Registration Example: bash curl -X POST $WORKER_URL/call-tool \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "request_planning", "arguments": { "originalRequest": "Automate financial reporting sequence", "tasks": [{"title": "Gather Q1 Data", "description": "Extract sales figures from DB"}] } } }'

Exposed Function Set

📋 Primary Workflow Control

• request_planning: Establishes a new overarching request artifact and decomposes it into initial execution steps.
• get_next_task: Retrieves the highest-priority, pending operational unit for processing.
• mark_task_done: Flags a task as functionally complete, optionally supplying observational data.
• approve_task_completion: Formal sign-off on an individual completed task's results.
• approve_request_completion: Final authorization signifying the entire user objective is met.

⚙️ Procedural Modifications

• add_tasks_to_request: Dynamically injects supplementary tasks into an active request structure.
• update_task: Modifies the metadata (label/description) of tasks currently in a 'Pending' state.
• delete_task: Removes an item from the defined task sequence.
• open_task_details: Fetches exhaustive documentation for a single, specified task.

📊 Observability & Reporting

• list_requests: Generates an inventory of all registered workflows and their present completion metrics.

📊 Data Schemas

Task Data Structure

typescript interface Task { id: string; // Unique identifier (e.g., "t-9a4f") title: string; // Concise summary label description: string; // In-depth procedural explanation done: boolean; // Completion flag (pre-approval) approved: boolean; // Final sign-off status completedDetails: string; // Rationale/output accompanying 'done' status }

Request Artifact Structure

typescript interface RequestEntry { requestId: string; // Unique identifier for the workflow (e.g., "req-xyz") originalRequest: string; // Source prompt or directive from the initiator splitDetails: string; // Contextual narrative on how the objective was partitioned tasks: Task[]; // Collection of all requisite operational units completed: boolean; // Finalized state of the encompassing request }

State Transition Pathway

Uninitiated (Pending) → Execution Phase (Marked as Done) → Vetting Phase (Awaiting Approval) → Finalized (Approved)

Modifications are strictly prohibited once a task enters the 'Done' state or after receiving formal approval.

🛠️ Development & Local Iteration

Local Setup Commands

bash

Install necessary packages

npm install

Compile TypeScript sources

npm run build

Run worker locally, connecting to live remote KV

npx wrangler dev

Run worker locally, using entirely local storage for testing

npx wrangler dev --local

Testing Artifacts

bash

Verify compilation integrity

npm run build

Simulate deployment without publishing

npx wrangler deploy --dry-run

Execute defined unit tests (if present)

npm test

Debugging Utilities

Accessing operational logs in real-time from the deployed service: bash

Stream all worker output

npx wrangler tail

Stream output with improved readability

npx wrangler tail --format pretty

KV Data Manipulation (Via Wrangler CLI)

bash

Display all stored key-value pairs

npx wrangler kv:key list --binding WORKFLOW_STATE_STORE

Retrieve content for a specific key

npx wrangler kv:key get "metadata_index" --binding WORKFLOW_STATE_STORE

CAUTION: Completely purge all stored data associated with this binding

npx wrangler kv:key delete "*" --binding WORKFLOW_STATE_STORE

🏗️ System Architecture Overview

The engine operates on a decoupled, edge-native architecture:

┌──────────────────┐ ┌──────────────────────────┐ ┌──────────────────┐ │ AI Agent / Client│───▶│ Cloudflare Edge Worker │───▶│ Cloudflare KV Store│ │ (MCP Consumer) │ │ (API Gateway & Handler) │ │ (Data Persistence) │ └──────────────────┘ └───────────┬──────────────┘ └──────────────────┘ │ ▼ ┌──────────────────┐ │ Workflow Core │ │ (Business Logic) │ └──────────────────┘

Key Architectural Pillars

• WorkflowCore Class: Encapsulates all task sequencing and state transition logic.
• WorkerInterface: Manages HTTP request parsing (JSON-RPC) and response formatting.
• Cloudflare KV: Provides transactional, key-value persistence for high availability.
• MCP Compliance: Ensures interoperability with standard AI interaction protocols.
• CORS Support: Necessary headers provisioned for client-side web consumption.

Advantages of this Pattern

• Global Distribution: Minimal latency due to execution across Cloudflare's global network.
• Zero Infrastructure Overhead: True serverless operation; automatic scaling and maintenance.
• Resilient State: Data integrity maintained through durable, distributed storage.
• Economic Efficiency: Highly scalable while leveraging Cloudflare's cost-effective platform.
• Uptime Guarantee: Inherited high availability features from the Cloudflare platform.

📈 Operational Health and Logging

Monitoring Access

Metrics and verbose logs are accessible via the Cloudflare web interface: 1. Access the Cloudflare Dashboard. 2. Navigate to the 'Workers & Pages' section. 3. Select the mcp-taskmanager service instance. 4. Review the built-in analytics, performance graphs, and log streams.

Live Log Tailoring

bash

Monitor live stream

npx wrangler tail

View logs in a developer-friendly format

npx wrangler tail --format pretty

Isolate error conditions during debugging

npx wrangler tail --status 5xx

Critical Performance Indicators (KPIs)

• Request Throughput: Rate of incoming API interactions.
• Operation Latency: Measured time taken for state changes.
• Error Frequency: Rate of server-side exceptions (5xx).
• Storage IO: Efficiency of read/write operations against KV.
• Resource Utilization: Worker memory footprint per execution.

Common Failure Resolution

Symptom	Probable Origin	Remedial Action
500 HTTP Response	Uninitialized KV Binding	Confirm correct id in wrangler.toml for WORKFLOW_STATE_STORE
Browser Access Blocked	Incorrect CORS Headers	Review and adjust Cross-Origin policy within worker.ts
Task ID Not Found	Input validation error	Validate UUID format and ensure request ID exists in storage
Build Artifact Failure	Type checking violation	Execute local build (npm run build) to identify static errors

🤝 Community Collaboration

Contributions are welcomed to enhance this management layer. Follow these steps:

Contribution Framework

1. Fork this repository.
2. Clone your fork locally.
3. Establish a dedicated feature branch (e.g., git checkout -b feature/new-automation-step).
4. Install environment dependencies (npm install).
5. Implement and validate changes.
6. Test in a local simulation: npx wrangler dev --local.

Coding Standards

• Adhere strictly to TypeScript conventions.
• Ensure comprehensive unit tests accompany all new functionalities.
• Documentation (README/inline comments) must reflect API signature changes.
• Utilize Conventional Commits specification for commit messages.

Submission Protocol

1. Commit staged changes with a descriptive message.
2. Push the branch to your fork.
3. Submit a detailed Pull Request referencing any linked issues or required context.

Potential Development Areas

• Implementing robust error handling for transient KV failures.
• Expanding the set of available operational tools.
• Integrating more sophisticated throttling/rate-limiting measures.

License

Proprietary/Open Source Dual Licensing - See the LICENSE file for specific terms.

💬 Support Channels

For assistance, inquiries, or feature suggestions: - Issue Tracker: Submit Bugs or Feature Requests Here - Community Forum: Discussions for Ideas and Questions

When reporting faults, provide the deployed Worker URL, exact reproduction steps, and relevant log output.

🙏 Recognition

• Leverages core concepts from the Model Context Protocol Initiative.
• Execution environment provided by Cloudflare Workers Platform.
• Engineered to streamline complex sequences for advanced autonomous agents.

---

Deployment Directive: Initialize this service to govern your AI-driven processes with precision and accountability.

BUSINESS MANAGEMENT TOOLS: These systems encompass methodologies, applications, and controls utilized by organizations to navigate evolving market conditions, secure competitive standing, and elevate operational performance. They span functional areas from transactional data handling to strategic decision support, reflecting the ongoing technological shift toward cloud-native, scalable solutions.