npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@resolflow/mcp-client

v2.1.0

Published

Resolflow MCP client - stdio to HTTP bridge for AI assistants (Claude Desktop, Cursor, VS Code, Zed, Windsurf)

Readme

Resolflow MCP Client

stdio-to-HTTP bridge that allows AI assistants to connect to the Resolflow MCP server.

This package provides seamless integration between stdio-based AI clients (Claude Desktop/Code, ChatGPT Codex, VS Code/GitHub Copilot, Cursor, Gemini Antigravity) and Resolflow's HTTP-based MCP server.

What This Does

Resolflow MCP server runs over HTTP, but AI clients (Agents, Applications/Tools) like Claude Desktop expect stdin/stdout communication. This client bridges that gap:

AI Client (stdio) <---> resolflow-mcp <---> Resolflow Server (HTTPS)

Key Features:

  • ✅ Auto-discovery: Token automatically identifies your project (no project_id needed)
  • ✅ Zero configuration: Works out of the box with npx
  • ✅ Retry logic: Automatic retries on transient errors (429, 5xx, network). Tool calls are only retried on 429 or connection failures, so a retry never duplicates a write
  • ✅ Secure: Token-based authentication over HTTPS
  • ✅ Standard protocol: JSON-RPC 2.0 / MCP compliant
  • ✅ Multi-IDE support: Claude Desktop, VS Code, Cursor, Windsurf, Zed, and more

Quick Start

With npx (No installation needed)

RESOLFLOW_MCP_TOKEN=YOUR_TOKEN npx @resolflow/mcp-client

--token YOUR_TOKEN still works but prints a warning: a command-line flag is visible in the process list and shell history.

Claude Desktop Configuration

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "resolflow": {
      "command": "npx",
      "args": ["-y", "@resolflow/mcp-client"],
      "env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

Restart Claude Desktop. Resolflow tools will be automatically available.


VS Code / GitHub Copilot

Method 1: MCP Extension

  1. Press Ctrl/Cmd + Shift + P
  2. Type: MCP: Add Server
  3. Select: Command (stdio)
  4. Enter: npx @resolflow/mcp-client and set RESOLFLOW_MCP_TOKEN in the server env (or use Method 2)
  5. Name: Resolflow

Method 2: mcp.json

Add to .vscode/mcp.json:

{
  "servers": {
    "resolflow": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@resolflow/mcp-client"],
      "env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN_HERE" }
    }
  }
}

Cursor

Add to Cursor settings or .cursor/mcp.json:

{
  "mcpServers": {
    "resolflow": {
      "command": "npx",
      "args": ["-y", "@resolflow/mcp-client"],
      "env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN" }
    }
  }
}

Windsurf

  1. Press Ctrl/Cmd + , (Settings)
  2. Navigate to: Cascade → MCP servers
  3. Click: Add Server → Add custom server
  4. Paste:
{
  "mcpServers": {
    "resolflow": {
      "command": "npx",
      "args": ["-y", "@resolflow/mcp-client"],
      "env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN" }
    }
  }
}

Zed

  1. Press Cmd + , (Settings)
  2. Add:
{
  "context_servers": {
    "resolflow": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@resolflow/mcp-client"],
      "env": { "RESOLFLOW_MCP_TOKEN": "YOUR_TOKEN" }
    }
  }
}

Claude Code

claude mcp add resolflow -e RESOLFLOW_MCP_TOKEN=YOUR_TOKEN -- npx -y @resolflow/mcp-client

Then run /mcp in Claude Code to confirm the server is connected.


Other MCP-Compatible Clients

Command: npx
Arguments: -y @resolflow/mcp-client
Environment: RESOLFLOW_MCP_TOKEN=YOUR_TOKEN

Wake an agent when work arrives (watch)

Since 1.2, resolflow-mcp watch checks the queue of a token (get_my_queue: stages to work, stages to review, tasks delegated to it) and runs a command for each new item, one at a time. The item is in the environment of the command: RESOLFLOW_TASK_ID, RESOLFLOW_ITEM_KIND (work, review, deploy, suggest or rework), RESOLFLOW_DEPLOYMENT_ID (deploy items) and RESOLFLOW_ITEM (JSON).

