Granoflow

Granoflow is a local-first app for planning work, reviewing completed tasks, and turning durable lessons into review cards. Granoflow MCP connects MCP-capable AI agents to a local task, review, and long-term work memory layer.

MCP server for Granoflow: exposes the Granoflow Local HTTP API as tools for AI agents and IDEs that need to track task work, finish tasks with meaningful reviews, and preserve reusable lessons as memory cards.

This is not a code analyzer, CI fixer, or repository automation framework. If your only goal is to make an AI coding agent write better code, use tests, linters, CI, prompts, and code-analysis tools directly. Granoflow MCP is for the surrounding agent workflow: what task the agent is doing, what happened, what should be remembered, and what deserves review later.

Granoflow MCP can support any agent-assisted work, but it is especially useful for software projects. If you are not a programmer, or if you have not used AI coding agents before, Granoflow helps you benefit from the experience AI builds while it works. You can read, understand, and learn from those records so AI work is no longer a black box, or ignore them and let future agents search the same durable experience tomorrow, next month, or next year. That way your agent can continue past work instead of inventing a fresh plan every time and fragmenting the project into disconnected attempts, without replacing tests, linters, or engineering judgment.

This server is intentionally thin. It does not own Granoflow business logic, database access, app orchestration, or release workflows. It resolves a local API endpoint, forwards structured requests to the running Granoflow app, and returns predictable MCP tool results.

Granoflow App owns task and work-memory truth. Granoflow MCP is the control-plane protocol surface. The host Agent/runtime owns traversal, Skill/provider routing, and execution handoff; repository, browser, image, video, and other tools perform the actual work. A user instruction to implement the active Task Work Document authorizes the host, not the MCP server, to enter the execution plane.

External Skill routing is host-owned and capability-based. For a relevant Skill, the host may call it only when current metadata permits model invocation; user-only Skills are suggested for explicit user invocation. When a Skill is missing, the host shows a verified source, actual installation scope, and verified command before asking for installation approval, then waits without assuming refusal. Refusal, installation, rediscovery, reload, or invocation failure uses a documented model capability fallback. Granoflow MCP does not scan or modify the host's global Skill environment and does not treat Skill invocation as authorization to implement, commit, publish, or perform another gated action.

- Node.js 20 or newer.
- A running Granoflow app with the Local HTTP API enabled.

export GRANOFLOW_API_BASE_URL="http://127.0.0.1:56789" export GRANOFLOW_API_TOKEN="..."

The MCP server can keep non-secret local connection defaults in:

SetGRANOFLOW_MCP_CONFIG_PATHto use a different config path for tests, temporary setups, or advanced local installs. API tokens are not stored in this file; keepGRANOFLOW_API_TOKENin the MCP client environment.

For a non-default port, ask the agent to previewgranoflow_setup_write_configwithapiPort, review the candidate evidence, path, old/new value, and environment override status, then confirm that exact write once. The server rereads and verifies the config immediately. A saved value is reused on later requests without asking again. IfGRANOFLOW_API_BASE_URLis set, it intentionally overrides this file; setup reportsconfiguration_shadowed_by_envinstead of pretending the saved value is active.

The same MCP-owned file may store non-secret Agent defaults. Usegranoflow_agent_preferences_write_defaultsto preview or update them andgranoflow_agent_preferences_getto resolve a project's effective values:

{ "agentPreferences": { "audience": "beginner", "explanation": "detailed", "executionMode": "interactive", "git": { "missingNotice": "once", "workflow": "current_branch", "checkpoint": { "enabled": false } } } }

Projects can override individual values in theagent_preferencessection of their App-ownedproject_rules.yaml. Project values win field by field; local defaults and then newcomer-safe defaults fill the gaps. Missing Git produces at most one short newcomer notice by default and never forces an installation choice.

