convez.ai
MCP ServerIntegração & APIsIntermediário
brycehans

await-mcp

brycehans/await-mcp

Pause agentes Claude até eventos externos chegarem via webhook

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que permite a um agente Claude aguardar sinais externos (webhooks, eventos) sem polling. Claude pausa a execução até que um evento nomeado chegue via HTTP, retomando imediatamente quando disparado. Ideal para fluxos que dependem de ações fora do controle do agente.

Instalação

$npx convez-ai brycehans/await-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Aguardar conclusão de deploys ou builds
  • Parar fluxo até aprovação manual (Slack, email)
  • Esperar pagamentos ou transações completarem
  • Sincronizar com eventos de sistemas externos
  • Orquestração de workflows multi-etapa

Veredito

Solução elegante para padrão comum: agentes que precisam esperar eventos externos sem desperdício de polling. Implementação limpa com interface HTTP simples e suporte a payloads JSON. Excelente para orquestração de workflows com dependências assíncronas.

README

A tradução para o português deste README ainda está na fila.

await-mcp

A Claude Code plugin that blocks a session until a named external event arrives.

Use it when a task depends on something outside Claude's control — a webhook, a Slack reply, a payment, a deploy finishing, a file appearing. Instead of polling, Claude waits and resumes the moment the event arrives.

Usage

/await "payment complete"
/await deploy-finished
/await slack-approval

From any terminal, script, or webhook handler, fire the event:

# URL form (simplest)
xh GET 'http://127.0.0.1:9876/event/payment%20complete' --ignore-stdin

# JSON form (with optional data payload)
xh POST http://127.0.0.1:9876/event name="payment complete" data:='{"amount":99}' --ignore-stdin

The event name must match exactly what was passed to /await.

How it works

The plugin runs a local Node.js process that listens on two interfaces simultaneously:

  • MCP (stdio) — exposes wait_until_event(name) to Claude Code. When called, it registers a pending waiter and blocks indefinitely.
  • HTTP (localhost:9876) — accepts POST /event (JSON body) or GET|POST /event/<name> (URL path). When an event arrives, it resolves all matching waiters.

No polling. No timeout. Claude resumes the instant the HTTP endpoint is hit.

Installation

Register this repo as a local marketplace in ~/.claude/settings.json under extraKnownMarketplaces:

"extraKnownMarketplaces": {
  "brycehans": {
    "source": {
      "source": "directory",
      "path": "/path/to/await-mcp"
    }
  }
}

Then install:

claude plugin install await@brycehans

Configuration

Environment variableDefaultDescription
AWAIT_PORT9876HTTP port to listen on

HTTP API

MethodPathBodyDescription
POST/event{"name":"...","data":{}}Fire an event with optional data
GET|POST/event/<name>—Fire an event by URL path
GET/health—Liveness check

The response is always {"ok":true,"resolved":<n>,"name":"...","data":{}} where resolved is the number of active waiters that were unblocked. If resolved is 0, the event arrived before anyone was waiting — it is dropped.


Development

Repo layout

await-mcp/
  package.json                   ← marketplace manifest (name + version only)
  .claude-plugin/
    marketplace.json             ← marketplace index (read by Claude Code CLI)
  plugin/                        ← installable content — copied to cache on install
    .claude-plugin/
      plugin.json                ← plugin metadata
    .mcp.json                    ← MCP server launch config
    index.js                     ← the MCP + HTTP server
    package.json                 ← dependencies + start script
    skills/
      await/
        SKILL.md                 ← the /await slash command

Everything under plugin/ is what gets installed. Files at the repo root (outside plugin/) are only read by the marketplace machinery — they are not part of the installed plugin.

Edit → reinstall → reload loop

  1. Edit files under plugin/
  2. Reinstall to refresh the cache:
    claude plugin install await@brycehans
    
  3. Start a new Claude Code session (the MCP server process is spawned fresh per session)

The install command copies plugin/ into ~/.claude/plugins/cache/brycehans/await/<version>/. You do not need to restart between edits to SKILL.md — skills are read at session start from the cache, so reinstall + new session is sufficient.

Running the server standalone

You can start the server outside of Claude Code to test the HTTP side:

cd plugin
bun install
node index.js

The MCP side requires a connected client (Claude Code), but the HTTP server starts regardless. Test it:

xh GET http://127.0.0.1:9876/health
# → ok

xh GET 'http://127.0.0.1:9876/event/test' --ignore-stdin
# → {"ok":true,"resolved":0,"name":"test","data":{}}

resolved: 0 is expected when no waiter is registered — the event is dropped.

Checking the server is running during a session

While /await is blocking inside Claude Code, confirm the HTTP endpoint is up:

xh GET http://127.0.0.1:9876/health

If it returns ok, the server is running and ready to receive events. If it fails, the MCP server process didn't start — check that bun is on PATH and plugin/node_modules/ was installed.

Version bumps

Version numbers live in four places — keep them in sync:

FileField
package.json (root)version
.claude-plugin/marketplace.jsonmetadata.version and plugins[0].version
plugin/package.jsonversion
plugin/.claude-plugin/plugin.jsonversion
plugin/index.jsversion in new Server({name:'await', version:'...'})

After bumping, reinstall — the CLI uses the version to name the cache directory, so a version bump gets a fresh cache slot:

claude plugin install await@brycehans

Marketplace mechanics

Claude Code reads .claude-plugin/marketplace.json at the repo root to enumerate available plugins. That file's plugins[0].source ("./plugin") tells the CLI where the installable content lives. On install, the CLI copies that directory into:

~/.claude/plugins/cache/brycehans/await/<version>/

The installed plugin is registered in ~/.claude/settings.json under enabledPlugins as await@brycehans. The known_marketplaces.json file at ~/.claude/plugins/known_marketplaces.json tracks the marketplace registration separately.

To uninstall:

claude plugin uninstall await@brycehans

To list installed plugins:

claude plugin list
Ver o original no GitHub

Bom para

Relacionados