mdflow MCP Server
mdflow MCP Server lets an AI agent register, inspect, mutate, validate, and verify mdflow/ContextOS project state across architecture, source bindings, plans, checkpoints, commands, and timeline.
Register an existing directory as an mdflow project by creating
.mdflow/project.json.Read compact project maps, graph status, searches, validations, change sequences, entities, decisions, and plans.
Manage architecture graph: Blocks, Chains, Links, Decisions, Plans, Checkpoints, scopes, and source refs via atomic mutations, patches, flows, or simple connects.
Suggest and persist AST source bindings for Blocks; sync source files to report moved, changed, missing, or ambiguous bindings.
Extract contract-first code streams along Chains, including symbols, signatures, line ranges, contracts, or bounded slices.
Run project-local commands such as tests and builds, returning redacted compressed summaries instead of raw output.
Sanitize build/test/terminal logs by stripping ANSI noise, collapsing routine output, and isolating failure traces.
Create, record, list, refresh, and validate checkpoints with evidence, execution IDs, and completion gates.
Seal a verified Block when it has current source bindings and a fresh passed checkpoint.
Replace one already-bound AST symbol body with a verification command.
Generate Foundation Plans from unimplemented Blocks with dependency-ordered steps, checkpoints, and integration gates.
Read budgeted task context packs and hierarchical Plan documents.
View and sync the project timeline, advance Plan steps, and revert safe reversible ChangeSets.
Supports configuring Google Antigravity to use mdflow's architecture graph, task-scoped code context, and verified/rollback-safe code mutation workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mdflow MCP Server give me context for the current task and its validation status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
中文 · Install with AI · Measured results · Desktop App
Give your agent an exoskeleton

