saferagenticai-mcp

Servidor MCP somente leitura que expõe o framework de segurança Safer Agentic AI: 238 padrões + 14 heurísticas operacionais via 12 ferramentas de consulta; Python stdio.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP SaferAgenticAI

Serve o framework SaferAgenticAI (critérios canônicos + camada de Padrões de Implementação) para assistentes de codificação por meio do Model Context Protocol.

Disponível em

Publicado nos catálogos MCP canônicos — instale a partir de um cliente com registro ou pela CLI abaixo:

PyPI — saferagenticai-mcp
Registro MCP Oficial — io.github.NellInc/saferagenticai-mcp

Também em expansão pelo ecossistema MCP mais amplo: mcp.directory, mcpservers.org, PulseMCP (via ingestão do registro) e mcp.so.

Instalação

Escolha o caminho que corresponde à sua configuração.

Opção 1 — `uvx` (mais rápida, sem venv manual)

Se você tiver o uv instalado, aponte seu cliente MCP para:

uvx --from git+https://github.com/NellInc/saferagenticai-mcp saferagenticai-mcp

O uv cuida do isolamento e armazena em cache a instalação. Funciona para linhas de configuração de comando único em ~/.claude/mcp.json.

Opção 2 — `pipx` (instalação global isolada)

pipx install "git+https://github.com/NellInc/saferagenticai-mcp"

Expõe saferagenticai-mcp globalmente; atualizado com pipx upgrade saferagenticai-mcp.

Opção 3 — venv manual (funciona offline a partir de um checkout)

Homebrew / Python do sistema bloqueia pip install direto sob PEP 668, então se você clonou o repositório e quer uma instalação editável:

python3 -m venv research/mcp/.venv
research/mcp/.venv/bin/pip install -e research/mcp/server

Produz research/mcp/.venv/bin/saferagenticai-mcp. Edições nos YAMLs de padrões no repositório são captadas ao vivo (modo editável).

Opção 4 — a partir do PyPI

pipx install saferagenticai-mcp
# or, with the modern uv toolchain:
uv tool install saferagenticai-mcp
# or plain pip:
pip install --user saferagenticai-mcp

Para reprodutibilidade de trilha de auditoria, fixe a versão: pipx install saferagenticai-mcp==0.3.6. O pacote inclui criteria-v1.json + 238 YAMLs de padrões + 4 exemplares + operational_heuristics.yaml dentro de saferagenticai_mcp/_data/, então uma instalação via wheel funciona sem checkout do repositório. (O wheel 0.3.0 é anterior à extensão do corpus e inclui apenas 214 padrões, sem heurísticas; 0.3.1 é o primeiro build completo.)

Configurar (Claude Code)

Adicione a ~/.claude/mcp.json (ou ao config MCP da sua IDE). Escolha a variante que corresponde à sua opção de instalação.

Com `uvx`

{
  "mcpServers": {
    "saferagenticai": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NellInc/saferagenticai-mcp",
        "saferagenticai-mcp"
      ]
    }
  }
}

Com `pipx` ou venv manual

{
  "mcpServers": {
    "saferagenticai": {
      "command": "/absolute/path/to/saferagenticai-mcp"
    }
  }
}

Para um checkout com venv manual, o caminho absoluto é <repo>/research/mcp/.venv/bin/saferagenticai-mcp.

Reinicie o Claude Code / sua IDE após editar. O servidor carregará na primeira chamada de ferramenta do seu assistente.

Ferramentas (12 no total)

