Rode o gsage no seu ambiente.

§Repositórios

O gsage é distribuído em dois repositórios source-available no GitHub. Dê star para acompanhar releases.

§Quick start

Instale o gsage com um único comando:

$ curl -fsSL http://raw.githubusercontent.com/guardiankey/gsage-ai-soc/refs/heads/main/dist/get-gsage.sh | sudo bash

Os detalhes de instalação estão no repositório principal: guardiankey/gsage-ai-soc.

§Ferramentas & integrações

Tools são como o gsage interage com o seu ambiente. A plataforma foi feita para tornar simples adicionar novas integrações.

O guia canônico para criar tools está em docs/dev/TOOLS.md. Esta página mantém apenas um exemplo curto alinhado à API de BaseTool:

from __future__ import annotations

from typing import ClassVar, Optional

from src.mcp_server.tools.base import BaseTool, ToolResult
from src.shared.security.context import AgentContext


class MyTool(BaseTool):
    name: ClassVar[str] = "my_tool"
    version: ClassVar[str] = "1.0.0"
    summary: ClassVar[str] = "One-line summary used by search_tools"
    category: ClassVar[str] = "utility"
    permissions: ClassVar[list[str]] = ["utility:run"]

    params_schema: ClassVar[dict] = {
        "type": "object",
        "properties": {"value": {"type": "string"}},
        "required": ["value"],
    }

    config_schema: ClassVar[Optional[dict]] = {
        "properties": {"prefix": {"type": "string"}},
    }
    config_defaults: ClassVar[dict] = {"prefix": ""}

    async def execute(
        self,
        agent_context: AgentContext,
        params: dict,
        config: dict,
        state: dict,
    ) -> ToolResult:
        raw_value = params.get("value")
        if not isinstance(raw_value, str) or not raw_value.strip():
            return self._failure("INVALID_INPUT", "'value' must be a non-empty string")

      return self._success({
            "value": f"{config.get('prefix', '')}{raw_value.strip()}",
            "org_id": str(agent_context.org_id),
      })

§Contribuindo

Contribuições são bem-vindas, mas devem ser pragmáticas e fáceis de revisar. Compartilhe tools e integrações que outros possam usar; evite grandes refatorações ou mudanças arquiteturais sem discussão prévia.

1. abra uma issue primeiro para mudanças significativas;
2. mantenha PRs focados em um problema;
3. inclua testes quando o comportamento mudar;
4. atualize docs de apoio quando o setup ou uso mudar;
5. evite misturar refactors com mudanças funcionais, salvo se acoplados.

Antes de contribuir, revise docs/dev/. Ao submeter contribuições, você concorda com os termos descritos na LICENÇA.

§Issues e suporte

Se encontrar um bug, abra uma issue no GitHub. Ao reportar, inclua:

• o que você esperava que acontecesse;
• o que de fato aconteceu;
• o serviço afetado;
• logs relevantes;
• passos de reprodução;
• detalhes do ambiente (versão do Docker, SO, LLM provider).

Se a issue envolver segredos, credenciais ou dados sensíveis de cliente, faça redaction antes de postar.

---