Skip to main content

mcp-master-of-puppets

Servidor MCP para comunicação assíncrona entre agentes de IA via caixas de entrada baseadas em arquivos.

Cada agente (Claude, GPT, Gemini, Deepseek…) tem seu próprio inbox. As mensagens são arquivos .md com frontmatter YAML. Um inbox-index.yaml por inbox mantém o uso da janela de contexto baixo — os agentes leem o índice primeiro e abrem apenas as mensagens relevantes.

Regra de naming dos subagents: o inbox deve seguir o formato agentname-role, com nomes em minúsculas e separados por hífen. Exemplo: claude-backend-senior.

Como funciona

Quando vários agentes de IA trabalham no mesmo projeto, eles não têm como se comunicar diretamente — cada um opera em sua própria sessão, sem memória compartilhada.

Este MCP resolve isso com um sistema de mailbox baseado em arquivos dentro do próprio repositório. Cada agente tem um inbox em .agents/mail/{agent-id}/. As mensagens são arquivos .md com frontmatter YAML. Um inbox-index.yaml por inbox evita que o agente precise abrir todas as mensagens de uma vez — ele lê o índice primeiro, filtra o que é relevante e só então abre as mensagens selecionadas.

O fluxo básico:

  1. Cada agente sabe seu agent-id (ex: claude, gpt, gemini)
  2. Ao iniciar, lê seu inbox e as tasks atribuídas a ele
  3. Executa a tarefa e envia mensagens para os outros agentes via mailbox
  4. Quando tem dúvida ou precisa de permissão, posta na fila review/ para o tech lead
  5. Ao finalizar sem pendências, gera um resumo do ciclo para o tech lead revisar

O resultado é um time de agentes que colabora de forma assíncrona, preserva histórico de decisões e evita conflitos de trabalho paralelo — tudo em arquivos rastreáveis pelo git.

Instalação e execução

uvx mcp-master-of-puppets

Ou com pip:

pip install mcp-master-of-puppets
mcp-master-of-puppets

Configuração no Claude Code

Adicione ao .claude/settings.json do seu projeto:

{
  "mcpServers": {
    "mail-agents": {
      "command": "uvx",
      "args": ["mcp-master-of-puppets"],
      "env": {
        "AGENTS_ROOT": "."
      }
    }
  }
}

AGENTS_ROOT é a raiz do projeto onde .agents/ será criado (padrão: diretório atual).

Configuração no Codex CLI

Adicione ao ~/.codex/config.toml:

[[mcp_servers]]
name = "mail-agents"
command = "uvx"
args = ["mcp-master-of-puppets"]

[mcp_servers.env]
AGENTS_ROOT = "."

Os subagents iniciados com CLI codex sobem com -a never, para não pedir aprovações interativas durante a execução em background.

Estrutura de pastas criada

.agents/
  mail/
    mailbox-rules.md
    all/                 ← broadcasts
    review/              ← fila do tech lead
    codex/               ← líder, se aplicável
    claude-backend-senior/
    gemini-qa/
  tasks/                 ← arquivos de tasks dos agentes

Regra para IDs de subagents

  • Todo subagent deve usar agentname-role, com pelo menos um hífen.
  • São aceitos apenas a-z, 0-9 e -.
  • Exemplos válidos: claude-backend-senior, gemini-qa, codex-frontend.
  • Exemplos inválidos: claude, Claude-QA, worker_1.

Essa validação é aplicada em mailbox_init_session e mailbox_spawn_agents.

Ferramentas disponíveis (16)

Ferramenta Descrição
mailbox_read_inbox Lê o índice do inbox de um agente
mailbox_read_message Abre uma mensagem específica
mailbox_mark_read Marca mensagem como lida
mailbox_send_message Envia mensagem para outro agente
mailbox_send_broadcast Broadcast para múltiplos agentes
mailbox_read_broadcast_inbox Lê o índice do all/ compartilhado
mailbox_read_broadcast Abre uma mensagem de broadcast
mailbox_create_review Posta na fila de revisão do tech lead
mailbox_read_review_inbox Lê o índice da fila de revisão
mailbox_read_review_message Abre uma mensagem da fila de revisão
mailbox_list_tasks Lista tasks de um agente
mailbox_read_task Lê um arquivo de task
mailbox_update_task_status Atualiza status da task e renomeia o arquivo
mailbox_create_task Cria uma nova task
mailbox_list_agents Lista agentes conhecidos (scan das pastas de inbox)
mailbox_read_rules Lê o mailbox-rules.md

Formato das mensagens

DD-MM-YYYY-HHmm-{from}-{to}-{assunto}.md
---
from: gpt
to: claude
date: 19-05-2026 14:30
subject: auth-refactor
status: unread
---

## Contexto
## Arquivos Alterados
## O Que Foi Feito
## Preciso Que Você Revise
## Problemas Encontrados
## Perguntas
## Próxima Ação Sugerida

Publicando atualizações

1. Edite o pyproject.toml e incremente a versão:

version = "0.1.1"

2. Reconstrua e publique no PyPI:

uv build
uv publish --token pypi-SEU_TOKEN

3. Faça commit e crie a tag da release no GitHub:

git add -A
git commit -m "chore: release v0.1.1"
git tag v0.1.1
git push && git push --tags

Após a publicação, usuários que usam uvx mcp-master-of-puppets receberão a versão mais recente automaticamente na próxima execução.

Licença

MIT

Metadata

Release files for mcp-master-of-puppets 0.7.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-master-of-puppets 0.7.4
File Size Uploaded Provenance Actions
mcp_master_of_puppets-0.7.4.tar.gz 32.8 kB Without provenance Details for mcp_master_of_puppets-0.7.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-master-of-puppets 0.7.4
File Interpreter ABI Platform Actions
mcp_master_of_puppets-0.7.4-py3-none-any.whl Python 3 none any Details for mcp_master_of_puppets-0.7.4-py3-none-any.whl

Total release size: 77.4 kB

Release files / mcp_master_of_puppets-0.7.4.tar.gz

Download URL mcp_master_of_puppets-0.7.4.tar.gz
Size 32.8 kB
Tags Source
SHA-256 checksum
How to use checksums
4ea3faf53998bb175a5c8c2836c686f699389aa66addf51c5a726d7dbc728ca2
BLAKE2b-256 checksum
How to use checksums
2e583fdc3bc17e21636cb542bbf02680f71f64084c2aa3512770ffb16feade83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Fedora Linux","version":"44","id":"","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / mcp_master_of_puppets-0.7.4-py3-none-any.whl

Download URL mcp_master_of_puppets-0.7.4-py3-none-any.whl
Size 44.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e6063fd54233c06d2445520c3dbdf1dad04fe2832fb26172a754e6683763e23c
BLAKE2b-256 checksum
How to use checksums
23577a6a74b365503a78a2f8cd692db031394cafc67823096ba58b6c239bc857
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Fedora Linux","version":"44","id":"","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for mcp-master-of-puppets 0.7.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page