Since 2.0, --exec does not use a shell. The command is split into words (single quotes, double quotes and backslash group words, nothing else) and started directly. $, |, ;, &&, backticks, $(...) and globs are plain text, so text from the server can never become a command. In the arguments, watch replaces only $RESOLFLOW_TASK_ID, $RESOLFLOW_DEPLOYMENT_ID (each must be a UUID) and $RESOLFLOW_ITEM_KIND (one of the kinds above); when a value is missing or malformed, the item is skipped and nothing runs. $RESOLFLOW_ITEM is never put into the command line (it contains text people wrote): read it from the environment in your program, or let the agent call get_my_queue.

Since 1.3, finished deploys come too: when a staging or production deploy of tasks the agent works (or its team works, for the lead) succeeds or fails, a deploy item arrives with the environment, outcome, run URL, the tasks and the next step (RESOLFLOW_DEPLOYMENT_ID is set). It stays until the agent calls ack_message with its message_id, or 48 hours. The project chooses which deploys are sent in Releases & deployments → Configuration.

New tasks: propose the description and todos (--kinds suggest). A team lead (orchestrator token) or a single agent (role all, no team) can watch for tasks a person just created that still need a description or todos. While it polls with --kinds suggest Resolflow counts it as watching (2 minutes); each new task arrives as a suggest item with needs (description, todos, more_todos, check_todos), the existing todos and a recommended_model_tier. The agent calls claim_suggest (first caller wins for 10 minutes, so two agents never propose and the cloud Task Planner review is skipped), reads the task, then suggest_task_details. The proposal is stored as a suggestion people accept item by item in Resolflow; it never changes the task or its todos. A lead can do it itself or hand it to a sub agent with delegate_task (kind: "suggest", model): pick a model of at least the recommended tier — Resolflow warns when it is below. Sub agents get a suggest item only when their lead delegates one. Without a watching lead or single agent the cloud review runs as before. Suggest items are opt-in: don't pass --kinds suggest and none arrive.

Reopened tasks (since 2.1). When a person reopens a finished task ("Request rework", with a reason and a stage), the agent working it gets a work item again with reopened: true, round (the how-many-th reopen), revision_todo_id and the reason in returned_reason; it works the revision todo first, then hands the stage in again. Each reopen is a new item, even at the same stage, so --exec runs once per reopen. The team lead gets a rework item until it delegates the task with delegate_task (or someone claims it); --kinds suggest includes rework, and --kinds suggest,rework says so explicitly. The reason is text a person wrote: it is in RESOLFLOW_ITEM and get_inbox (task.reopened), never in the command line. Clients before 2.1 drop rework items when --kinds suggest is set (the inbox message still arrives).

# A team lead (or a single agent) that proposes the description and todos of new tasks
# and delegates tasks a person reopened
RESOLFLOW_MCP_TOKEN=LEAD_TOKEN npx -y @resolflow/mcp-client watch --kinds suggest,rework \
  --exec 'claude -p "Làm item Resolflow $RESOLFLOW_TASK_ID: gọi get_my_queue"'

# A reviewer agent that runs Claude Code headless whenever a stage waits for its review
RESOLFLOW_MCP_TOKEN=REVIEWER_TOKEN npx -y @resolflow/mcp-client watch \
  --exec 'claude -p "Review the Resolflow task $RESOLFLOW_TASK_ID: claim_review, check the work, submit_review."'

# Wake up only when a deploy of your tasks finished
RESOLFLOW_MCP_TOKEN=YOUR_TOKEN npx -y @resolflow/mcp-client watch --kinds deploy \
  --exec 'claude -p "Deploy $RESOLFLOW_DEPLOYMENT_ID của task $RESOLFLOW_TASK_ID đã xong: gọi get_my_queue, làm next_step rồi ack_message"'

# Just print new work (and ring the terminal bell)
RESOLFLOW_MCP_TOKEN=YOUR_TOKEN npx -y @resolflow/mcp-client watch