Ferramenta	Entrada	Retorna
`list_suites`	—	16 suítes com títulos e contagens de subobjetivos
`get_requirement`	`id`, `include_pattern`	um subobjetivo + sua camada de Padrões; recorre a candidatos difusos se não houver correspondência exata
`list_requirements`	filtros de suíte/tipo/tipo_de_conteúdo/confiança	lista de subobjetivos filtrada com sinais de confiabilidade
`search_patterns`	`query`, `limit`, `verbosity`	correspondências ranqueadas com pesos por campo, com `matched_in` e (no modo completo) trechos + flags de confiança. Pesos de campo: título 10×, resumo 4×, sfr 3×, descrição 2×, corpo 1×
`get_cross_references`	`id`, `include_inferred`	adjacências de saída
`get_reverse_references`	`id`	adjacências de entrada (quem cita este padrão)
`resolve_id`	`query`	canonicaliza um id parcial, fragmento de slug ou display_id; sempre retorna candidatos
`find_patterns_for_task`	`task`, `limit`, `verbosity`	principais padrões agrupados por suíte para uma descrição de tarefa; padrão é modo compacto para triagem barata
`list_unreviewed`	`limit`	padrões sem `reviewed_by`, ordenados por menor confiança primeiro
`review_stats`	—	% de cobertura, por suíte, por confiança; além da contagem de problemas de validação
`list_operational_heuristics`	`suite_id`?, `query`?	heurísticas operacionais destiladas de implantações de IA agêntica em produção, opcionalmente filtradas por suíte ou palavra-chave
`get_operational_heuristic`	`id`	uma heurística operacional por id (ex.: `OH::geoffrey-pattern`); retorna a entrada completa com princípio, mapeamento de framework, padrões de design e narrativa de descoberta

Fontes de dados

Framework normativo: framework/catalog/, carregado pela projeção gerada assessor/src/data/criteria-v1.json
Camada de padrões: research/mcp/suites/<SUITE>/<pattern_id>.yaml (238 arquivos)
Exemplares: research/mcp/exemplars/*.yaml (fallback para quatro subobjetivos âncora)
Heurísticas operacionais: research/mcp/operational_heuristics.yaml (14 heurísticas)

Na inicialização, o servidor carrega ambos e constrói um índice em memória chaveado por pattern_id. Consultas por display_id também são suportadas, mas podem resolver para múltiplos subobjetivos (variantes sublinhadas).

Teste rápido (sem MCP instalado)

python3 -c "
from saferagenticai_mcp.framework_loader import load_framework
idx = load_framework()
print(f'{len(idx.subgoals)} subgoals, {sum(1 for s in idx.subgoals.values() if s.has_pattern)} with patterns')
"

Versionamento

Framework canônico: segue o campo version de criteria-v1.json.
Camada de padrões: v1-draft enquanto este diretório está sendo populado; v1 após revisão.
Servidor: versionamento semântico. A versão atual é 0.3.6 (framework 1.3-draft, corpus completo de 238 padrões e heurísticas operacionais incluídas). Fixe explicitamente para reprodutibilidade de auditoria.

O que já está embutido

Hot reload — o servidor percorre a árvore de fontes a cada chamada de ferramenta; edições aparecem sem reiniciar.
Validação no carregamento — campos obrigatórios, enum de content_type, enum de confiança. Padrões inválidos registram WARNINGs, mas não derrubam o servidor.
find_patterns_for_task — tarefa em linguagem natural → principais padrões agrupados por suíte. Substitui a necessidade de um índice de embeddings separado na escala atual.
Índice reverso de xref — construído no carregamento, consultado por get_reverse_references.

Não implementado

Autenticação / transporte remoto (apenas stdio).
Busca semântica baseada em embeddings — a pontuação por palavras-chave com pesos por campo é suficiente com 238 padrões; embeddings valeriam a pena em 10× esta escala.
Ferramenta de escrita mark_reviewed — deliberadamente não adicionada. Edições de revisão da Fase 3 passam direto pelo YAML (editor + git diff = auditável); o MCP permanece somente leitura.

A arquitetura agêntica nativa mais ampla propõe operações de orientação composta, pacote de contexto, workspace, planejamento, ação e verificação. Elas estão explicitamente fora da interface atual 0.3.6. Veja ../../architecture/README.md para o alvo e o plano de compatibilidade.

O catálogo autoritativo mapeia identificadores e slugs MCP atuais para IDs de requisito permanentes. O servidor 0.3.6 mantém sua interface de doze ferramentas, carrega o snapshot empacotado gerado, valida saai.catalog.v1 e reporta o hash compartilhado do snapshot.

Licença

Este servidor (o código neste diretório) é licenciado MIT — veja LICENSE.

O conteúdo do framework de segurança que ele serve (os padrões, critérios canônicos e heurísticas operacionais incluídos sob saferagenticai_mcp/_data/) faz parte do framework SaferAgenticAI, publicado sob CC-BY-4.0 na raiz do repositório. Atribuição: Nell Watson e a Comunidade de Prática de Segurança em IA Agêntica.