MCP Handoff Server

🤝 MCP Handoff Server

Um servidor Model Context Protocol (MCP) que ajuda agentes de IA a repassar trabalho uns aos outros com documentação estruturada e acompanhamento de progresso.

✨ O que ele faz

Quando agentes de IA precisam passar trabalho entre si, este servidor fornece:

• 📝 Documentos de handoff estruturados com modelos
• 🔄 Acompanhamento de progresso do início à conclusão
• 📁 Organização automática de handoffs ativos e arquivados
• 🔍 Busca fácil e filtragem de trabalhos passados

🚀 Início Rápido

Basta executá-lo com npx - sem necessidade de instalação:

# Start in MCP mode (for MCP clients)
npx -y mcp-handoff-server

# Start HTTP server (for testing/direct API access)
npx -y mcp-handoff-server --mode http

É isso! O servidor cria automaticamente todas as pastas e modelos necessários.

📋 Uso Básico

Para Clientes MCP

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "handoff": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-handoff-server"
      ]
    }
  }
}

Para Testes HTTP

# Start server
npx -y mcp-handoff-server --mode http

# Test it works
curl http://localhost:3001/health

🛠️ Ferramentas Disponíveis

O servidor fornece estas ferramentas MCP para agentes de IA:

graph LR
    A[📝 create_handoff] --> B[📖 read_handoff]
    B --> C[🔄 update_handoff]
    C --> D[✅ complete_handoff]
    D --> E[📦 archive_handoff]

    F[📋 list_handoffs] --> B

    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style D fill:#e8f5e8
    style E fill:#fff3e0
    style F fill:#fce4ec

Funções das Ferramentas:

• create_handoff - Iniciar um novo documento de handoff
• read_handoff - Ler um handoff existente
• update_handoff - Adicionar atualizações de progresso
• complete_handoff - Marcar trabalho como concluído
• archive_handoff - Mover trabalho concluído para o arquivo
• list_handoffs - Encontrar e filtrar handoffs

📖 Exemplo: Criando um Handoff

# Start the server
npx -y mcp-handoff-server --mode http

# Create a new handoff
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "create_handoff",
    "params": {
      "type": "quick",
      "initialData": {
        "date": "2025-06-30",
        "time": "14:30 UTC",
        "currentState": {
          "workingOn": "Building user login",
          "status": "50% complete",
          "nextStep": "Add password validation"
        },
        "environmentStatus": {
          "details": {
            "Server": "✅",
            "Database": "✅"
          }
        }
      }
    }
  }'

🔧 Opções de Comando

npx -y mcp-handoff-server [options]

Options:
  --mode <mode>        'mcp' or 'http' (default: mcp)
  --port <port>        HTTP port (default: 3001)
  --handoff-root <dir> Storage directory (default: ./handoff-system)
  --help              Show help
  --version           Show version

🔄 Como Funciona

Fluxo de Trabalho Simples

1. Crie um handoff ao iniciar o trabalho
2. Atualize o progresso enquanto trabalha
3. Conclua quando terminar
4. Arquive para referência futura

graph TD
    A[🤖 Agent Starts Work] --> B{New Work?}
    B -->|Yes| C[📝 create_handoff]
    B -->|No| D[📖 read_handoff]

    C --> E[📁 Active Handoff]
    D --> E

    E --> F[🔄 update_handoff]
    F --> G{Work Done?}

    G -->|No| F
    G -->|Yes| H[✅ complete_handoff]

    H --> I[📦 archive_handoff]
    I --> J[🗄️ Archived]

    style C fill:#e1f5fe
    style F fill:#f3e5f5
    style H fill:#e8f5e8
    style I fill:#fff3e0

Organização de Arquivos

O servidor organiza automaticamente tudo em pastas:

• handoff-system/active/ - Trabalho atual
• handoff-system/archive/ - Trabalho concluído
• handoff-system/templates/ - Modelos de documentos

🎯 Dois Tipos de Handoffs

📋 Handoff Padrão - Para trabalhos complexos com contexto detalhado ⚡ Handoff Rápido - Para atualizações simples e transições breves

🏷️ Indicadores de Status

• ✅ Trabalhando - Tudo certo
• ⚠️ Aviso - Alguns problemas, mas não bloqueado
• ❌ Erro - Problemas que precisam ser corrigidos

🛠️ Desenvolvimento

Quer contribuir ou executar localmente?

# Clone and install
git clone <repository-url>
cd mcp-handoff-server
npm install

# Run in development
npm run dev

# Build for production
npm run build

📄 Licença

Licença MIT - sinta-se à vontade para usar isso em seus projetos!

🆘 Precisa de Ajuda?

• Issues: Issues do GitHub
• Protocolo MCP: Documentação do Model Context Protocol

---

Construído para colaboração perfeita entre agentes de IA 🤖✨