| Option | | |---|---| | --exec <command> | Command to run per new item, without a shell (see above) | | --exec-shell <command> | 1.x behaviour: run the command through your shell. Opt-in, prints a warning on every run, cannot be combined with --exec. Required for Windows .cmd / .bat | | --interval <sec> | Seconds between checks (default 30, minimum 10) | | --skip-existing | Ignore what is already in the queue at start | | --once | Check once and exit | | --kinds <list> | Only these items: work, review, deploy, suggest, rework (comma separated). suggest is opt-in and brings rework too |

Migrating from 1.x

2.0 is a security release with breaking changes for watch and the server URL:

  1. --exec no longer runs through a shell. Pipes, ;, &&, redirects, $(...), backticks, globs and $OTHER_VARS are not interpreted any more. If you need them, put them in a script and run the script (--exec './on-item.sh', reading $RESOLFLOW_* from the environment), or switch to --exec-shell (the 1.x behaviour, with a warning on every run).
  2. $RESOLFLOW_ITEM is no longer substituted into the command line. Prompts that put the item JSON into the command line become, for example, claude -p "Làm item Resolflow $RESOLFLOW_TASK_ID: gọi get_my_queue"; the agent reads the item itself. A command that contains $RESOLFLOW_ITEM is refused at start. Other $RESOLFLOW_* names (except the three above) are refused too.
  3. Variables are checked. $RESOLFLOW_TASK_ID / $RESOLFLOW_DEPLOYMENT_ID must be UUIDs and $RESOLFLOW_ITEM_KIND a known kind, or the item is skipped.
  4. Windows: .cmd / .bat (including npm shims such as claude.cmd) need --exec-shell; cmd.exe expands %VAR%, so keep server text out of the command.
  5. http:// to a non-loopback host is refused; use https:// or add --insecure-http.
  6. --token prints a warning; move the token to RESOLFLOW_MCP_TOKEN (MCP client configs: the env block).
  7. Text from the server (titles, next steps, errors) is printed with terminal control characters and escape sequences removed.

Getting Your Token

  1. Go to resolflow.ai → Projects → Your Project
  2. Navigate to Settings → MCP Tokens
  3. Click Generate Token
  4. Copy the token

Options

RESOLFLOW_MCP_TOKEN=<token> resolflow-mcp [--url <url>]

| Option | Description | Default | |--------|-------------|---------| | --token | Authentication token (prefer RESOLFLOW_MCP_TOKEN; the flag prints a warning) | — | | --url | Server URL (also RESOLFLOW_MCP_URL). https://, or http:// to this machine (localhost, 127.x, ::1) | https://api.resolflow.ai/api/mcp | | --insecure-http | Allow http:// to another host (the token travels unencrypted) | — | | --version, -v | Print version | — | | --help, -h | Show help | — |

Environment Variables

export RESOLFLOW_MCP_TOKEN="your-token"
resolflow-mcp

Available Tools

Tools are served by the Resolflow MCP server and discovered automatically via tools/list, so new server-side tools work without upgrading this client. Current tools:

Project

  • get_project_context - Project details, guardrails and workspace info
  • list_project_documents / store_project_document - Read and store project documents

Session context (memory between sessions)

  • save_context - Save markdown notes under a key for your later sessions (scope project, task or team; 64 KB max; expires 14 days after its last use)
  • get_context, list_contexts - Pick up saved context at the start of a session
  • delete_context - Remove an entry that is no longer true

Tasks

  • list_tasks, get_task_by_id, search_tasks - Browse and look up tasks
  • create_task - Create new tasks
  • update_task - Fix a task's title, description or priority instead of creating a duplicate (lead / single agent tokens only; never status, stage, type, groups or assignee). Pass expected_updated_at (the updatedAt you read): a task changed meanwhile answers 409 with its current values. Refused while a stage waits for review and on done / cancelled tasks; every edit is kept as old → new in the history
  • get_unclaimed_tasks - Find open tasks nobody has claimed (drafts are parked by humans; pass status: "draft" to list them)
  • claim_task - Claim a task (auto-assignment, force to override)
  • cancel_task - Cancel a task with a reason. Applied right away only for an agent-created task nobody has started; otherwise a project Owner/PO/PM approves it in Resolflow
  • request_task_deletion - Ask an Owner/PO/PM to delete a task. Agents never delete directly, and tasks with completed work can't be deleted

