mcp-taskflow-server

armolo23/mcp-taskflow-server

3.2

If you are the rightful owner of mcp-taskflow-server 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.

This document provides a structured overview of a stateful MCP server that organizes tools hierarchically based on context, optimizing agent interactions by reducing unnecessary tool evaluations.

Taskflow MCP — Hierarchical Tool Pattern

Python MCP Pattern License

Taskflow MCP is a reference implementation of a stateful Model Context Protocol (MCP) server that narrows tool exposure to the active workflow. It behaves like a headless app with explicit navigation states, keeping the tool list concise, contextual, and easy for agents to reason about.

Why It Exists

Most MCP servers expose dozens of tools at once. Agents burn tokens evaluating irrelevant options, planning becomes brittle, and long workflows are hard to manage. Taskflow MCP demonstrates the bounded-context pattern: start with lifecycle tools, activate a workflow, surface only the 3–5 tools that matter, and reset when the task is done. The result is lower token usage, clearer task boundaries, and predictable state transitions.

Key Capabilities

  • Dynamic tool list & tool-list-changed notifications per session.
  • Two independent bounded contexts:
    • Notes flow with tagging submenu (notes_create, notes_list, notes_search, notes_open_tagging, notes_add_tag, notes_remove_tag).
    • MLOps pipeline (mlops_generate_data, mlops_train_baseline, mlops_report_metrics) with progress streaming and typed metrics.
  • Structured responses via Pydantic for dependable schemas.
  • Minimal in-memory session state (current task, notes, tagging target, model artifacts, metrics).
  • Reset semantics: complete_task and cancel_task collapse the tool list back to lifecycle entry.

Architecture at a Glance

+--------------+
¦ Lifecycle    ¦  start_task(), complete_task(), cancel_task()
+--------------+
       ¦
       +- start_task("notes")
       ¦    +- notes_create(), notes_list(), notes_search()
       ¦    +- notes_open_tagging()
       ¦         +- notes_add_tag()
       ¦         +- notes_remove_tag()
       ¦
       +- start_task("mlops")
            +- mlops_generate_data()
            +- mlops_train_baseline()   # streams progress + info log
            +- mlops_report_metrics()   # returns Metrics Pydantic model

Tool visibility is limited to five items (or fewer) within any workflow. Returning to lifecycle options is as simple as complete_task or cancel_task.

Repository Layout

PathPurpose
src/server.pySingle-file server implementing the bounded-context pattern.
pyproject.tomlDependency and tool configuration (mcp[cli]>=1.2.0, pydantic>=2.6).
scripts/dev.shConvenience script for running the MCP dev inspector (bash compatible).
README.mdProject overview and usage instructions.
NOTES.mdLoom talking points, email snippet, and impact summary.
DESCRIPTION.txtOne-line GitHub description.
LICENSEMIT license covering the project.
.gitattributesLine-ending rules (scripts/dev.sh forced to LF).
.gitignorePython, packaging, virtualenv, and editor ignores.

(Reference SDK dumps used during development were removed before release.)

Getting Started

Prerequisites

  • Python 3.10+
  • mcp[cli] >= 1.2.0
  • pydantic >= 2.6
  • Bash (for scripts/dev.sh) or PowerShell equivalent on Windows

Installation

python -m venv .venv
source .venv/bin/activate           # Windows PowerShell: .\.venv\Scripts\Activate.ps1
pip install "mcp[cli]>=1.2.0" pydantic

Run the Server

Interactive dev (MCP inspector):

python -m mcp dev src/server.py

StdIO (production deployment):

python src/server.py

Optional Development Tools

Format with Black:

python -m black src/server.py

Ensure executable bit on dev script (run in a POSIX shell once):

git update-index --chmod=+x scripts/dev.sh

Tool Catalog Snapshot

ToolDescription
start_taskEnter notes or mlops context.
complete_task / cancel_taskExit current task and collapse tool list.
notes_createAdd a note (title + body).
notes_listReturn all notes and tags.
notes_searchSubstring search across notes.
notes_open_taggingSelect a note for tag editing or close tagging mode.
notes_add_tag / notes_remove_tagModify tags on the active note.
mlops_generate_dataProduce synthetic regression data (supports noise).
mlops_train_baselineFit a linear model, stream progress, emit info log.
mlops_report_metricsEmit RMSE/MAE/R2 via a Pydantic Metrics model.

Example Agent Flow

  1. start_task("notes")
  2. notes_create / notes_list / notes_search
  3. notes_open_tagging ? notes_add_tag or notes_remove_tag
  4. complete_task

Switch to MLOps:

  1. start_task("mlops")
  2. mlops_generate_data
  3. mlops_train_baseline (monitor progress/logs)
  4. mlops_report_metrics
  5. complete_task

Design Considerations

  • Minimal, per-session state with no persistence (by design).
  • Errors surface clearly (e.g., trying to train before generating data).
  • Validated via a harness that exercises every workflow and asserts state transitions.

Roadmap Ideas

  • Pluggable persistence stores.
  • Shared state or multi-session coordination.
  • Richer ML pipelines or additional bounded contexts.
  • Authentication / authorization layers.

License

MIT — see LICENSE for details.

If you build on Taskflow MCP, drop a star or open an issue. Contributions exploring new bounded contexts or persistence strategies are welcome.