When checkpoint is enabled, the host Agent may create a local commit only after the current Task Work explicitly authorizes it, all required tests and project gates pass, staged content contains only task-owned files, secret and hook checks pass, and commit SHA/readback succeeds. Preferences never authorize push, publish, deploy, deletion, login, secrets, branch creation, or history changes.

For a user-facing setup walkthrough, seeGranoflow MCP User Install And Demo Guide.

For maintainers, seeGranoflow MCP Release Checklist. For one-command release with develop/main回流、推送与npm发布并返回开发分支，请使用npm run release:platforms。

Agents can also reuse the bundledGranoflow Agent Workflow skillfor task completion, weekly/monthly review drafting, review-card drafting, long-term work memory retrieval, and user-feedback handling conventions. For an explicit daily review, use the bundledGranoflow Daily Review skill, which uses display, confirmation, and write/readback phases.

Agents can use the bundledGranoflow First-Run Import skillto initialize the connection, offer all recommended AI capability collections, and optionally import data from Cursor, Codex, Hermes, or other agents.

To define or initialize asoftware project(Project Work, Design Baseline with tokens, and App Shell)—not MCP connection setup—use the bundledGranoflow Project Definition skill. AskInitialize this project/Define this project/初始化这个项目/定义这个项目. This is distinct fromInitialize Granoflow.

For one context-aware task entrypoint, use the bundledGranoflow Task Orchestrator. Plain language orgfselects quick capture, context enrichment, Analysis, Planning, safe local execution, or completion audit. Optional shortcuts aregf记/gf+,gf析/gf?,gf规/gf>,gf做/gf!, andgf完/gf.. User-facing status usesA,P, andDfor Analysis, Plan, and Delivery while attachments keep their canonical metadata and filenames.

After Project Definition, useGranoflow Portfolio Orchestratorto create all milestones then quality-author each milestone's tasks (description batch size 1). Component Skills:Milestone Workflow(create milestones),Task Authoring(create tasks), andMilestone Coordination(charter / integrate / close). Single-task lifecycle remainsTask Orchestrator/ Agent Workflow. For unattended suite runs until green, useIntegration Test Campaign(service_path / cross-module real I/O; one milestone per round; not task-local write-only IT), thenE2E Test Campaign(final stage: Project Work user-flow coverage, author missing UI journeys, auto-fix bugs, screenshots undertemp/shown to the user).

npx -y @granoflow/mcp-server gfmcp-runner --dry-run --once

npx -y @granoflow/mcp-server gfmcp-runner --workspace /absolute/project/path

granoflow-gfmcp-runner --status granoflow-gfmcp-runner --stop

Thread execution has three user-facing modes. If the user says nothing, the agent uses the default interactive mode. Explicitunattendedmode requires the thread to report its mode and declare responsible node lanes, allowed actions, stop conditions, and handoff; ordinary confirmation nodes are skipped, but real external-action boundaries remain. Explicitlayered_handoffmode assigns versioned capability prefixes to separate workers. Newbatch_v2tasks use[analysis],[plan],[dev],[test],[integration],[user], and[action]; historicallegacy_v1tasks retain[confirm]and the old[test]meaning. The prefix names a responsibility, not a model. The user or host chooses models because an agent cannot reliably identify its own model or reasoning tier.

Unattended mode has one general zero-interruption contract, not a list of prompt phrases to suppress. A bounded same-run request uses an interaction budget of zero across Analysis, Planning, implementation, repair, verification, Delivery, and completion. The agent may wait only for a proven direction change, scope drift, forbidden action, user-only input, or required subjective acceptance; before waiting it completes independent safe work and asks one batched question. Durable continuation across a later host turn still uses the confirmed delegated authorization envelope.

The persistent milestone runner supports those explicit modes with--execution-modeand repeatable--lane.[dev]prepares and statically validates integration/screenshot scripts;[test]means a later worker actually runs them. Every completed implementation produces a self-contained acceptance HTML, including when integration and screenshots arenot_required; the report then explains why and shows the alternative automated evidence.

