Are you the author? Sign in to claim
Unified Cognitive Scaffold MCP Server — Bridging Deep Reasoning and Reliable Execution for LLM Agents. Combines Tree of
Unified Cognitive Scaffold MCP Server — Bridging Deep Reasoning and Reliable Execution for LLM Agents
agent_mcp_thoughtflow is a production-ready Model Context Protocol (MCP) server that unifies structured task execution with systematic reasoning.
Modern LLM agents are excellent at planning (using techniques like Tree of Thoughts) but frequently fail at execution — they explore ideas, then jump straight into implementation while skipping proper task tracking, dependency management, and auditability.
This server solves that gap by providing a single, cohesive cognitive scaffold where:
The result: agents can think deeply, commit reasoning to structured work, execute reliably, and — when blocked — spawn new reasoning trees from existing tasks.
Many agents follow this broken pattern:
agent_mcp_thoughtflow makes the correct workflow the easiest path:
Think → Promote to Tasks → Execute with Tracking → (If blocked) Spawn new reasoning from task
promote_thought_to_tasks — Convert a thought (or entire subtree) into executable tasks with full provenance metadataspawn_tot_from_task — When a task is blocked, spawn a fresh Tree of Thoughts from it for deeper analysislink_thought_to_task — Create soft bidirectional links between thoughts and tasks for "inspired by" or "related to" relationshipsget_cognitive_provenance — Trace the complete reasoning → execution chainAll bridge operations automatically maintain metadata.cognitive and create auditable cognitiveLinks.
parentTaskId + order)startWorkflowExecution + advanceWorkflowRun for controlled executiongetReadyTasks for just-in-time task dispatchingverified, verifiedAt, verificationNotes, verificationMethod for tracking verification statusscore, creativity, risk, custom criteria)verified, verifiedAt, verificationNotes, verificationMethod for tracking verification statustreeIds and workflowIdsadd_tree_to_strategy, add_workflow_to_strategy, remove_tree_from_strategy, remove_workflow_from_strategyvisualize_tree_ascii)visualize_tree_with_links)get_cognitive_stats for high-level metricsBaseServiceToolRegistry for maintainable tool definitionsnpm install agent_mcp_thoughtflow
Or run directly with npx:
npx agent_mcp_thoughtflow
npx agent_mcp_thoughtflow
The server uses JSON file storage by default (./thoughtflow-state.json).
// 1. Create a reasoning tree
create_tree({
"goal": "Design a robust caching strategy for our API",
"rootContent": "Start with a simple in-memory cache"
})
// 2. Explore and evaluate thoughts...
// 3. Promote the best approach to tasks
promote_thought_to_tasks({
"treeId": "...",
"thoughtId": "...",
"includeDescendants": true,
"workflowId": "optional-existing-workflow"
})
// 4. Start executing the workflow
start_workflow_execution({ "workflowId": "..." })
// 5. If a task gets blocked, spawn new reasoning
spawn_tot_from_task({
"taskId": "...",
"goal": "Investigate why the cache invalidation is failing",
"rootContent": "The cache is not being invalidated on write operations"
})
For new projects, use quick_plan to create strategy + workflow + tasks + root thought in a single call:
quick_plan({
"goal": "Implement user authentication system",
"tasks": [
{ "name": "Design auth schema", "description": "Define user, session, and token tables" },
{ "name": "Implement password hashing", "dependencies": ["task-1"] },
{ "name": "Create login endpoint", "dependencies": ["task-2"] },
{ "name": "Add JWT token generation", "dependencies": ["task-3"] },
{ "name": "Implement logout logic", "dependencies": ["task-4"] }
],
"strategyName": "auth-system",
"workflowName": "auth-implementation"
})
// Returns:
// {
// strategyId: "auth-system",
// workflowId: "auth-implementation",
// taskIds: ["task-1", "task-2", "task-3", "task-4", "task-5"],
// treeId: "...",
// rootThoughtId: "..."
// }
This reduces 4-5 tool calls to 1, making onboarding friction-free.
The Thoughtflow Dashboard provides a comprehensive web interface for inspecting cognitive provenance, including:
# Build the project first (if not already built)
npm run build
# Start the dashboard server
npm run dashboard
The dashboard server will start on port 3000 (or the next available port if 3000 is in use). You'll see output like:
Thoughtflow Dashboard server running at http://localhost:3000
Dashboard: http://localhost:3000/dashboard
API: http://localhost:3000/api/state
State Info: http://localhost:3000/api/state/info
Open your browser and navigate to:
http://localhost:3000/dashboardThe dashboard server provides the following API endpoints:
GET /api/state — Returns the complete Thoughtflow state (strategies, tasks, trees, workflows, cognitive links)GET /api/state/info — Returns state metadata (exists, lastModified, size)| Tool | Purpose |
|---|---|
promote_thought_to_tasks | Convert reasoning into tracked executable work |
spawn_tot_from_task | Spawn fresh reasoning from a blocked task |
link_thought_to_task | Create soft bidirectional links for "inspired by" or "related to" relationships |
get_cognitive_provenance | Trace full reasoning → execution history |
complete_task_and_thought | Atomically mark task completed and evaluate/verify linked thoughts |
quick_plan | Single call to create strategy + workflow + tasks + root thought |
sync_workflow_thoughts | Scan completed tasks and evaluate pending linked thoughts |
Note: promote_thought_to_tasks supports skipEvaluationGate: true for simple workflows that don't need the evaluate+select cycle. The system uses debounce mechanisms to prevent race conditions during heavy LLM usage.
| Category | Tools |
|---|---|
| Tasks | create_tasks (batch), get_task, list_tasks, update_task, delete_task |
| Workflows | create_workflow, get_workflow, list_workflows, addTasksToWorkflow |
| Execution | start_workflow_execution, advance_workflow_run, getReadyTasks |
| Hierarchy | get_subtasks, move_task |
| Strategies | create_strategy, get_strategy, list_strategies, add_tree_to_strategy, remove_tree_from_strategy |
| Soft-Delete | purge_deleted, restore_deleted |
Note: Single-item task creation (create_task) is not available. Use create_tasks (batch) for all task creation. It supports positional references (task-1, task-2) for dependencies and parent-child relationships within the batch, and returns an idMap for mapping positional refs to real IDs.
| Category | Tools |
|---|---|
| Trees | create_tree, get_tree, list_trees, delete_tree |
| Thoughts | add_ideas (batch), get_thought, evaluate_thought, verify_thought, select_thought, backtrack, prune_tree |
| Strategies | create_strategy, get_strategy, list_strategies, add_workflow_to_strategy, remove_workflow_from_strategy |
Note: Single-item idea creation (add_idea) is not available. Use add_ideas (batch) for all idea creation. It supports positional references (idea-1, idea-2) for parentId within the batch, uses fuzzy matching for robustness, and returns an idMap for mapping positional refs to real IDs.
All delete operations use soft-delete by default — entities are marked as deleted but preserved for recovery.
includeDeleted parameter: All get_* and list_* tools support an optional includeDeleted: true parameter to view soft-deleted items.restore_deleted: Restore a soft-deleted entity back to active state. Requires entityType ('task', 'workflow', 'tree', 'strategy', 'link') and id.purge_deleted: Permanently remove soft-deleted items (cannot be undone). Supports filtering by entityType and olderThanDays for safe cleanup.Example workflow:
// 1. Delete a task
delete_task({ "id": "task-123" })
// 2. List active tasks (deleted task hidden)
list_tasks() // → task-123 not visible
// 3. List with deleted included
list_tasks({ "includeDeleted": true }) // → task-123 visible with isDeleted flag
// 4. Restore if needed
restore_deleted({ "entityType": "task", "id": "task-123" })
// 5. Permanently purge old deleted items (e.g., older than 30 days)
purge_deleted({ "entityType": "task", "olderThanDays": 30 })
Cognitive links can accumulate over time. The system includes built-in deduplication tools to manage state size:
deduplicate_strategies_and_trees — Removes duplicate strategies and trees by normalized name/goaldeduplicate_strategies — Removes duplicate strategies onlydeduplicate_trees — Removes duplicate trees onlyFor production workloads with heavy cognitive link usage, monitor state file size and run deduplication periodically.
visualize_tree_asciivisualize_tree_with_linksvisualize_workflow_svgvisualize_task_svgvisualize_strategy_svgget_cognitive_statsThe intended usage pattern for LLM agents:
create_tree + add_idea + evaluate_thought to explore solution spacepromote_thought_to_tasks on the most promising branchstart_workflow_execution + advance_workflow_run (or getReadyTasks)spawn_tot_from_task on the stuck taskget_cognitive_provenance when traceability is requiredThis pattern turns ad-hoc reasoning into auditable, resumable, delegable work.
The system uses a strict hierarchical relationship model for organizing cognitive work:
Strategy (Top-Level Organizer - Mandatory Owner)
├── workflowIds: string[] → Workflows (each workflow belongs to exactly ONE strategy)
├── treeIds: string[] → Trees of Thoughts (reasoning, optional strategy association)
└── metadata: Record<string, any>
Workflow (Execution Container - Mandatory Owner)
├── strategyId: string → Strategy (mandatory, exactly one)
├── taskIds: string[] → Tasks (each task belongs to exactly ONE workflow)
└── metadata: Record<string, any>
Task (Executable Unit - Mandatory Owner)
├── workflowId: string → Workflow (mandatory, exactly one)
├── strategyId: string → Strategy (denormalized from workflow for convenience)
├── parentTaskId?: string → Subtask parent (must be in same workflow)
├── dependencies: string[] → Task dependencies (must be in same workflow)
└── metadata: Record<string, any>
Idea (Thought) ↔ Task (Soft Bidirectional Links)
├── Thought.metadata.cognitive.linkedTaskIds
├── Task.metadata.cognitive.linkedThoughtIds
├── syncStatus: 'synced' | 'outdated' | 'conflict'
└── provenanceChain: ProvenanceEntry[]
parentTaskId validation)workflowId)All creation flows must follow the hierarchy:
create_strategy — Create or get strategy (idempotent by normalized name)create_workflow(strategyId) — Create workflow with mandatory strategyIdcreate_task(workflowId) — Create task with mandatory workflowId (automatically inherits strategyId)The system enforces these invariants at every operation to prevent data inconsistency.
┌─────────────────────────────────────────────────────────────┐
│ Thoughtflow MCP Server │
├─────────────────────────────────────────────────────────────┤
│ CognitiveBridgeService ←→ TaskOrchestratorService │
│ ↑ ↑ │
│ │ │ │
│ ToTService Workflow Execution Engine │
│ │ │ │
│ └──────────┬───────────────┘ │
│ │ │
│ VisualizationService │
└─────────────────────────────────────────────────────────────┘
All services extend BaseService for unified state management, auto-save, and shutdown behavior.
thoughtflow-state.json)The storage layer is abstracted via IStorageAdapter, making it easy to add new backends.
The ToT system supports multiple LLM backends:
GrokLLMProvider) — Recommended for high-quality structured evaluationOllamaLLMProvider) — Local/private modelsMockLLMProvider) — Testing and development# Install dependencies
npm install
# Run in development mode
npm run dev
# Build
npm run build
Contributions are welcome! Please open an issue first to discuss major changes.
Focus areas:
MIT © 2026
This project was born from the observation that reasoning without execution tracking is incomplete, and execution without reasoning provenance is fragile.
agent_mcp_thoughtflow exists to make the full cognitive loop first-class in agent systems.
Built with ❤️ for agents that need to think and ship.
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots
@googleapis✓ OfficialGoogle's universal MCP server supporting PostgreSQL, MySQL, MongoDB, Redis, and 10+ databases
@github✓ OfficialOfficial GitHub integration for repos, issues, PRs, and CI/CD workflows