Mcp Taskflow Server

Taskflow MCP � Hierarchical Tool Pattern

[](#) [](#) [](#) [](#)

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

| Path | Purpose | | ---------------- | -------------------------------------------------------------------------- | | src/server.py | Single-file server implementing the bounded-context pattern. | | pyproject.toml | Dependency and tool configuration (mcp[cli]>=1.2.0, pydantic>=2.6). | | scripts/dev.sh | Convenience script for running the MCP dev inspector (bash compatible). | | README.md | Project overview and usage instructions. | | NOTES.md | Loom talking points, email snippet, and impact summary. | | DESCRIPTION.txt| One-line GitHub description. | | LICENSE | MIT license covering the project. | | .gitattributes | Line-ending rules (scripts/dev.sh forced to LF). | | .gitignore | Python, 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

| Tool | Description | | ------------------------ | ----------------------------------------------------- | | start_task | Enter notes or mlops context. | | complete_task / cancel_task | Exit current task and collapse tool list. | | notes_create | Add a note (title + body). | | notes_list | Return all notes and tags. | | notes_search | Substring search across notes. | | notes_open_tagging | Select a note for tag editing or close tagging mode. | | notes_add_tag / notes_remove_tag | Modify tags on the active note. | | mlops_generate_data | Produce synthetic regression data (supports noise). | | mlops_train_baseline | Fit a linear model, stream progress, emit info log. | | mlops_report_metrics | Emit 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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: armolo23
• Source: armolo23/mcp-taskflow-server
• License: MIT

Install and usage instructions live in the source repository linked above.