For bounded unattended Task Work, callgranoflow_delegated_authorization_skill. It defines a confirmed, expiring envelope with separate Analysis confirmation, Planning permission, Plan confirmation, and Execution authorization grants. Hosts re-read the controller task attachment and App-owned SHA-256 receipt, then run the packaged read-only validator against current Grill, Plan, repository, path, and action facts. A matching decision may continue only its evaluated scope; expired, revoked, stale, unknown, forbidden, or drifted state fails closed into the existing visible waiting-node and reminder workflow. Skill invocation and theGFMCPtag never grant authorization.

The optionalgf做/gf!local-safe profile is also not blanket authorization. After its fixed contract has been previewed and approved, it can continue only an explicitly targeted run whose Analysis and Readiness Grills pass and whose requested actions stay inside the declared local/GF allowlist. Publish, deploy, commit, push, deletion, login, payment, secret/2FA access, external messages, approved-asset overwrite, and scope expansion always remain outside the profile.

The bundled workflow also includes due-task processing. When the user asks an agent to process today's tasks, a specific date or range, or all unfinished tasks, the agent should use a batch ledger to classify which tasks AI can do, which need user input, and which the user must do. Each selected task gets one adaptive Task Work Document; Planning is expanded only when needed, and execution still requires a separate user instruction or a current delegated execution grant. User-only blockers should be preserved as Granoflow task nodes, reminders, notification tasks, and sync visibility reports when the running app exposes the required tools.

The bundled workflow also includes lightweight requirement capture. When the user asks an agent to create a task from the requirement being discussed, the agent should place it directly into one clearly matching existing project and active milestone. Every other default placement goes straight to inbox without interrupting the user to propose or create project structure. The task keeps enough context for later analysis, then returns only a one-sentence placement confirmation.

Every task authored by an AI agent or automation follows one shared quality contract, including tasks created directly, from project or milestone work, during import, or as notification tasks. The title must name an action or observable outcome. The description must use non-programmer-friendly language and include both a real analogy and a different concrete example. Task-create tools require exactauthoringEvidenceexcerpts and fail withtask_authoring_quality_failedbefore any write when the evidence is missing or invalid. Human title-only quick capture in the App remains unchanged.

The bundled workflow also includes interactive single-task work definition. The agent prefills evidence, shows unresolved directional questions once with AI recommendations, and writes one adaptive Task Work Document after approval. Analysis and Planning remain separately confirmed semantic states inside that document; small tasks may recordplanning_status=not_required. Task Work Documents are immutable versioned task attachments. Their optional nodes have deliverable and downstream-start standards, reconcile against the latest Granoflow state before writes, and leave manual acceptance available on any synced device without blocking later safe AI work. Completing the last active node lets Granoflow's existing NodeService complete the parent task. When installed, the host Agent may usegrill-finalizerand let its Provider Registry select relevant reviewers for a local working draft. Granoflow MCP does not detect, install, or invoke that Skill. For a missing relevant finalizer or helper, the host offers one verified installation choice and waits for the user. After a temp-writinggrill-finalizerpass, the hostmustrun thegrill-meone-question pipeline before promotion (interactive: wait per question; explicit unattended: one question + recommend + auto-adopt). Standalonegrill-meoutside that pipeline may stay user-initiated. Only task-relevant gstack/provider reviewers are selected rather than an entire family. Refusal or installation, rediscovery, reload, or invocation failure is recorded before bundled Grill continues as an honest model fallback, without claiming evidence from a reviewer that did not run. Other external Skills follow the bundledexternal-skill-routingreference: the Work Document records capability decisions and Planning retains only execution-relevant choices. External methods remain subordinate to project rules and Granoflow authorization.

