Integrações: Channels, MCP, Skills e API REST

Canais de comunicação nativos, Model Context Protocol, skills marketplace e os 74 endpoints REST.

Panorama de integrações

O IronShell integra com o mundo externo em quatro frentes principais, cada uma com propriedade de segurança consistente.

Channels — 8 canais de comunicação nativos.
MCP (Model Context Protocol) — protocolo aberto da indústria para tools externas.
Skills — mais de 1.400 skills embutidas ou importáveis.
API REST — 74 endpoints para integração programática.

Em todas as frentes, cada ação de entrada ou saída passa pela auditoria do kernel antes da execução.

Channels

O IronShell suporta 8 canais de comunicação prontos para uso. Cada canal tem handler dedicado, validação de assinatura (HMAC ou equivalente) e proteção contra replay via janela temporal.

Lista completa de canais

| Canal | Protocolo | Caso de uso típico | Assinatura | | --- | --- | --- | --- | | Telegram | Bot API | Chatbot pessoal, alertas ops | Secret token por bot | | Discord | Bot + Webhooks | Comunidade, notificações | Ed25519 + timestamp | | Slack | Bolt + Events | ChatOps enterprise | HMAC-SHA256 + replay window | | Matrix | Client-Server API | Chat federado | Access token | | Email | IMAP + SMTP | Processamento de tickets | SPF/DKIM/DMARC | | MQTT | Pub/Sub | Sensores IoT, streaming telemetria | TLS client cert | | WhatsApp | Cloud API (Meta) | Suporte a cliente | Webhook token | | IRC | Raw TCP | Comunidades legacy | SASL auth |

Propriedades compartilhadas

Cada canal implementa:

Rate limit por origem — proteção contra flood, desconexão automática em excesso.
Validação de assinatura — rejeição imediata de mensagens sem assinatura válida.
Proteção contra replay — janela temporal padrão de 5 minutos; mensagens fora da janela são descartadas.
Audit log — cada mensagem recebida e enviada é registrada na chain HMAC.
Retry com backoff exponencial — falhas de entrega são retentadas 3 vezes com 1s, 2s, 4s de espera.

Exemplo: Telegram bot com IronShell

Configure:

# .env
TELEGRAM_BOT_TOKEN=1234:ABCDef...
IRONSHELL_TELEGRAM_ENABLED=true
IRONSHELL_TELEGRAM_AGENDE_ENABLED=true  # habilita /agende para agendar rotinas

Comandos embutidos:

/start — handshake inicial, associa chat ID ao usuário.
/ajuda — lista comandos disponíveis.
/agende <data> <hora> <prompt> — agenda uma rotina proativa.
/cancelar <id> — cancela uma rotina agendada.

Toda mensagem processada passa pelo kernel de segurança antes de alimentar o LLM. Se o usuário digitar um comando que dispara prompt injection (tentativa de exfiltrar dados do próprio sistema do bot), a resposta vai ser bloqueada com mensagem estruturada.

Exemplo: Slack ChatOps

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
SLACK_APP_TOKEN=xapp-...
IRONSHELL_SLACK_CHANNELS=#ops,#dev-bot

Uso típico em produção:

Alguém posta no canal #ops: "@ironshell quantos jobs falharam na última hora?"
O IronShell recebe via Events API, valida HMAC, processa.
Agente consulta logs internos (via tool auditado).
Resposta volta com estatística estruturada.

Model Context Protocol (MCP)

O MCP é um protocolo aberto para conectar LLMs a fontes de dados e ferramentas externas. O IronShell tem cliente MCP completo, integrado ao registry interno de tools.

O que o cliente MCP permite

Tool discovery — conectar a um server MCP e descobrir as tools disponíveis.
Tool execution — chamar uma tool externa via JSON-RPC 2.0.
Resource listing — listar recursos expostos pelo server (arquivos, endpoints, datasets).
Prompt templates — consumir prompts parametrizados definidos pelo server.
OAuth 2.1 — autenticação com refresh automático de token.

Como integrar

Configure um server MCP no .env:

IRONSHELL_MCP_SERVERS=gmail,drive,github
IRONSHELL_MCP_GMAIL_URL=https://mcp.example.com/gmail
IRONSHELL_MCP_GMAIL_AUTH=oauth2.1
IRONSHELL_MCP_GMAIL_CLIENT_ID=...
IRONSHELL_MCP_GMAIL_CLIENT_SECRET=...

