noteflow-mcp

MCP (Model Context Protocol) server for Noteflow — gives any MCP-compatible AI agent access to your notes, projects, tasks, and shared agent memory.

What is Noteflow MCP?

Noteflow MCP bridges your AI coding assistants (Claude, Codex, Cursor, etc.) to your Noteflow workspace.

Every agent that touches your codebase reads from and writes to the same decision history. When one agent's context window runs out and another takes over, it reads what came before — and continues without losing track.

Agent A works → writes memory commit (what, why, which files, which decisions)
Agent B starts → reads memory commits → knows exactly where things stand

Installation

npm install -g noteflow-mcp

1. Authenticate

Get your token from noteflow.app → Settings → API.

noteflow setup

This writes the MCP config for all detected AI clients on your machine:

| Client | Config location | |---|---| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Code CLI | ~/.claude.json | | Codex CLI | ~/.codex/config.toml | | Cursor | ~/.cursor/mcp.json | | VS Code Copilot | ~/Library/Application Support/Code/User/settings.json |

2. Link your repo

cd your-repo
noteflow init

This:

• Links the repo to a Noteflow project (creates .noteflow/project.json)
• Registers the workspace in ~/.noteflow/workspaces.json
• Creates AGENTS.md — full agent instructions for this repo
• Creates CLAUDE.md — Noteflow quick-reference for Claude Code

Restart your AI clients after noteflow setup. Run noteflow init in each repo you want to track.

MCP Tools

noteflow_get_current_project_context

Call this at the start of every session. Returns the linked project plus the last 5 memory commits so the agent knows where things stand before touching anything.

// input (all optional)
{ "workspacePath": "/absolute/path/to/repo" }

// output
{
  "projectId": "abc123",
  "name": "my-project",
  "workspaceRoot": "/Users/me/my-project",
  "recentMemoryCommits": [
    {
      "id": "...",
      "title": "Add SafetyValidator before hardware write",
      "decisions": ["Use allow-list approach"],
      "codeEvolution": { "shortStat": "3 files changed, +42 -5", "changedFiles": [...] }
    }
  ],
  "instruction": "Read recentMemoryCommits before making architectural decisions."
}

noteflow_list_memory_commits

Lists recent memory commits. Call before starting significant work to review past decisions.

// input
{
  "projectId": "optional-if-binding-found",
  "limit": 20   // 1–50, default 20
}

Returns full commit data including decisions, reasons, and codeEvolution summary fields.

noteflow_get_memory_commit

Fetch the full detail of a single memory commit — including diffStoragePath for the raw git diff.

// input
{
  "commitId": "abc123",
  "projectId": "optional"
}

noteflow_create_memory_commit

Records a structured memory commit. Call this after completing any meaningful task or architectural decision.

// input
{
  "title": "Add SafetyValidator before hardware write",
  "summary": "Invalid joint commands were reaching the bridge without validation. Added an allow-list validator.",
  "decisions": ["Use allow-list approach over regex"],
  "reasons": ["Simpler to audit, lower false-negative risk"],
  "affectedFiles": ["src/bridge/validator.ts", "src/bridge/index.ts"],
  "tags": ["safety", "breaking-change"],
  "status": "approved",
  "agentName": "Claude",
  "codeEvolutionSummary": {
    "beforeSummary": "Commands passed directly to hardware bridge without validation",
    "afterSummary": "All commands go through SafetyValidator allow-list before reaching bridge",
    "behaviorChange": "Invalid joint commands now throw SafetyError instead of silently executing",
    "changedSymbols": ["SafetyValidator", "HardwareBridge.send", "SafetyError"],
    "workingTreeStatus": "staged"
  }
}

Field reference

| Field | Required | Description | |---|---|---| | title | ✅ | Imperative, max 200 chars. What was done. | | summary | ✅ | Why. Context. What problem was solved. | | agentName | ✅ | Your name: "Claude", "Codex", "Cursor". Shown in the UI. | | decisions | — | Key choices made. Include rejected alternatives. | | reasons | — | Why these decisions. Constraints, tradeoffs. | | affectedFiles | — | Exact paths of changed files. | | relatedCommands | — | CLI commands relevant to this change. | | tags | — | Free-form. Helps future search. | | status | — | "approved" (default) or "proposed". | | codeEvolutionSummary | — | Human-readable before/after explanation. See below. |

codeEvolutionSummary fields

| Field | Description | |---|---| | beforeSummary | What the code did before this change | | afterSummary | What it does after | | diffSummary | Short technical summary of the diff | | behaviorChange | What observable behavior changed | | changedSymbols | Function/class/interface names that changed | | workingTreeStatus | clean / unstaged / staged / mixed |

Note: codeEvolution (git metadata) is captured automatically — branch, HEAD sha, changed files, and the full diff uploaded to storage. You don't need to fill this. codeEvolutionSummary is the human explanation layer on top.

CLI

noteflow capture

Capture the current working tree diff as a memory commit — without waiting for a git commit.

noteflow capture --title "Try local resolver fallback"

Useful for capturing intermediate states while an agent is working. The diff is sanitized (.env, dist/, .key files excluded, secrets redacted) and uploaded to storage.

Capturing git diff...
Summary (optional, press Enter to skip): Testing fallback to global registry
Uploading diff...
✓ Code evolution captured: Try local resolver fallback

Commits created via noteflow capture are tagged source: "you" and shown with a 👤 badge in the UI. Agent-created commits show 🤖 Claude (or whichever agentName was set).

Diff capture & safety

What is always captured

Every memory commit (via MCP tool or CLI) always records:

• branch, headSha, shortStat, changedFiles — lightweight git metadata
• workingTreeStatus — clean / unstaged / staged / mixed

This has no privacy risk — no file content is stored.

Raw diff upload (opt-in)

Uploading the raw diff to Firebase Storage is off by default.

To enable for the MCP tool, set:

NOTEFLOW_DIFF_UPLOAD=1

When enabled, the server:

• Runs git diff + git diff --cached in the workspace root
• Excludes node_modules/, dist/, build/, .env*, *.pem, *.key
• Redacts secret patterns: API_KEY, TOKEN, SECRET, PASSWORD, PRIVATE_KEY
• Truncates at 300 KB (sets diffTruncated: true if hit)
• Uploads the sanitized diff to Firebase Storage
• Sets diffUploadError: true if upload fails (does not block the commit)

noteflow capture always uploads the diff — that is its explicit purpose.

Project binding

noteflow init writes .noteflow/project.json to the repo root:

{
  "projectId": "abc123",
  "name": "my-project",
  "workspaceRoot": ".",
  "createdAt": "2026-05-27T..."
}

The MCP server resolves the binding by walking up from cwd looking for this file, then falls back to ~/.noteflow/workspaces.json (the global registry of all linked workspaces).

Requirements

• Node.js ≥ 18
• A Noteflow account
• Token from Settings → API

License

MIT