Granoflow MCP separates actual delivery from later reflection:
- Read or resolve the current Granoflow task.
- Perform the work in the normal coding, writing, research, or operations environment.
- Write an immutable, versioned Task Delivery and verify its content or App-owned SHA-256 readback.
- For a task with Work Document nodes, finish the final required node and let NodeService complete the parent. For a node-less compatibility task, callgranoflow_task_finishonce.
- Read backstatus=done; never call a second completion path.
- Leave deep Task Review and Review Cards for a separately initiated Deferred Task Review, unless the user explicitly requested inline review.

This makes Granoflow useful to Codex, Cursor, Claude Code, OpenCode, OpenClaw, and other MCP-capable agents as a local workflow memory layer: task state is kept in the app, completion evidence is written back to the task, and reusable knowledge can become spaced-practice cards.

Review cards are not only language-learning cards. Agents should first decide whether the knowledge is worth keeping, then classify the content naturally: language term, person, organization, place, engineering convention, security principle, or general knowledge. Professional terms introduced by the agent can become cards when they matter to future work.

The bundled workflow skill keeps Evidence, independent Experience, Knowledge assessment, and Card materialization separate. Raw Experience is not a Card type. The detailed rules decide whether a source should remain searchable, become a system-enforced control, reuse existing Knowledge, or produce one Note with active or archived-reference Cards.

{ "clientCardId": "card-idempotent", "cardType": "basic_qa", "front": "What does idempotent mean in an API or task workflow?", "back": "Repeating the operation has the same durable effect as doing it once.", "sourceSummary": "", "noteFields": [ { "key": "phonetic", "label": "Phonetic", "type": "text", "value": "/ˌaɪdəmˈpoʊtənt/" }, { "key": "pronunciation", "label": "Pronunciation", "type": "text_to_speech", "value": "idempotent", "ttsLanguageCode": "en-US" } ], "frontLayout": ["front", "pronunciation"], "backLayout": ["back", "phonetic"] }

- developis the active integration branch. It may contain unverified or unreleased changes.
- mainis the npm release branch. Publish@granoflow/mcp-serverlatest only frommain.
- Merge or fast-forwarddevelopintomainonly after release preflight passes.

npm install npm run build node dist/index.js

Verify an installed package without starting an MCP stdio session:

npx -y @granoflow/mcp-server --version npx -y @granoflow/mcp-server --help

Before publishing a release, verify the package contents:

