API de Plataforma CafeTech

Cada servidor MCP habla JSON-RPC 2.0. Todas las llamadas son POST al endpoint del servidor.

Métodos JSON-RPC Soportados

Forma de la Solicitud

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": { "key": "value" }
  }
}

Respuesta de Éxito

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { ... }
}

Respuesta de Error

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Agent not permitted for MCP category: blockchain"
  }
}

Códigos de Error

Información del Servidor (GET, sin autenticación)

Cada categoría tiene un endpoint <code>GET</code> que devuelve metadatos sin autenticación:

GET https://cafetech.lat/mcp/events

{
  "server": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "cafetech-events", "version": "1.0" }
  },
  "tools_count": 9,
  "tools": [
    { "name": "list_events", "description": "Lists upcoming, active or past events." },
    ...
  ]
}

Llamar a un servidor privado

curl https://cafetech.lat/mcp/analytics \
  -H "Content-Type: application/json" \
  -H "X-Agent-Key: your_agent_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Endpoint mínimo requerido

POST /run

Cuerpo de la solicitud desde la plataforma:

{
  "context": {
    "triggered_by": "cafetech_platform",
    "agent_name": "ceo_agent",
    "payload": { "any": "data" }
  }
}

Respuesta esperada:

{
  "success": true,
  "result": { "your": "output" },
  "decision": "acted",
  "reasoning": "One-sentence explanation of what the agent did and why."
}

Endpoints opcionales recomendados

Compatibilidad con Framework

Flujo de Trabajo

# 1. Fork & clone
git clone https://github.com/CoffeTech/app-web.git
cd app-web

# 2. Start local environment with hot reload
docker compose -f docker-compose.dev.yml up -d

# 3. Create a feature branch
git checkout -b feat/your-feature

# 4. Make changes and write tests
bundle exec rspec

# 5. Open a Pull Request against main

Lo que recibimos

Crear un nuevo agente (Ruby)

# app/services/agents/my_agent.rb
module Agents
  class MyAgent < BaseAgentV2
    VERSION     = "1.0"
    DESCRIPTION = "One sentence describing what this agent does."
    INPUTS  = [{ name: "target_id", type: "integer", required: true }]
    OUTPUTS = [{ name: "decision", type: "string" }]

    def run
      # Main execution loop — called by AgentRunnerJob
    end

    def evaluate(target, conditions = {})
      { decision: "act", should_act: true, reasoning: "..." }
    end

    def execute(target, decision, reasoning)
      # Side effects here
    end
  end
end

Checklist de Pull Request

• □ Tests pasan (bundle exec rspec)
• □ Sin nuevas vulnerabilidades de seguridad
• □ Nuevos agentes registrados en docs/agents/AGENTS_REGISTRY.md
• □ Nuevas herramientas MCP documentadas en docs/developers/MCP_PROTOCOL.md
• □ La descripción del PR explica qué cambió y por qué
• □ Cambios disruptivos claramente marcados

Proponer un nuevo repositorio comunitario

1. Abre un issue en CoffeTech/app-web etiquetado org-proposal
2. Describe: propósito, stack, alcance, cómo se relaciona con la plataforma
3. Si se aprueba, se crea un nuevo repo y podrías ser invitado como colaborador

Propuestas de Gobernanza

Las decisiones significativas de la plataforma se pueden enviar como propuestas a través del sistema de gobernanza DAO:

curl https://cafetech.lat/mcp/events \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_proposal",
      "arguments": {
        "title": "Add Discord MCP server",
        "description": "Detailed description..."
      }
    }
  }'