O IronShell descobre automaticamente as tools de cada server, valida schemas, e registra cada tool no registry interno. Quando o agente chama uma tool MCP, o kernel audita o payload antes do JSON-RPC ser enviado ao server externo.

Servers MCP publicados suportados

O IronShell roda com qualquer server MCP compliant. Exemplos populares testados:

Servers do Anthropic (Gmail, Calendar, Drive, Sentry).
Servers da comunidade (GitHub, Notion, Linear, Figma, Postgres).
Servers customizados via SDK oficial.

Skills

O IronShell indexa mais de 1.400 skills descobertas via scanner de biblioteca. Cada skill é um arquivo markdown com frontmatter YAML definindo metadados e código/prompt de operação.

Skills built-in (core)

As skills principais embarcadas incluem:

elevenLabs — text-to-speech com vozes realistas.
imageGen — geração de imagem via Gemini, DALL-E, Stability.
weather — consulta meteorológica.
github — operações git e GitHub API.
notion — integração com Notion API.
spotify — controle de playback.
whisper — speech-to-text local via whisper.cpp.
summarize — sumarização recursiva de textos longos.
trello — gestão de tarefas.
ironDesktop — automação desktop cross-OS.

Além dessas 10 core, 53 skills formam a biblioteca community shipped por padrão, cobrindo casos como cold-email, lead-qualification, code-review, security-audit, competitor-intelligence, contexto-builder. Mais de 1.300 skills adicionais são descobertas em repositórios de terceiros compatíveis com o padrão Anthropic Skills.

Instalação de skill

ironshell skill install <nome>

O processo de instalação executa, em ordem:

Parse do frontmatter — validação de schema Zod (title, description, license, tags, capabilities).
License gate — bloqueia licenças incompatíveis (GPL, AGPL, LGPL, SSPL). Aceita MIT, Apache, BSD, ISC. Licença desconhecida requer confirmação explícita.
Scan de segurança — kernel audita o conteúdo da skill antes de aceitar.
Deduplicação por content hash — SHA-256 do conteúdo impede instalação duplicada.
Atomic write — grava em arquivo temporário, renomeia só se tudo passou.
Registro — indexa no Knowledge Graph interno para busca semântica.

Compatibilidade OpenClaw

Skills no formato OpenClaw são drop-in compatíveis. Você pode importar bibliotecas inteiras sem conversão manual.

Criar skill custom

Uma skill é um arquivo .md:

---
name: my-custom-skill
description: Extract invoice totals from PDF documents
version: 1.0.0
license: MIT
tags: [pdf, invoice, extraction]
capabilities: [read_file, llm_call]
---

# My Custom Skill

Instructions for the agent:
1. Read the PDF at the provided path.
2. Extract the line items and totals.
3. Return structured JSON.

## Example

Input: /path/to/invoice.pdf
Output: { total: 1500.00, currency: "USD", items: [...] }

Coloque o arquivo em ~/.ironshell/skills/local/ e o scanner o indexará na próxima inicialização.

API REST

O IronShell expõe 74 endpoints REST, organizados em famílias funcionais. Todas as rotas passam pelo mesmo pipeline de segurança: autenticação → rate limit → audit → processamento.

Famílias de endpoints

`/v1/chat/*` — agent turns

POST /v1/chat — turno completo com processamento de skill calls.
POST /v1/chat/stream — streaming via Server-Sent Events.
GET /v1/chat/history — histórico da sessão corrente.

`/v1/audit/*` — kernel de segurança

POST /v1/audit — audita um comando sem executar.
POST /v1/audit/batch — batch de comandos.
GET /v1/audit/patterns — lista padrões ativos.

`/v1/skills/*` — marketplace

GET /v1/skills — lista skills disponíveis.
POST /v1/skills/install — instala skill por nome.
POST /v1/skills/run — executa skill com parâmetros.
GET /v1/hub/skills?q=<query> — busca no marketplace.

`/v1/memory/*` — memória

GET /v1/memory — episódios recentes.
POST /v1/memory/store — armazena KV persistente.
POST /v1/memory/search — busca híbrida RAG.
GET /v1/memory/graph — snapshot do Knowledge Graph.

`/v1/squad/*` — agentes especialistas

POST /v1/squad/invoke — invoca agente especialista.
GET /v1/squad/agents — lista agentes disponíveis.

`/v1/swarm/*` — consenso Byzantine

POST /v1/swarm/propose — propõe ação que requer quórum 2/3.
GET /v1/swarm/status/:id — status de uma proposta.

`/v1/ade/*` — pipeline autônomo de desenvolvimento