ContextOS is a local development runtime between an AI coding agent and your repository. It keeps source evidence, command logs, plans, architecture, and verification receipts outside the main conversation, then returns the pieces needed for the next decision.
OS supports the entire AI development lifecycle: understand the project, plan, inspect evidence, execute, implement, verify, review, and resume. Precise reads, reusable commands, pipelines, Blocks, Chains, persistent plans, Micro, and CLI all serve the same purpose: reduce unnecessary token consumption and context occupancy while keeping development grounded in inspectable project state.
Your existing coding assistant stays in charge. OS supplies the execution and memory layer beneath it, including bounded API Micro assistance and isolated CLI implementation when a task benefits from delegation.
In a recorded real development task, the full OS + Micro + CLI workflow reduced peak main-thread context by 63.8% and main-thread cumulative raw tokens by 77.4% compared with native tools. See the task, comparison, and limits below.
Related MCP server: engrams
Why long coding sessions get expensive
A small question often triggers a large file read. A failed test fills the conversation with logs. The agent revisits the same code, repeats a command, and spends its attention reconstructing decisions made earlier. Multi-file implementation then shares the same context window as planning and review.
The result is familiar: a crowded conversation, repeated explanations, uncertain project state, and less room for the next useful decision. A larger context window postpones the problem; development needs a way to carry this work across tools and sessions.
How OS carries the work
You → Main agent: plan, scope, architecture, review
│
└─ ContextOS: evidence, commands, changes, persistent state
├─ API Micro: bounded discovery, summaries, small checks
├─ CLI worker: isolated implementation → report → integration
└─ Desktop App: architecture, plans, checkpoints, settingsEvidence and logs are saved locally. Workers read task evidence in their own contexts and return compact reports. Changes pass through OS so file ownership, verification, and the project graph stay connected. A fresh session can recover the plan and receipts instead of reconstructing the entire transcript.
Capabilities and their practical effect
Capability | How it works | What it achieves |
Evidence · | Inspect exact paths, line ranges, and AST symbols; recover earlier evidence by result ID and check source versions. | Read the relevant implementation and reuse valid evidence instead of repeatedly loading whole files. |
Commands · | Execute once, persist stdout/stderr and exit status, then retrieve a focused section by command ID. | Keep build noise outside the main context and recover the useful failure without rerunning the process. |
Batches · | Combine known steps in serial or parallel execution, with per-step results and continuation. | Reduce tool round trips; group independent reads and checks in one call. |
Architecture · Block | Bind curated source files to architecture units with boundaries, state, and verification evidence. | Make ownership visible and keep implementation changes connected to the architecture. |
Architecture · Chain | Connect Blocks into project paths and record their relationships and progress. | See which capabilities depend on each other and follow a feature across module boundaries. |
Changes · | Apply scoped changes through OS or merge a worker's isolated diff, with verification receipts. | Review actual changes and keep architecture state current during implementation. |
Small assistant · | A configured API model performs bounded retrieval, summarization, diagnosis, or a small edit and returns a compact report. | Move routine tool loops into a lower-cost assistant context; keep the main agent available for judgement. |
Implementation · | A configured CLI adapter runs a task in an isolated workspace, supports background collection, and returns changes, checks, and blockers. | Move complex implementation out of the main conversation and integrate a reviewable result. |
Continuity · plans, tasks, sessions | Persist intent, progress, rules, decisions, and receipts in the project's OS state. | Resume real project work across conversations and inspect progress in the App. |
Micro and CLI help when the task contract is clear. A small deterministic read can use OS directly; a broad implementation belongs to a CLI worker. Delegation has overhead, so OS makes its execution and results inspectable.
Three development workflows, measured
The recorded comparison started from commit 0dd6431. Fresh host conversations and isolated worktrees received the same real feature: plan dependency add/remove/list, persistence, validation of unknown targets, duplicates, self-reference and cycles, MCP routing, and tests across domain, application, storage, and MCP layers. Historical measurement record.
Workflow | Peak main-thread context | Reduction vs native | Main-thread raw tokens | Tests passed |
Native tools | 234,174 | baseline | 8,016,375 | 778 / 778 |
OS + API Micro | 145,694 | 37.8% | 4,993,135 | 778 / 778 |
OS + API Micro + CLI | 84,681 | 63.8% | 1,809,566 | 781 / 781 |
What “60% less context” means here: peak input to a main-agent request fell from 234,174 to 84,681 tokens. It describes this measured task, rather than a promise for every repository or the combined tokens of every worker.
Raw tokens are cumulative input plus output; peak context is the largest single main-agent input. Cached input is included in input, so uncached = input − cached. Reasoning tokens are included in output and are not counted or charged twice.
The specified comparison uses equivalent tokens = main raw + (Micro raw + CLI raw) / 7:
Arm / workflow | Main raw | Micro raw | CLI raw | Observed total raw | Equivalent tokens | Reduction vs native |
A · Native | 8,016,375 | 0 | 0 | 8,016,375 | 8,016,375 | baseline |
B · OS only, no assistant | 6,119,582 | 0 | 0 | 6,119,582 | 6,119,582 | 23.7% |
C · OS + Micro | 4,993,135 | 734,551 | 0 | 5,727,686 | 5,098,070.9 | 36.4% |
D · OS + Micro + CLI | 1,809,566 | 3,258,709† | 4,393,118 | 9,461,393† | 2,902,684.1† | 63.8%† |
For USD, the user-specified comparison rates per million tokens are $2 for uncached input, $0.10 for cached input, and $10 for output:
base USD = (uncached input × 2 + cached input × 0.1 + output × 10) / 1,000,000
equivalent USD = main base USD + (Micro base USD + CLI base USD) / 7
Arm | Role | Input | Cached input | Uncached input | Output | Base USD | Divisor | Equivalent USD |
A | Main | 7,971,486 | 7,773,056 | 198,430 | 44,889 | $1.6230556 | 1 | $1.6230556 |
B | Main | 6,073,014 | 5,945,216 | 127,798 | 46,568 | $1.3157976 | 1 | $1.3157976 |
C | Main | 4,952,753 | 4,710,016 | 242,737 | 40,382 | $1.3602956 | 1 | $1.3602956 |
C | Micro | 720,163 | 636,800 | 83,363 | 14,388 | $0.3742860 | 7 | $0.053469428571 |
D | Main | 1,788,852 | 1,746,560 | 42,292 | 20,714 | $0.4663800 | 1 | $0.4663800 |
D | Micro | 3,211,208† | 3,007,232† | 203,976† | 47,501† | $1.1836852† | 7 | $0.169097885714† |
D | CLI | 4,355,283 | 4,214,016 | 141,267 | 37,835 | $1.0822856 | 7 | $0.154612228571 |
Workflow | Total equivalent USD | Reduction vs native |
Native | $1.623055600000 | baseline |
OS only | $1.315797600000 | 18.9% |
OS + Micro | $1.413765028571 | 12.9% |
OS + Micro + CLI | $0.790090114286† | 51.3%† |
These are equivalent consumption and costs under the specified model, not actual provider invoices or verified provider rates. The assistant divisor of 7 is a chosen comparison assumption. All main sessions reported the deepseek-v4.1-flash alias with max reasoning effort and a custom provider; Micro C/D retained the same session lastModel, and D CLI reported the same alias/custom provider. This does not independently verify the underlying backend model.
Main usage is deduplicated by provider response ID and matches terminal cumulative totals. C Micro has 2 receipts and provider usage for all 26/26 started requests. D CLI has 51 unique cumulative states whose last-usage sum matches its terminal total. † D Micro has 5 receipts, 129 started requests and 128 usage-bearing responses. One continuation timeout request has unknown usage. D totals and the 51.3% cost reduction are observed subtotals; the missing request is not assigned zero. Original Micro reasoning fields are unavailable and remain unknown.
The full workflow used more observed total raw tokens than native tools while reducing peak main context. OS-only reached 184,507 peak tokens (−21.2%) and lower equivalent USD than OS + Micro in this run. This is one feature's historical single-run comparison; results vary with task, model, caching and delegation.
Inspect the frozen evidence and methodology, original usage fields and coverage, role costs CSV, and four-arm totals CSV. Recompute and check the published file hashes with:
python3 docs/benchmarks/plan-dependencies/recalculate.py --checkSee your project in the App
The desktop App projects the same OS state that agents use: Blocks, Chains, plans, checkpoints, rules, and knowledge. Its white canvas, restrained color, and precise connections make a large project readable.

