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:
- Cada agente sabe seu
agent-id(ex:claude,gpt,gemini) - Ao iniciar, lê seu inbox e as tasks atribuídas a ele
- Executa a tarefa e envia mensagens para os outros agentes via mailbox
- Quando tem dúvida ou precisa de permissão, posta na fila
review/para o tech lead - 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-9e-. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.