neuroflow-mcp

NeuroFlow MCP

NeuroFlow is an open source, local-first MCP server for organization and execution. It helps a user move through one goal at a time with small, explicit, sequential actions.

Current stage: MVP in validation. Functional prototype.

NeuroFlow is designed to reduce cognitive load. The first configurable profile is autism. This profile is a starting interaction style. It does not represent every autistic person. NeuroFlow does not diagnose, provide therapy, provide treatment, promise clinical benefit, or replace medical or professional support.

What Is NeuroFlow?

NeuroFlow is a local-first execution tool for MCP hosts. A host model or user supplies a goal and ordered microtasks. NeuroFlow saves the goal locally, shows the current step, advances progress one step at a time, and supports safe switching, canceling, restoring, and resuming.

What It Is Not

NeuroFlow is not:

• a local or remote LLM
• a model installer
• a chat application
• therapy
• diagnosis
• medical or psychological guidance

What Problem Does It Try To Solve?

Many productivity tools assume a user wants broad plans, many suggestions, and constant context switching. NeuroFlow focuses on the opposite:

• one clear goal
• one clear current action
• visible progress
• exact resume behavior
• explicit recovery when something changes

Who Was It Initially Designed For?

The first configurable profile was designed around reported needs from some autistic users who prefer lower cognitive load, literal wording, explicit next steps, and stable navigation.

This does not mean the profile fits every autistic person, and it does not exclude use by anyone else.

Three Main Features

• Structured goal creation from short microtasks.
• One-step-at-a-time execution with exact resume behavior.
• Local progress memory with SQLite.

How It Works

• A host or user creates a goal with ordered microtasks.
• NeuroFlow activates exactly one step.
• The user checks the current step.
• The user completes the current step.
• NeuroFlow advances once and saves progress locally.
• The user can switch goals, return to the previous goal, cancel a goal, restore a goal, archive a goal, or resume later.

Installation

Using npx:

npx -y neuroflow-mcp doctor

Using pip:

python -m pip install neuroflow-mcp
neuroflow-mcp doctor

Using editable install for development:

python -m venv .venv
.venv\Scripts\activate
python -m pip install -e .[dev]
neuroflow-mcp doctor

Interactive terminal host with fixed menu:

neuroflow-mcp host

Configure An MCP Client

Generic stdio MCP configuration:

{
  "mcpServers": {
    "neuroflow": {
      "command": "npx",
      "args": ["-y", "neuroflow-mcp", "serve"]
    }
  }
}

Alternative Python module form:

{
  "command": "python",
  "args": ["-m", "neuroflow_mcp", "serve"]
}

See docs/quickstart.md for a first-run walkthrough and docs/clients.md for ready-to-use examples for Codex, Claude Code, Copilot or VS Code, Devin, and OpenClaw. Release publication status is tracked in docs/release-readiness.md. If your MCP client does not keep the menu visible, you can use neuroflow-mcp host as a local terminal host that renders menu.options as a persistent UI.

Public Demo

Run the deterministic public demo:

python examples/demo_flow.py

Generate versionable showcase assets:

python media/generate_showcase.py

See docs/showcase.md, media/DEMO_SCRIPT.md, media/SHOT_LIST.md, and media/RECORDING_GUIDE.md. For a final public demo pass, also use media/VIDEO_CHECKLIST.md and media/VIDEO_PROMPT.md.

Goal Lifecycle

NeuroFlow currently supports:

• active goals
• completed goals
• cancelled goals
• archived goals
• restore from cancelled or archived
• return to the previously selected goal

Canceling a goal does not delete its saved tasks or progress.

Manual permanent deletion is separate:

neuroflow-mcp goals delete <goal-id> --yes

See docs/faq.md for goal-management details.

Data Storage

NeuroFlow stores local data in:

• NEUROFLOW_HOME when set
• otherwise the platform user data directory

The default SQLite database file is neuroflow.db.

Stored local data includes:

• goals
• tasks
• progress
• profile settings
• navigation state

No backend account is required. No telemetry is enabled by default.

Tool Overview

Core tools:

• create_goal
• get_current_step
• complete_step
• resume_goal

Guided navigation tools:

• show_menu
• list_goals
• select_goal
• show_goal
• cancel_goal
• archive_goal
• restore_goal
• return_to_previous_goal
• confirm_action
• cancel_action
• go_back
• create_goal_from_title

Automatic Task Decomposition

NeuroFlow can create microtasks automatically from only a goal title.

• MCP tool: create_goal_from_title
• Terminal host: option Criar meta now asks only for the goal title and optional description
• Default behavior: use a deterministic local decomposition with no model dependency

Security Model

NeuroFlow MCP applies centralized protection to tool inputs and outputs.

• functional server messages are returned in pt-BR
• explicit prompt-injection attempts are blocked before domain execution
• internal configuration, secrets, stack traces, and absolute paths are sanitized
• outputs are minimized to the fields needed by the tool contract

NeuroFlow protects its own MCP contracts, but it does not fully control any extra natural-language text produced later by an external MCP client or LLM.

CLI Commands

neuroflow-mcp serve
neuroflow-mcp doctor
neuroflow-mcp host
neuroflow-mcp config show
neuroflow-mcp config set show_goal false
neuroflow-mcp goals list
neuroflow-mcp goals delete <goal-id> --yes

Testing

python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m mypy src tests
python -m build

Documentation

• docs/quickstart.md
• docs/architecture.md
• docs/autism-profile.md
• docs/faq.md
• docs/limitations.md
• docs/roadmap.md
• docs/showcase.md

Limitations

NeuroFlow is still an MVP in validation.

Current limitations include:

• no hosted sync
• no web or mobile app
• no authentication
• no notifications
• no collaboration features
• no medical claims or validation

See docs/limitations.md for more detail.

Contributing

See CONTRIBUTING.md. Feedback from autistic users, accessibility-minded contributors, and MCP integrators is especially welcome.

License

MIT. See LICENSE.