- granoflow_setup_status
- granoflow_agent_workflow_skill
- granoflow_bundled_skill_reference
- granoflow_daily_review_skill
- granoflow_first_run_import_skill
- granoflow_gfmcp_runner_skill
- granoflow_delegated_authorization_skill
- granoflow_task_orchestrator_skill
- granoflow_milestone_workflow_skill
- granoflow_milestone_coordination_skill
- granoflow_task_authoring_skill
- granoflow_portfolio_orchestrator_skill
- granoflow_gfmcp_prepare
- granoflow_gfmcp_safe_sync
- granoflow_gfmcp_candidates
- granoflow_setup_detect_local_api
- granoflow_setup_write_config
- granoflow_setup_open_config
- granoflow_setup_open_app
- granoflow_health
- granoflow_version
- granoflow_capabilities
- granoflow_ai_agent_tools
- granoflow_evidence_list
- granoflow_evidence_search
- granoflow_evidence_get
- granoflow_evidence_authoring_preview
- granoflow_evidence_authoring_apply
- granoflow_evidence_update
- granoflow_evidence_delete
- granoflow_experience_list
- granoflow_experience_get
- granoflow_project_experiences
- granoflow_milestone_experiences
- granoflow_experience_search
- granoflow_experience_authoring_preview
- granoflow_experience_authoring_apply
- granoflow_experience_update
- granoflow_experience_delete_impact
- granoflow_experience_delete
- granoflow_experience_merge_preview
- granoflow_experience_merge_apply
- granoflow_experience_usage_link
- granoflow_experience_usage_unlink_impact
- granoflow_experience_usage_unlink
- granoflow_knowledge_assessment_list
- granoflow_knowledge_assessment_get
- granoflow_knowledge_assessment_preview
- granoflow_knowledge_assessment_apply
- granoflow_knowledge_materialization_list
- granoflow_knowledge_materialization_get
- granoflow_knowledge_materialization_preview
- granoflow_knowledge_materialization_apply
- granoflow_knowledge_control_preview
- granoflow_knowledge_control_apply
- granoflow_task_knowledge_pack
- granoflow_task_knowledge_references
- granoflow_task_knowledge_adoption_preview
- granoflow_task_knowledge_adoption_apply
- granoflow_task_knowledge_audit_preview
- granoflow_task_knowledge_audit_apply
- granoflow_task_knowledge_usage_preview
- granoflow_task_knowledge_usage_apply
- granoflow_project_knowledge_usages
- granoflow_milestone_knowledge_usages
- granoflow_context_pack
- granoflow_context_steward_status
- granoflow_project_context_update
- granoflow_milestone_context_update
- granoflow_milestone_context_archive
- granoflow_task_completion_record
- granoflow_review_card_record
- granoflow_task_list
- granoflow_task_export
- granoflow_task_validate
- granoflow_task_import
- granoflow_task_history_mutate
- granoflow_task_create
- granoflow_task_create_structured
- granoflow_task_update
- granoflow_task_update_structured
- granoflow_task_attachment_list
- granoflow_task_attachment_add_markdown
- granoflow_task_attachment_delete
- granoflow_task_node_list
- granoflow_task_node_batch_create
- granoflow_task_node_update
- granoflow_task_node_delete
- granoflow_task_complete
- granoflow_task_finish
- granoflow_task_resolve
- granoflow_project_list
- granoflow_project_resolve
- granoflow_project_create
- granoflow_project_update
- granoflow_project_delete
- granoflow_milestone_list
- granoflow_milestone_resolve
- granoflow_milestone_create
- granoflow_milestone_update
- granoflow_milestone_delete
- granoflow_review_day_show
- granoflow_api_request

Each bundled Skill tool returns its mainSKILL.mdplus areferencesmanifest. Read one manifest entry withgranoflow_bundled_skill_reference(skillId, referenceId). The supported Skill ids are:

- granoflow-agent-workflow
- granoflow-daily-review
- granoflow-first-run-import
- granoflow-review-card-draft
- granoflow-gfmcp-runner
- granoflow-delegated-authorization
- granoflow-task-orchestrator
- granoflow-milestone-workflow
- granoflow-milestone-coordination
- granoflow-task-authoring
- granoflow-portfolio-orchestrator
- granoflow-persistent-milestone-runner
- granoflow-project-definition
- granoflow-integration-test-campaign
- granoflow-e2e-test-campaign

The reference tool is package-local and read-only. It accepts no caller path, does not call the Granoflow Local HTTP API, and does not require an API token. It returns the stable Skill/reference ids, package-relative path, byte count, SHA-256, and UTF-8 Markdown content. Reads are limited to one regular.mdfile under a fixed bundledreferences/root and 256 KiB. Unknown, missing, unsafe, or oversized references fail with stableworkflow_reference_*codes. This SHA-256 identifies the packaged reference only; it is not a Granoflow App attachment hash.

Prefer the structured task, project, and milestone tools for common resource operations. The JSON payload tools remain available as escape hatches when the running app exposes newer fields before this package has first-class schemas.

Knowledge-distillation tools are thin Local HTTP API forwards. Before every call they verify the exact App resource action. An older App receives a stableunsupported_capabilityresult; the MCP server never falls back to its own eligibility, duplicate, vector, learning-budget, association, or Usage logic. Authoring remainspreview -> user approval -> apply -> App readback, with partial approval and idempotency owned by the running App.

Every milestone created throughgranoflow_milestone_createhas a deadline. An explicitdueAtis preserved. When omitted, the tool uses the strictly next local Saturday at23:59:59.000, then advances by seven-day increments until the date is later than all existing milestone deadlines in the same project.