Epics, sprints & user stories

  • create_task_group - Create an epic, sprint (with dates) or custom group
  • list_task_groups - List groups with their task counts
  • assign_task_to_groups - Move a task into or out of an epic, sprint or custom groups
  • create_user_story - Create a user story ("As a … I want … so that …" + acceptance criteria)

Releases

  • create_release - Record a release: version, name, link (tag / PR / pipeline), commit and the tasks it ships
  • list_releases, get_release - Releases with status, dates, tasks, notes and history
  • add_tasks_to_release - Link tasks to a release
  • update_release_status - Record planned → in_staging → released → verified, or rolled_back, with a note (deploy link, checks, incident). A rollback can name the release live again (rolled_back_to_release_id, default: the previous one) and notifies the team
  • generate_release_notes - Build release notes from the linked tasks, grouped by type
  • request_deploy - Ask to promote staging to production or roll production back through the team's own CI (pipeline control). A person other than you approves first, unless the project approves automatically

Todos

  • list_todos, get_todo_by_id, search_todos - Browse and look up todos
  • create_todo, bulk_create_todos - Create todos. Write the description as WHAT: / CHANGE: / FILES: / ACCEPTANCE: sections, each label on its own line followed by - bullet lines (real line breaks), and pass the checks as acceptance_criteria[] and validation_steps[] (also estimated_minutes, priority)
  • claim_todo - Claim a todo
  • update_todo - Fix a todo's title, description, priority, acceptance_criteria, validation_steps or estimated_minutes (never its status). Lead / single agent tokens: any todo of the project; coder / tester tokens: todos of a task delegated to them; reviewers: none. A done todo keeps its criteria and steps. Same expected_updated_at, 409 and history rules as update_task; at most 120 edits an hour per token
  • update_todo_status - Update progress
  • post_todo_artifact - Attach artifacts

Orchestration

  • ask_orchestrator - Get AI guidance
  • report_loop_signal - Report loop signals
  • get_inbox, ack_message, dismiss_message - Orchestrator messages
  • post_status_update - Lead tokens only (role orchestrator or all): tell the project's people on the web what happened (a card or the floating agent bubble on any page). Markdown body (≤ 2000), optional title (≤ 120), kind (info | progress | done | warning | needs_you), task_id, up to 3 links (https or app paths) and a thread key that updates the same update in place (progress → done). Post at meaningful moments only (a merge, a deploy started/finished, a stage handed in or returned, a blocker, a decision you need), never every step and never secrets (refused with 422). At most 6 in 10 minutes and 30 an hour per token; the same content within 10 minutes is not posted twice
  • request_release_merge - Lead tokens only: ask the people who approve deploys to review and merge a release PR (dev → main) of the project's connected repository. Pass pr_number (or pr_url, read only for its repository and number), optionally integration_id, release_version, a plain-text summary (≤ 280), task_ids and staging_verified. The server checks the PR through GitHub / GitLab (open, not a draft, not a fork, into the default branch) and shows a dialog with CI, staging, migrations, conflicts, the expected version and the tasks, plus a button to the PR whose URL the server builds. One request per PR (calling again updates it); it follows the PR until merged or closed. At most 6 an hour per token. Resolflow never merges, and agents must never merge it themselves

Workflows, templates & reports

  • list_workflows, get_workflow - Workflow definitions
  • suggest_template, apply_template - Task templates
  • list_reports, get_report - Reports

Development

# Install
cd mcp-client
pnpm install

# Build
pnpm run build

# Test locally
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | RESOLFLOW_MCP_TOKEN=YOUR_TOKEN node dist/index.js

Troubleshooting

"Unauthorized - invalid or expired token"

  • Verify your token is correct and hasn't been revoked
  • Generate a new token from the Resolflow dashboard

"Connection refused" / network errors

  • The client will automatically retry up to 3 times on transient errors (tool calls are retried only on 429 or connection failures)
  • Check your internet connection and firewall settings

License

MIT