Granoflow MCP Server

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.

Granoflow's local features are free to use forever. If privacy is your concern, do not subscribe: without membership, your data never leaves your device or gets uploaded to the cloud.

Learn more at granoflow.com.

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.

Requirements

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

The default Granoflow API URL is:

http://127.0.0.1:56789

You can override it with:

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:

~/.config/granoflow-mcp/config.json

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

For a non-default port, ask the agent to preview granoflow_setup_write_config with apiPort, 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. If GRANOFLOW_API_BASE_URL is set, it intentionally overrides this file; setup reports configuration_shadowed_by_env instead of pretending the saved value is active.

The same MCP-owned file may store non-secret Agent defaults. Use granoflow_agent_preferences_write_defaults to preview or update them and granoflow_agent_preferences_get to 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 the agent_preferences section of their App-owned project_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.

Install

npm install -g @granoflow/mcp-server

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

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

Agents can also reuse the bundled Granoflow Agent Workflow skill for 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 bundled Granoflow Daily Review skill, which uses display, confirmation, and write/readback phases.

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

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

For one context-aware task entrypoint, use the bundled Granoflow Task Orchestrator. Plain language or gf selects quick capture, context enrichment, Analysis, Planning, safe local execution, or completion audit. Optional shortcuts are gf记/gf+, gf析/gf?, gf规/gf>, gf做/gf!, and gf完/gf.. User-facing status uses A, P, and D for Analysis, Plan, and Delivery while attachments keep their canonical metadata and filenames.

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

Workflow Examples

After installing Granoflow MCP, ask your agent:

Initialize Granoflow

Granoflow will check the connection, show only the names and plain-language functions of recommended AI capabilities, and offer to install all of them. You can then ask it to import data from Cursor, Codex, Hermes, or other agents.

To define a software project after MCP is ready, ask (not the same as Initialize Granoflow):

Initialize this project

or:

定义这个项目

Project Definition fills Project Work from your sources, locks stack capability and skill routing, delivers a Design Baseline with Design Tokens and landscape/portrait App Shell under contract fidelity, then hands off to milestone/task skills.

Then ask:

Process today's tasks

Granoflow will analyze and process the matching tasks in Granoflow.

During a task, Granoflow can ask for your approval or missing information by adding a request to the task and notifying you when available.

Ask your agent:

Create a task from this requirement

Granoflow will capture the requirement as a task and place it in the right project, milestone, or inbox.

Ask your agent:

Analyze the first task

Granoflow will prefill the Analysis state of one adaptive Task Work Document, show unresolved decisions with AI recommendations, and add Planning only when the task needs it.

More workflows will be added to this catalog as the Granoflow MCP workflow layer grows.

Long-Term Work Memory