POST /v1/ade/spec — cria spec a partir de descrição natural.
GET /v1/ade/status/:id — status da pipeline.

`/v1/vision/*` — computer vision

POST /v1/vision/analyze — análise multimodal.
POST /v1/vision/ocr — extração de texto de imagem.
POST /v1/vision/template/match — template matching.
POST /v1/vision/live/start — streaming de análise em tempo real.

`/v1/desktop/*` — automação RPA

POST /v1/desktop/execute — ação desktop nativa.
POST /v1/desktop/browser/* — navegação web via Playwright.
POST /v1/desktop/rpa/run — executa flow RPA JSON.
POST /v1/desktop/remote/* — controle remoto via screenshot.

`/v1/channels/*` — canais de comunicação

GET /v1/channels — canais ativos.
POST /v1/channels/<canal>/webhook — webhook entrada.
POST /v1/channels/<canal>/send — envio saída.

`/v1/codeguard/*` — análise de código

POST /v1/codeguard/scan — scan de diretório, retorna score.
GET /v1/codeguard/report/:id — report detalhado.

`/v1/guard/*` — guards semânticos

POST /v1/guard/semantic — análise anti-falácia.
POST /v1/guard/leak — scan de credenciais no texto.

`/v1/hub/*` — marketplace e threat intel

GET /v1/hub/patterns — últimos patterns publicados.
GET /v1/hub/threats — imunidade coletiva P2P.

Autenticação

Todas as rotas requerem header Authorization: Bearer <token>. Tokens são emitidos no primeiro login ou via painel enterprise. Rate limit padrão: 100 requests por minuto por token.

Streaming com SSE

curl -N -X POST http://localhost:3000/v1/chat/stream \
  -H "Authorization: Bearer $IRONSHELL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "explain what this file does", "stream": true}'

Eventos chegam como data: <json>\n\n com os seguintes tipos:

token — token parcial do LLM.
tool_call — agente chamando uma tool.
tool_result — resultado da tool.
audit — evento do kernel (bloqueio, warn).
done — turno completo.

OpenAPI spec

O IronShell expõe a spec OpenAPI 3.1 em /v1/openapi.json. Isso permite gerar clientes automaticamente com ferramentas como openapi-generator, oapi-codegen ou consumir direto via Swagger UI em /v1/docs.

CI/CD com IronShell

Integração típica em pipelines.

GitHub Actions — security gate

name: IronShell Security Gate

on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install IronShell
        run: npm install -g ironshell
      - name: Activate license
        run: ironshell license activate ${{ secrets.IRONSHELL_LICENSE }}
      - name: Audit source code
        run: npx ironaudit src/ --strict --format json --output audit-report.json
      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: audit-report
          path: audit-report.json

A flag --strict faz o processo sair com código 2 se qualquer risk score for maior ou igual a 70. Isso bloqueia o merge até a remediação.

GitLab CI

audit:
  stage: test
  image: node:22
  script:
    - npm install -g ironshell
    - ironshell license activate $IRONSHELL_LICENSE
    - npx ironaudit src/ --strict

Jenkins

pipeline {
  agent any
  stages {
    stage('Security') {
      steps {
        sh 'npx ironaudit src/ --strict --format json'
      }
    }
  }
}

Webhooks e event-driven

O IronShell suporta rotinas disparadas por webhooks externos além de cron. Configure em ~/.ironshell/routines.json:

{
  "name": "slack-alert-on-deploy",
  "trigger": {
    "type": "webhook",
    "path": "/hooks/deploy",
    "secret": "${SLACK_WEBHOOK_SECRET}"
  },
  "action": {
    "type": "chat",
    "message": "Deploy detected. Generating post-deploy summary."
  }
}

O webhook fica disponível em http://seu-host:3000/hooks/deploy. O secret valida HMAC-SHA256 de cada request antes de disparar a rotina.

OpenTelemetry

Todas as operações críticas são instrumentadas com spans OpenTelemetry, exportáveis para Jaeger, Tempo, Honeycomb ou qualquer backend OTLP.

# .env
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318
OTEL_SERVICE_NAME=ironshell-prod
OTEL_TRACES_SAMPLER=always_on

Spans cobrem: turnos do agente, chamadas LLM, audits do kernel, operações de memória, execuções de skill. Cada span carrega atributos estruturados (provider, model, risk_score, tokens_in, tokens_out, cost_usd).

Próximos passos

Deployment — self-host, VPS, enterprise on-premise.
Benchmarks — números reais medidos em hardware.
FAQ — perguntas sobre enterprise, SLA, compliance.