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

@agilemonster/mcp-server

v1.0.35

Published

Official Model Context Protocol (MCP) server & Orchestrator for Agile Monster (Cursor, Claude Code, Antigravity, Codex, Hermes, Windsurf)

Readme

@agilemonster/mcp-server & Agent Orchestrator

Official Model Context Protocol (MCP) Server and Autonomous Agent Orchestrator for Agile Monster (https://app.agilemonster.com).

Seamlessly connects your Agile Monster boards with your favorite developer AI agents:

  • Cursor
  • Claude Code
  • Antigravity / Gemini Code Assist
  • Codex
  • Hermes Agent
  • Windsurf / Aider

⚡ Quick Start: Adding to your AI Agent

The quickest way is the one command in Connect a project folder below: it does everything in this section for you.

To set a tool up by hand, generate a Personal API Key in Agile Monster (https://app.agilemonster.com -> Profile -> AI Agents & API Keys -> Generate API key). Your key will look like am_live_....

1. Cursor (.cursor/mcp.json or Global Settings)

{
  "mcpServers": {
    "agilemonster": {
      "command": "npx",
      "args": ["-y", "@agilemonster/mcp-server"],
      "env": {
        "AGILEMONSTER_API_KEY": "am_live_your_token_here",
        "AGILEMONSTER_API_URL": "https://api.agilemonster.com"
      }
    }
  }
}

2. Claude Code CLI

claude mcp add agilemonster npx -y @agilemonster/mcp-server \
  -e AGILEMONSTER_API_KEY="am_live_your_token_here" \
  -e AGILEMONSTER_API_URL="https://api.agilemonster.com"

3. Antigravity / Gemini

Add to your Antigravity MCP directory (~/.gemini/antigravity/mcp/agilemonster or project settings):

{
  "mcpServers": {
    "agilemonster": {
      "command": "node",
      "args": ["/path/to/agilemonster/packages/mcp-server/bin/mcp.js"],
      "env": {
        "AGILEMONSTER_API_KEY": "am_live_your_token_here",
        "AGILEMONSTER_API_URL": "https://api.agilemonster.com"
      }
    }
  }
}

📁 Connect a project folder (bootstrap)

Open a terminal in your project folder and run this once (it needs Node.js 18.14 or newer):

npx -y @agilemonster/mcp-server bootstrap

It asks for your API key the first time, lets you pick the board, writes the files below, installs the background runner (see the next section) and then gets a coding agent ready: it shows which agents on this computer can work a card, offers to sign in each one that is installed but signed out (in that agent's own sign-in; Agile Monster never sees a password), and, if none is installed, offers to install one. init and setup are the same command. Add --board="Board name" to skip the question, --no-service to leave the background runner out, or --no-login to skip the sign-in offer. To come back to the sign-in step later:

npx -y @agilemonster/mcp-server agents login

This generates:

  1. .agilemonster.json — Binds the local repository to the board UUID, list columns, and default agent provider.
  2. AGENTS.md — Codified operational rules for autonomous agents (Cursor, Claude Code, Antigravity, etc.) so they know when to claim tasks, ask clarifying questions, log progress, and submit work for human testing.

🛠️ Available MCP Tools

Agents have access to these purpose-built lifecycle tools:

| Tool | Purpose | | :--- | :--- | | agilemonster_get_context | Inspects board, columns, and active tasks. Auto-detects project from .agilemonster.json or directory name. | | agilemonster_init_project | Binds current repo to an Agile Monster board and creates AGENTS.md. | | agilemonster_list_my_tasks | Lists cards assigned to the AI agent (queued, in_progress, waiting_for_input, review). | | agilemonster_claim_task | Claims a task, marking it in_progress on the board before code edits start. | | agilemonster_ask_question | Posts a question comment on the card and marks status as waiting_for_input so the user is alerted. | | agilemonster_add_progress | Logs implementation progress notes to task comments. | | agilemonster_submit_for_review | Marks work complete, moves card to Review column, reassigns to human member for confirmation, and posts test instructions. | | agilemonster_create_followup_tasks | Creates follow-up cards (e.g. "Deploy to Test", "Deploy to Production", "Write integration tests"). | | agilemonster_get_deploy_profile | How this project deploys: route, exact command, confidence, the evidence behind it, alternatives, and recent outcomes. | | agilemonster_record_deployment | Records how a deployment went (or pins the route the user stated) so every later task deploys the same proven way. |


🧠 Who works a card that is queued from the board

A card you assign to an agent in the web app is picked up by the background runner on your machine.

The background runner

bootstrap installs the runner as a service that starts with the computer, so cards are worked whether or not a coding tool is open. Without it, cards are only picked up while an AI coding tool with this MCP server is open in the project folder.

npx -y @agilemonster/mcp-server service status      # is it installed and running?
npx -y @agilemonster/mcp-server service install     # install or repair it
npx -y @agilemonster/mcp-server service uninstall   # stop and remove it
  • macOS: a launchd agent (~/Library/LaunchAgents/com.agilemonster.pulse.plist). Linux: a systemd user unit (agilemonster-runner.service). Windows: not available as a service yet; keep your coding tool open, or run npx -y @agilemonster/mcp-server pulse-daemon in a terminal.
  • The service runs its own copy of this package from ~/.agilemonster/runner and keeps it up to date.
  • A runner that was set up by hand is left alone unless you pass --force.
  • One worker per computer. While the background runner is running it alone works the cards, and the MCP server inside an open coding tool leaves them to it. A coding tool keeps its MCP server for as long as it stays open, on the version it started with, so the board does not hand cards to one that is older than the version cards need (1.0.33 today): the card then says to restart the coding tool or install the service.
  • The board shows the result: next to a waiting card it says whether a computer is connected, whether it is there right now, and which agent will do the work.

The agent that does the work

The runner hands a card to a real coding agent running headless in the project folder — the same agent you use in the IDE, with the same ability to search the code, open what it finds, run the build and fix what it broke:

| Card's agent | Command line agent used | One-time setup | | :--- | :--- | :--- | | Cursor | cursor-agent -p --force | curl https://cursor.com/install -fsS \| bash, then cursor-agent login | | Claude Code | claude -p --permission-mode acceptEdits --allowedTools Bash | npm install -g @anthropic-ai/claude-code, then claude auth login | | Codex | codex exec --sandbox workspace-write | npm install -g @openai/codex, then codex login |

If a terminal answers "command not found" for one of these, the agent is installed somewhere that terminal does not search. npx -y @agilemonster/mcp-server agents login finds it wherever it is, and the board shows the sign-in command with its full path.

The runner also finds an agent that is not on your PATH — for example the Codex CLI that the Codex app and its IDE plugin install, already signed in with your ChatGPT account — so there is often nothing to set up.

Nothing stands in silently. A card assigned to an agent by name is done by that agent or it waits, and the card says what it is waiting for (usually one sign-in command). A card set to Automatic is done by whichever agent is ready. Why a sign-in at all: an IDE's chat window only acts when you type into it, so unattended work goes through that product's command line agent, which signs in separately from the IDE. An IDE without a command line agent (Antigravity, Windsurf) only works a card from its own chat window. Cards assigned before 1.0.28 keep the old behaviour (any ready agent may do them).

To see what this machine will use, and the one step that would fix an agent that is not ready:

npx @agilemonster/mcp-server agents

The agent gets the card, the requester's replies on it, and three rules: decide open details the way the codebase already does instead of asking, check your own work, and do not commit — the runner commits and deploys exactly the files the agent changed, after its own build check.

  • No CLI installed or signed in? The card falls back to the built-in engine (the server-side model picks a few files and writes one patch). It cannot explore or debug, so it is noticeably weaker; the card tells you what to install or sign in to.
  • Only your own cards reach the agent. It can run commands on your machine, so a card or comment written by another board member is never passed to it. Those cards use the built-in engine.
  • You can keep working while a card runs. The agent does not work in your folder. It works in a private copy of it, made in seconds next to the project (a hidden .agilemonster-… folder, removed when the run ends), with your installed packages, local config and uncommitted work included. Only the files the agent changed are brought back and committed. Whatever you (or another agent session) edit in your own folder meanwhile stays yours: it is never committed with the card and never "put back".
  • Your edits are never overwritten. If the agent changed a file that you also changed while it worked, or one that already had uncommitted changes of yours, nothing of the card is put in your folder and the card asks you to commit or stash first.
  • Where that copy is possible. On a disk that can clone files instantly: APFS on any Mac, Btrfs or XFS on Linux. The project folder must be the top of its own Git repository. Elsewhere (Windows, ext4, a subfolder of a larger repository) the agent works in the project folder itself, and files you save during the run can end up in the card's commit, so leave the folder alone until the card is in review.
  • After a card that changes dependencies, your own folder has the new package.json (or pubspec.yaml, …) but still the old installed packages: run your usual install command. The review says so when it applies.
  • How long a run may take. A run is not on a fixed clock. It ends when the agent finishes, when the agent has shown no sign of work for ten minutes, or after three hours in total. Signs of work are: anything the agent prints, Claude Code's own session transcript growing, an uncommitted file in the working folder changing, and the agent's processes (the tests or build it is waiting on included) using the processor. A command that is alive but idle, such as a dev server or a test runner in watch mode, is not work. On Windows only Claude Code can be observed this way; for the other agents only the three hour limit applies.
  • A run that is stopped loses nothing. The files the agent had changed are kept for 14 days: in its private copy, or, where it worked in the project folder itself, set aside under ~/.agilemonster/kept-work with the folder put back the way it was. The card says exactly what was kept. Try again continues the same Claude Code session where it stopped; Cursor, Codex and your own command start again with the kept files already in place.

| Variable | Effect | | :--- | :--- | | AGILEMONSTER_AGENT_ENGINE | claude, cursor or codex to pin one; builtin to never start an agent CLI. | | AGILEMONSTER_AGENT_COMMAND | Your own command instead. It runs in the project folder with the brief in $AGILEMONSTER_PROMPT_FILE; whatever it prints last is the report. | | AGILEMONSTER_AGENT_QUIET_MINUTES | How long an agent may show no sign of work before its run is stopped (default 10; off: only the overall limit applies). | | AGILEMONSTER_AGENT_TIMEOUT_MINUTES | The overall limit for one agent run, however busy the agent is (default 180, at most 480). | | AGILEMONSTER_ISOLATE | off: the agent works in the project folder itself. copy: always use a private copy, even on a disk that has to copy every file (slow for a large project). Unset: a private copy wherever it is instant. | | AGILEMONSTER_REPORT | off: the runner keeps its own failures on this computer and reports none of them (see "What the runner reports back"). Unset: failures are reported. |


What the runner reports back

When something goes wrong on your computer (a card fails, the runner crashes, an update or a deploy does not go through, or the runner cannot work the way it prefers), the background runner tells Agile Monster with its next heartbeat, so that setups that break get fixed instead of staying in a log file on your disk.

  • What is sent: the name of the event (card.failed, deploy.failed, ...), a short error message, which agent it concerned, and how often it happened. With every heartbeat: the runner version, your system (darwin, its release, arm64), the Node version, and each agent's version and whether it is ready.
  • What is never sent: card titles and text, project names, your code, and file paths. Of a path only the last part is kept (…/app.ts); the home folder, e-mail addresses and anything shaped like a key or a token are removed before the message is stored, even on your own disk (~/.agilemonster/outbox.json).
  • Turning it off: set AGILEMONSTER_REPORT=off. Nothing is collected and nothing is sent; cards work exactly as before.

A card that was made from a problem report or an error alert is never handed to an agent that can run commands, on any runner version: its text came from outside your board.

Connecting the right folder

bootstrap connects the folder your terminal is in. Before it writes anything it shows the folder, its repository and the board, and it stops in two cases (1.0.33 and newer):

  • The folder already belongs to another board. Usually the terminal is in the wrong project. It cancels by default; in a terminal you can choose to move the folder to the new board or let both boards use it. Without a terminal, add --move or --both.
  • The folder looks nothing like the board (its name, the folder above it and its repository are compared with the board's name). It asks once; without a terminal, add --yes.

The background runner also never rewrites a folder's .agilemonster.json to another board while the board it names still uses the folder, and the board's AI Agents settings show a warning when two boards are connected to one folder.

Whose cards reach your agents

A coding agent started by the runner (Claude Code, Cursor, Codex) can read, change and run things in your project folder. So it only works cards written by:

  • you, the account this computer's API key belongs to, and
  • board members you named under "Who may send requests to my agents" in the board's AI Agents & Project Setup (runner 1.0.33 and newer). The list is per board, starts empty, and only you can change it. Their replies to an agent's question reach the agent too.

Everyone else's cards are still done, by the built-in engine, which edits a handful of files in one pass and has no shell. The card says so and names who can add the requester.

The runner reads your list from the server at the start of every run, for your own account. It never takes it from a card or a comment, so nobody can add themselves, and taking someone off the list counts for the next card, including cards they wrote earlier. If the list cannot be read, only your own cards reach an agent.

Being on the list never includes choosing how the project deploys: a deploy: reply, a "yes" to a first-time deploy question, an undo, and what happens to unpushed commits are only accepted from you.

🚀 How deployment is decided (and remembered)

Cards started from the Agile Monster web app run in the background without your IDE's context, so the server works out how a project ships from evidence and from what worked before:

  1. Explicit — .agilemonster/deploy.json in the repo ({"method": "docker_compose", "command": "...", "live_url": "..."}), or a route pinned with agilemonster_record_deployment({ pin: true }) / a card reply.
  2. Learned — the last deployment that was verified on this machine.
  3. Evidence, ranked — a deploy workflow that really fires on a push to the checked-out branch (path filters and workflow_run chains included) › a deploy script › a cloud CLI config › the Docker Compose stack that is running from this folder (reused with its exact project name and files) › a compose file › a plain git push.

What the runner guarantees:

  • Commits only the files it changed — never git add -A; local files holding your API key are filtered and added to .git/info/exclude.
  • Verifies before claiming "Deployed" — deploy workflow run for that commit, container state and health, script exit code, and a smoke check of a URL you provided. A guessed URL can never fail a deploy.
  • Asks once, then remembers — an unconfirmed deploy script, cloud CLI or manually-dispatched workflow is not run on a guess. Reply on the card with deploy: <command or method> to confirm; retry re-runs only the deployment, not the code change.
  • Heals what it can — starts Docker Desktop/OrbStack if it is installed but stopped, rebases and re-pushes when the remote moved ahead, retries network errors, and falls back to the next route when the chosen one plainly does not apply.
  • Checks the branch before it starts — fetches, and fast-forwards a folder that is only behind (Git refuses if that would touch an uncommitted edit of yours). Unpushed commits that fit are replayed on top. If unpushed commits clash with the remote, the card asks first, in plain words, instead of letting an agent work for minutes on something that cannot be pushed.
  • A refused push comes with ways out — the card says what clashes (this card, or older commits that never left this computer) and offers Ship only this change or Redo on the latest version. Anything moved out of the way is kept on an agilemonster/backup-… branch; nothing is deleted. If you push the change yourself, retry only checks the deployment: no second commit, no second deploy.
  • Asks before it guesses — the agent decides how to build something by itself, but when a card names a screen or section that does not exist as written, or can be read as two different changes, it stops and asks which is meant, with the readings as buttons.
  • Every change can be taken back — in review, Undo this change (or the reply undo) reverts the card's commits with new commits and deploys again, so the product is as it was before the card. On a board that deploys on approval, it discards the change that was waiting. It refuses, and says why, when later work builds on the change or the folder has uncommitted work.
  • Never reports a slow pipeline as failed — a CI run that outlives the wait is marked pending and re-checked on later pulses; the outcome is posted on the card.

State lives outside your repositories: ~/.agilemonster/projects/ (per-project deployment history) and ~/.agilemonster/logs/daemon.jsonl (structured daemon log).

When the runner asks a question, the card shows the answers it accepts as buttons, so nobody has to type these. They still work as typed replies: retry · deploy: github_actions · deploy: docker_compose · deploy: manual · deploy: ./deploy/deploy.sh · live url: https://example.com · deploy: only this change · branch: start fresh · undo

Replies that decide what runs or what moves on your computer (deploy: …, branch: start fresh) are only taken from the person whose account the runner uses.


💡 MCP Native Prompts & Resources

The server exposes Model Context Protocol Prompts and Resources so agents can automatically load operational instructions into their context:

Prompts

  • agilemonster_agent_protocol: System instructions explaining the full task lifecycle protocol.
  • agilemonster_work_on_task: Guided workflow prompt for an agent to claim, investigate, implement, test, submit for review, and propose follow-up tasks for a specific card ID.

Resources

  • agilemonster://guidelines/agents: Live markdown text of the official Agent Guidelines (text/markdown).
  • agilemonster://project/context: Current repository board, list structure, and active agent tasks as live JSON (application/json).

🤖 The Autonomous Agent Orchestrator CLI

Use the built-in orchestrator to monitor tasks, dispatch work, or run a background watcher:

# Check current tasks assigned to agents for this project
npx @agilemonster/mcp-server status

# Watch for newly assigned tasks in real-time
npx @agilemonster/mcp-server watch

# Claim a task
npx @agilemonster/mcp-server claim <card_id>

# Submit for user testing & confirmation
npx @agilemonster/mcp-server review <card_id> "Implemented dark mode toggle" "Test via Settings screen"

# Ask the user a question
npx @agilemonster/mcp-server question <card_id> "Should we support OAuth tokens as well?"

📚 REST API Reference

For developers building custom scripts, CI/CD bots, or proprietary agent orchestrators, refer to the full REST API specification in docs/AGENT-API.md.