All plugins

mflow

Manage mFlow (m-flow.io) from Hermes: boards and tasks, Knowledge Base/ADRs, and coding-agent delegation. Portable Agent Plugins v1 package (mcp.json + skills/) with no Python and nothing runs locally — it points Hermes at the hosted mFlow MCP server (Streamable HTTP at https://mcp.m-flow.io/mcp) and ships a skill that teaches Hermes how to use it (list_standalone_projects/tasks, create/update, create_comments, knowledge docs incl. ADRs, assign_to_coding_agent). Disclosure — network calls go to mcp.m-flow.io (mFlow's hosted MCP server); the plugin sends whatever board/task/KB data the user asks the agent to read or write, and coding-agent requests send the user's task text and, optionally, a public repo URL to mFlow's sandboxes. One auth path is OAuth (Google sign-in, access tokens last 90 days, re-auth every 90 days); the other is a future mFlow PAT via MFLOW_TOKEN (not yet shipped server-side — OAuth is the working path today). No telemetry, no shell commands, nothing stored or run on the host.

vladyslavpatrickToolsv0.1.0Updated 2 hours ago

About

Manage mFlow (m-flow.io) from Hermes: boards and tasks, Knowledge Base/ADRs, and coding-agent delegation. Portable Agent Plugins v1 package (mcp.json + skills/) with no Python and nothing runs locally — it points Hermes at the hosted mFlow MCP server (Streamable HTTP at https://mcp.m-flow.io/mcp) and ships a skill that teaches Hermes how to use it (list_standalone_projects/tasks, create/update, create_comments, knowledge docs incl. ADRs, assign_to_coding_agent). Disclosure — network calls go to mcp.m-flow.io (mFlow's hosted MCP server); the plugin sends whatever board/task/KB data the user asks the agent to read or write, and coding-agent requests send the user's task text and, optionally, a public repo URL to mFlow's sandboxes. One auth path is OAuth (Google sign-in, access tokens last 90 days, re-auth every 90 days); the other is a future mFlow PAT via MFLOW_TOKEN (not yet shipped server-side — OAuth is the working path today). No telemetry, no shell commands, nothing stored or run on the host.

mFlow for Hermes Agent

Use mFlow from Nous Research's Hermes Agent: manage
mFlow boards and tasks, read/write the Knowledge Base (including ADRs), and
delegate coding work to mFlow's coding agent.

This is a portable Agent Plugins v1 package. It contains no NestJS/NATS
code — it points Hermes at the hosted mFlow MCP server
(https://mcp.m-flow.io/mcp) and ships a skill that teaches Hermes how to use
it.

Repository layout

plugin.json
mcp.json
skills/mflow/SKILL.md
skills/mflow/references/recipes.md
skills/mflow/references/tools.md
examples/config.oauth.yaml
README.md
LICENSE

plugin.json must remain at the repo root so
hermes plugins install owner/repo works.

Install

hermes plugins install vladyslavpatrick/mflow-hermes --enable

Portable plugins are disabled by default unless installed with --enable. If
you installed without it:

hermes plugins enable mflow

Then choose an authentication method below.

Authentication

Option A — OAuth (works today)

Portable packages cannot declare auth: oauth in mcp.json, so OAuth uses a
same-named native entry in ~/.hermes/config.yaml. Native config
overrides the package's server entry.

Add this to ~/.hermes/config.yaml (see
examples/config.oauth.yaml):

mcp_servers:
  mflow:
    url: "https://mcp.m-flow.io/mcp"
    auth: oauth
    timeout: 120
    # tools: { exclude: ["delete_*", "transfer_knowledge_base"] }   # optional
    # trust: untrusted   # optional: approve every write

Then authenticate once:

hermes mcp login mflow

mFlow OAuth is authorization_code + PKCE with a Google sign-in consent page.
Access tokens last 90 days and there is no refresh grant yet, so
re-run hermes mcp login mflow every 90 days. For headless boxes, follow the
Hermes "OAuth over SSH" guide.

Option B — MFLOW_TOKEN (for headless Hermes: gateway/cron/VPS)

Once mFlow Personal Access Tokens (PATs) are available, put a PAT in Hermes'
env file and the bundled mcp.json works with zero native config:

# ~/.hermes/.env
MFLOW_TOKEN=mf_pat_xxxxxxxxxxxxxxxx

${MFLOW_TOKEN} in mcp.json headers is interpolated from the user's env or
~/.hermes/.env. If it is unset, Hermes fails closed and names the variable.

| Variable | Required | Description |
| --- | --- | --- |
| MFLOW_TOKEN | Only for Option B | mFlow Personal Access Token used as a Bearer token. Never commit it. |

Status: PAT creation/listing/revocation and mcp-server PAT verification
are backend work in the mFlow monorepo. Until it ships, use Option A.

Verify

# Confirm the mflow server is registered
hermes mcp list

# In an interactive session, reload MCP servers
/reload-mcp

# Smoke test
hermes chat -q "List my mFlow projects"

You can also ask Hermes to use the skill explicitly:

Use the mflow skill to list my mFlow projects and their task counts.

What the skill covers

  • Orientation: list_standalone_projects → get_standalone_project.
    mFlow APIs need ids, not names; custom columns have UUID ids.
  • Tasks: get_standalone_task_by_key, list_standalone_tasks,
    create_standalone_tasks (max 50 per call, nesting via
    localRef/parentRef, all-or-nothing validation),
    update_standalone_task (labelIds is a full replace),
    create_standalone_comment.
  • Knowledge Base: list_knowledge_docs (project id or "__global__";
    types convention|workflow|metric|guide|adr), list before create, use
    update_knowledge_doc to avoid duplicates. ADRs must have
    ## Context, ## Decision, ## Consequences; keep proposed until the
    user confirms accepted; never delete accepted ADRs — supersede them
    (adrStatus: superseded, supersededBy).
  • Coding agent: assign_to_coding_agent (taskKey/taskId, tier
    light 2GB/1CPU | mid default | heavy 7GB/4CPU, repoUrl,
    noRepoOutput zip|new_repo, extraPrompt, aiProvider) returns
    immediately; poll get_coding_agent_status (not in a tight loop;
    queuePosition while queued).
  • Semantic search: ask_mflow only as a last resort — slow, may change
    data, and is currently the only semantic search.
  • Pitfalls: 401 → re-auth; confirm before delete_* /
    transfer_knowledge_base mode: move.

See skills/mflow/SKILL.md,
skills/mflow/references/tools.md, and
skills/mflow/references/recipes.md.

Troubleshooting

| Symptom | Fix |
| --- | --- |
| 401 / auth error on any mFlow tool | Re-authenticate: hermes mcp login mflow (OAuth tokens expire after 90 days) |
| Error naming ${MFLOW_TOKEN} / missing env var | Set MFLOW_TOKEN in ~/.hermes/.env, or add the native OAuth entry from Option A |
| conflicts with native config; skipping warning | Expected when you use the OAuth override — native config intentionally overrides the package's mcp.json server entry |
| Coding agent stuck in queued | Sandboxes are busy; wait and poll again later (not in a tight loop) |
| noRepoOutput: new_repo fails | GitHub must be connected for the coding agent to create/push a repo |
| Tool not found / search_knowledge missing | A dedicated semantic-search MCP tool is not shipped yet; use ask_mflow as a fallback |

Known gaps

  • A dedicated search_knowledge MCP tool is not available yet; semantic
    search goes through ask_mflow.
  • PAT-based auth (MFLOW_TOKEN) depends on mFlow backend work; OAuth is the
    working path today.

License

MIT — see LICENSE.

README from the reviewed commit 9e6428e; it updates when the author re-pins.