Read the whole system at a glance. Follow a Chain through its Blocks, inspect the selected capability, and see implementation and verification progress alongside the graph.

Follow impact across modules. A highlighted Chain connects integration, packaging, and verification work.

See the evidence behind completion. Checkpoints expose their status and receipt references.

Keep project knowledge close. Open repository documentation and rules from the project sidebar.

Read documentation inside the App. The reader opens repository content alongside the project; performance figures follow the reproducible evidence below.

Manage your development environment. Settings bring preferences and host integration into the App. Configure shared models and reasoning levels, let each role inherit them with Use Global, and synchronize available models and effort options for Micro and CLI adapters.
The settings image above shows an earlier accepted layout.

Use OS from your coding assistant. The host loads the MCP runtime and matching skill so the agent can operate on project state.
Some gallery images were captured from earlier builds and retain the former mdflow name or earlier version labels. They demonstrate the workflow; follow the installer for the current runtime and configuration.
Install with one prompt
Paste this into your AI coding assistant:
读取 (https://github.com/yubinbin32-ops/ContextOS/blob/main/setup.md) ,为我安装OS
The agent reads setup.md, installs OS and matching host plugins/skills, registers your repository, configures API Micro and your CLI, and verifies the result with real tool calls. It handles dependency checks, adapter creation, plugin setup, and diagnosis for you.
You do not need to download and configure a Release package by hand. The setup guide is written for the installing agent, including diagnosis, adapter configuration, plugin installation, and acceptance checks.
Micro is required
Micro is the small assistant for routine work, and its API connection is required for the OS workflow. Prepare an API key, provider base URL, and model. A main-agent subscription or CLI login alone does not configure API Micro.
Recommended options:
Command Code GOAT: includes Provider API access. Create a key in its console; let the agent use the provider's current endpoint and exact model ID.
OpenCode Go: provides a subscription API key and available coding models. Have the agent check the current model list and API configuration.
Your own compatible API: use a provider you already trust, including the DeepSeek API.
For bounded Micro tasks, we recommend DeepSeek V4.1 Flash with medium reasoning where the provider supports it. The official DeepSeek model ID is deepseek-flash; gateways can use different IDs. The installer must verify model availability and map the provider's reasoning setting instead of assuming every API accepts the same parameters.
Keep the key in the local credential/configuration path established by the installer. Do not paste it into repository documentation or tracked source.
CLI setup is completed by the agent
CLI workers require a working CLI installation, an adapter, the matching ContextOS plugin/skills, and a verified authenticated execution path. Tell the agent which CLI you use; it should consult that CLI's official documentation, write the adapter, configure OS, and run a real probe and isolated implementation check.
A login, browser authorization, or operating-system permission may require your action. The agent should identify that exact step, continue the remaining setup, and verify readiness after you complete it. A discovered binary or saved adapter alone is not a successful installation.
Node.js 22 or later is required. After a plugin/runtime update, reload the host's MCP process as directed by setup. Keep the App, plugin, skills, and runtime on matching versions.
Daily use, in ordinary language
What you want | Prompt to your agent |
Start a planned task | “Write this plan into OS and start executing it.” |
Resume tomorrow | “Read the current OS plan and session state, then continue the next unfinished task.” |
Configure the small assistant | “Configure Micro for me, verify its API connection, and use it for bounded tasks.” |
Configure implementation workers | “Configure my CLI for me. Write its adapter, install the ContextOS plugin, and test an isolated implementation.” |
Explore a bug | “Use Micro to locate the cause; return the relevant evidence and one compact diagnosis.” |
Implement a feature | “Delegate this implementation to CLI in an isolated workspace, verify it, and integrate the result through OS.” |
Review progress | “Update the Blocks, Chains, and checkpoints so I can inspect progress in the App.” |
Change tools | “Switch to my other configured CLI adapter and verify it before the next task.” |
The main agent keeps the acceptance criteria and final review. Micro and CLI take bounded assignments; OS retains the evidence and progress between them.
What's new in 3.0.0
The 3.0 line, prepared from 4706c38, restructures ContextOS into an exoskeleton for the full AI development lifecycle:
Precise evidence and reusable commands keep source inspection and execution results focused and recoverable.
Pipelines and verified changes connect batched execution, scoped edits, and reviewable results.
Architecture and continuity keep plans, tasks, sessions, Blocks, Chains, and receipts available across conversations and in the desktop App.
Task-appropriate delegation adds bounded API Micro assistance and isolated CLI implementation to the same OS lifecycle.
AI-led installation makes provider configuration, host plugins, CLI adapters, diagnosis, and real acceptance checks part of setup.
See the 3.0 release notes, installation guide, and release history.
If ContextOS helps your agent stay focused, give the project a star. Reproducible tasks and issue reports help us improve the next release.
Available Tools
32 toolsarchitecture_connectC
Connect two architecture Blocks with a validated Link in one simple call without crafting manual operations.
Inputs: sourceId (required), targetId (required), kind, actor, +6 more.
architecture_link_suggestA
Suggest high-confidence architectural links for an architecture Block based on AST source imports and layered conventions.
Inputs: blockId (required), projectRoot, taskContextId, includeStructured.
block_code_mutateB
Replace one already-bound AST symbol body. Not a general editor: new files, new symbols, tests, and multi-file edits should use the host editor, then source_sync and source_binding_accept.
Inputs: symbol (required), blockId (required), newCode (required), verifyCommand (required), +4 more.
block_sealA
Seal a verified Block implementation as complete. Requires valid current SourceBindings and a fresh passed direct Checkpoint; an executionId, when supplied, must be a successful receipt cited by that Checkpoint.
Inputs: blockId (required), actor, reason, executionId, +4 more.
chain_code_streamB
Extract a contract-first stream along an architectural Chain. The default returns symbols, signatures, source status, line ranges, and contracts; use mode=slice only for an explicit bounded implementation slice.
Inputs: chainId (required), mode, projectRoot, maxTotalChars, +3 more.
change_set_revertB
Create a new reverse ChangeSet for a safe, fully reversible update-only ChangeSet. Original History is preserved; stale or unsupported changes are rejected instead of partially reverted.
Inputs: changeSetId (required), task, actor, planId, +6 more.
changes_sinceB
Read only graph/checkpoint mutations after a known change sequence. Use this for live synchronization and compact read-back instead of reloading the project.
Inputs: limit, sequence, projectRoot, taskContextId, +2 more.
checkpoint_listB
List checkpoints by status, target, Plan or ChainScope, including standalone checkpoints that are not referenced by any Plan. Use this for a compact verification inbox instead of opening every entity.
Inputs: limit, locale, planId, status, +7 more.
checkpoint_recordC
Create or update a checkpoint with evidence. Passed checkpoints are the only basis for healthy completion states.
Inputs: title (required), status (required), targetId (required), targetType (required), +19 more.
checkpoint_refresh_candidatesB
List stale checkpoints that a recorded execution receipt can refresh. Does not auto-pass checkpoints; it only maps changed bindings onto retest_required items.
Inputs: executionId, projectRoot, taskContextId, includeStructured.
context_for_taskB
Get a budgeted Markdown context pack for the current development task. Use at task start and expand only selected refs.
Inputs: task (required), locale, maxChars, focusRefs, +4 more.
decision_listA
Read the compact project-scoped Decision index. Bodies, rationale, alternatives, and consequences are omitted; use decision_open or entity_open(type=decision) for one record.
Inputs: locale, projectRoot, taskContextId, includeStructured.
decision_openB
Open one architecture Decision. Returns its rationale, alternatives, consequences, scope, supersession, and compact History.
Inputs: id (required), locale, projectRoot, historyLimit, +2 more.
entity_openC
Open one Block, Chain, Link, Plan, or Decision with only relevant details and recent History.
Inputs: id (required), type (required), locale, projectRoot, +3 more.
foundation_plan_createA
Generate one Foundation Plan from every non-deprecated unimplemented Block. Because this is an explicit implementation/verification Plan, the operation creates missing atomic Block checkpoints, direct Block PlanChanges, dependency-ordered parallel steps, Chain integration gates, and a final Plan acceptance gate in one transaction; plain architecture-only create_block does not.
Inputs: id, goal, actor, title, +6 more.
graph_flowB
Declare architectural flows and pipelines using natural arrow expressions like 'block:A -> block:B -> block:C' or 'A -[calls]-> B'. Automatically creates or updates links without complex JSON crafting.
Inputs: flow (required), actor, reason, projectRoot, +2 more.
graph_mutateB
Atomically create or patch Blocks, project-scoped Decisions, global Links, Chain paths, independent Plans, atomic Checkpoints, Background scopes, Decision scopes, and source refs. Decisions are not Canvas Blocks and never enter Block/Chain/Plan coverage. A plain create_block records architecture only; use create_checkpoint in the same ChangeSet when a requirement, Plan, Chain gate, or explicit verification request makes the check necessary. Link kinds are flows_to, calls, reads, writes, depends_on, implements, validates, constrains, and supersedes. Keep each call small and provide expectedRevision for updates.
Inputs: reason (required), operations (required), task, actor, +6 more.
graph_patchA
Apply a compact mdflow/1 Markdown-like patch. The server expands it into the same atomic ChangeSet used by graph_mutate, preserves omitted fields, and can create an atomic Block checkpoint with checkpoint=auto.
Inputs: patch (required), task, actor, planId, +6 more.
graph_searchB
Search graph entities and source paths without loading the entire project.
Inputs: query (required), kinds, limit, locale, +4 more.
graph_statusC
Inspect project architecture health, live drift detection, isolated blocks, ghost blocks with code, and pending verification gates.
Inputs: locale, projectRoot, taskContextId, includeStructured.
graph_validateC
Validate global graph references, Chain paths, Plan targets, Background scopes, contracts, and checkpoint-backed completion.
Inputs: projectRoot, taskContextId, includeStructured.
log_sanitizeA
Sanitize build, test, or terminal command outputs. Strips ANSI noise, collapses routine compiler stdout, and isolates actionable failure stack traces to protect context window from token flooding.
Inputs: rawOutput (required), exitCode, maxChars, projectRoot, +2 more.
plan_contextA
Read one Plan as a compact hierarchical development document: overview, ordered ChainScopes, inline Block/Link/Chain changes, checkpoint gates, and exact source refs. This is the primary read before implementing a Plan.
Inputs: id (required), locale, maxChars, projectRoot, +2 more.
project_mapA
Read a compact project map with architecture coverage, ordered Plans, Chain paths, explicit integration gates, and source-sync status without loading entity bodies.
Inputs: locale, projectRoot, taskContextId, includeStructured.
project_registerA
Register an existing directory as an mdflow project. This creates only .mdflow/project.json and is idempotent when the descriptor already exists.
Inputs: projectRoot (required), id, name, includeStructured.
run_commandB
Run one project-local command and return only a redacted, compressed terminal summary. Raw stdout/stderr never enters the MCP response; use this gateway for tests, builds, and mutation verification.
Inputs: command (required), cwd, maxChars, timeoutMs, +4 more.
source_binding_acceptB
Persist explicitly selected AST source binding candidates for a Block. Every candidate is re-resolved against current source before a SourceRef is created.
Inputs: blockId (required), bindings (required), actor, reason, +3 more.
source_binding_suggestA
Suggest source bindings for a Block from AST symbols and project semantics. Suggestions are read-only; use source_binding_accept to persist an explicitly chosen candidate.
Inputs: blockId (required), limit, maxFiles, projectRoot, +2 more.
source_syncB
Scan current files for bound symbols without loading source into the response. Reports moved, changed, missing, or ambiguous bindings and affected Blocks/Chains.
Inputs: projectRoot, sinceRevision, taskContextId, includeUnchanged, +1 more.
step_advanceA
Advance the active step of a Plan to complete, automatically updating progress and pointing nowDoing to the next step.
Inputs: planId, status, stepId, summary, +4 more.
timeline_syncC
Synchronize development cursor and active focus across conversations. Updates nowDoing, nextUp, and active step in the timeline.
Inputs: nextUp, planId, stepId, nowDoing, +5 more.
timeline_viewA
Read the unified project Timeline: execution phases, ordered plans (P0 > P1 > P2), and current active cursor (nowDoing, nextUp, lastFinished).
Inputs: projectRoot, taskContextId, includeStructured.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools have clearly distinct purposes, with detailed descriptions preventing major confusion. Minor overlaps exist between graph_mutate and graph_patch, and between entity_open and decision_open, but the descriptions clarify their scopes. Overall, an agent can reliably select the right tool for most operations.
All tool names follow a consistent verb_noun snake_case pattern (e.g., decision_open, source_binding_accept, checkpoint_list). Even multi-word names like checkpoint_refresh_candidates maintain the pattern, providing predictable and readable tool names throughout.
With 32 tools, the server exceeds the 25-tool threshold for 'too many'. While the domain (architecture decision management, graph manipulation, checkpoints, plans) is complex and may justify a larger surface, the sheer number can overwhelm agents and increase selection overhead. The count feels heavy for the apparent scope.
The tool surface is extensive, covering project registration, decision management, graph creation/validation, source binding, checkpoints, plans, timelines, and synchronization. It appears to provide full lifecycle coverage for architecture decisions and associated artifacts. Minor gaps exist, such as explicit entity deletion (only revert via change_set_revert), but these are workable.
Maintenance
Related MCP Connectors
Shared project memory that keeps teammates and AI agents aligned across sessions.
Project memory, documentation and controlled secret access for AI coding agents.
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Per-project memory for AI agents: decisions, attempts, tasks, ranked recall. Paid per call via x402.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides durable project context for coding agents, including project maps, session history, and explicit memories, all stored locally.143 npm7MIT
- AlicenseNot gradedqualityDmaintenanceGives AI assistants persistent, queryable project memory for decisions, patterns, and rules, reducing the need to re-explain context in every prompt.11Apache 2.0
- AlicenseNot gradedqualityDmaintenanceGives AI agents durable project memory via the Model Context Protocol, allowing them to read tasks, record decisions, search context, and sync snapshots to the cloud.12 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to maintain and query project memory independently of the underlying model, with versioned, auditable storage and multi-stage retrieval through a single MCP gateway.MIT