Snipara

MCP hospedado para inteligência de projetos, contexto com base no código-fonte, memória revisada e ferramentas de grafo de código.

GitHubExperimente este MCPPatrocinado

Documentação

snipara-mcp

snipara-mcp é o conector MCP stdio leve para o Project Brain do Snipara.

Snipara é o Project Brain para agentes de codificação com IA.

Use-o quando um cliente MCP precisar de um processo stdio local que converse com as APIs hospedadas de Project Intelligence do Snipara. O Snipara fornece ao Claude Code, Cursor, Codex e outros clientes MCP as decisões, o trabalho ativo, o impacto no código, as evidências e as transferências de contexto de que precisam antes de editar. Se o seu cliente suportar MCP HTTP streamable diretamente, prefira o endpoint hospedado e pule o processo local.

O Que É o Snipara?

O Snipara é a camada compartilhada de Project Intelligence para trabalho de software assistido por IA.

Ele fornece ao Claude Code, Cursor, Codex, OpenAI Agents e outros clientes compatíveis com MCP um contexto de projeto que sobrevive a sessões, usuários, ferramentas e trocas de modelo.

Seu agente ainda usa o próprio LLM. O Snipara fornece o contexto de projeto correto: documentação com base em fontes, memória revisada, orientação compartilhada, continuidade de fluxo de trabalho e estrutura do grafo de código. Em termos de categoria, é uma plataforma de contexto, memória e continuidade para agentes de codificação com IA.

Por Que MCP?

O MCP está se tornando uma camada de adaptador padrão para ferramentas de agente. O snipara-mcp disponibiliza o Snipara por meio dessa camada sem forçar os desenvolvedores a um IDE, modelo ou estrutura de orquestração específicos.

A integração deve parecer pequena:

uvx snipara-mcp

O impacto é maior: os agentes podem recuperar contexto durável do projeto em vez de começar do zero a cada sessão.

O Que Ele Desbloqueia

Necessidade	Grupo de ferramentas MCP do Snipara
Fazer perguntas com base em fontes à documentação do projeto	`snipara_context_query`, `snipara_get_chunk`
Recuperar decisões duráveis e aprendizados	`snipara_recall`
Revisar a Inbox da equipe	`snipara_inbox_review_queue`, `snipara_inbox_review_plan`, `snipara_inbox_review_apply`
Persistir memória reutilizável após uma tarefa	`snipara_remember_if_novel`, `snipara_end_of_task_commit`
Reutilizar padrões da equipe e orientação compartilhada	`snipara_shared_context`
Inspecionar relações estruturais de código	`snipara_code_callers`, `snipara_code_imports`, `snipara_code_neighbors`
Planejar mudanças de código arriscadas	`snipara_code_symbol_card`, `snipara_code_impact` dentro da capacidade do plano

Clientes MCP públicos devem usar os nomes snipara_*. Os aliases de compatibilidade rlm_* foram removidos do contrato distribuído em 2026-08-16 e permanecem apenas como identificadores internos de manipuladores. Essa limpeza de contrato está programada para a próxima versão do pacote; clientes que usam nomes legados devem migrar antes de atualizar.

O servidor stdio anuncia o mesmo contrato de agente padrão compacto que o endpoint MCP hospedado. Defina SNIPARA_TOOL_PROFILE=full apenas para clientes que precisam de descoberta direta de todas as ferramentas especializadas de compatibilidade; ferramentas ocultas permanecem chamáveis por nome explícito e descobríveis por meio de snipara_help.

A superfície de descoberta padrão contém 13 ferramentas coerentes: snipara_context_query, snipara_ask, snipara_search, snipara_read, snipara_stats, snipara_help, snipara_get_chunk, snipara_recall, snipara_remember_if_novel, snipara_end_of_task_commit, snipara_inbox_review_queue, snipara_inbox_review_plan e snipara_inbox_review_apply.

Revisão de mudança mínima segura (2.8.30)

Os contratos empacotados snipara_context_query e snipara_code_impact agora aceitam minimum_change_mode="review". Quando habilitado, pacotes de resposta e respostas de impacto carregam um recibo não bloqueante, priorizando evidências, cobrindo capacidades existentes, opções stdlib/nativas, dependências instaladas, o menor diff seguro e a preservação da superfície de validação. A política é consultiva e permanece opt-in até que as evidências do projeto calibrem uma aplicação mais forte.

Os chamadores podem fornecer minimum_change_evidence limitados com proveniência nomeada, como runtime, manifest, lockfile, git_diff ou test_runner. Alegações não verificadas de confirmed permanecem visíveis como asserted; confirmed é reservado para um recibo de adaptador versionado com correspondência de impressão digital. Os adaptadores verificados são lockfile_manifest para dependências instaladas diretamente e git_diff para uma verificação local coerente do menor diff seguro. As respostas também incluem guardas de preservação não bloqueantes para validação, erros, autenticação/segurança, acessibilidade, contratos públicos e testes.

Contrato de regras semânticas (2.8.27)

Os esquemas gerados snipara_code_symbol_card e snipara_code_impact agora encaminham substituições limitadas de projeto semantic_rules para o serviço hospedado. Os termos são strings literais, não expressões regulares executáveis.

Piso de segurança de transporte MCP (2.8.26)

O conector agora exige MCP Python SDK 1.28.1 ou mais recente. Isso incorpora as correções upstream para isolamento de sessão de principal autenticado, propriedade experimental de tarefas e validação de Host/Origin do WebSocket.

Travessia configurável de impacto no código (2.8.25)

O contrato empacotado snipara_code_impact agora expõe depth (1-6), direction (in, out ou both) e edge_kinds opcional. Isso mantém o contrato do conector alinhado com cadeias de impacto hospedadas e os controles de travessia híbrida local/hospedada do Companion.

Descoberta sem credenciais e contrato compacto (2.8.24)

Clientes MCP e inspetores de diretório agora podem concluir initialize e tools/list antes que as credenciais sejam configuradas. Toda chamada real de ferramenta ainda falha de forma fechada até que autenticação e seleção de projeto estejam presentes. A resposta padrão tools/list expõe o mesmo núcleo de 13 ferramentas do Snipara hospedado, enquanto SNIPARA_TOOL_PROFILE=full mantém a descoberta direta de todas as ferramentas especializadas de compatibilidade. As ferramentas principais agora incluem orientação completa de seleção, anotações de comportamento e documentação aninhada de parâmetros para uso mais seguro pelos agentes.

Contratos de ferramentas legíveis por agentes (2.8.23)

O conector agora preserva descrições detalhadas de ferramentas e anotações de comportamento MCP da fonte de verdade hospedada. Ferramentas de resumo, coordenação, estado, memória e grafo de código explicam seus pré-requisitos, regras de acesso, efeitos colaterais, idempotência, alternativas, parâmetros, saídas e modos comuns de falha para que os agentes possam escolhê-las com segurança. Esquemas nativos de saída permanecem adiados até que o transporte e o formato de resultado estruturado sejam atualizados juntos.

Revisão unificada da Inbox conversacional (2.8.22)

Administradores humanos de equipe podem listar os mesmos candidatos de memória e rascunhos ProjectDecision mostrados pela Inbox do Dashboard multi-projeto, criar recomendações com base em evidências de aprovar/rejeitar/necessita-humano e aplicar atomicamente um snapshot explicitamente autorizado. O serviço revalida a identidade do administrador humano da equipe, a propriedade do projeto, os estados atuais dos candidatos e snapshots imutáveis de itens antes de registrar auditorias de autoridade. Credenciais reais permanecem endereçáveis para rejeição, mas são redigidas da saída MCP. As ferramentas anteriores exclusivas do ProjectDecision permanecem disponíveis como ferramentas especializadas de compatibilidade.

Revisão conversacional de decisões (2.8.21)

Os agentes podem listar rascunhos pendentes de ProjectDecision, propor recomendações com base em evidências de aprovar/rejeitar/necessita-humano e aplicar um plano vinculado a snapshot explicitamente autorizado. A aplicação exige um administrador humano do projeto e falha de forma fechada se um rascunho mudar após o planejamento; não há aprovação curinga em tempo real.

Commits estruturados de captura de "Porquê" (2.8.20)

snipara_end_of_task_commit agora aceita um bloco atômico why com decision, rationale, alternatives, constraints e observed_outcome. Candidatos estruturados permanecem pendentes até revisão humana, e parâmetros desconhecidos falham de forma fechada em vez de serem silenciosamente ignorados.

Controles de resultado de recuperação (2.8.19)

O conector stdio encaminha os controles limitados de resultado de recuperação do servidor hospedado para context_query e recall: correlação opcional de tarefas, solicitações de rerank em modo sombra ou habilitado, e a janela estrita de atribuição de contexto. O servidor hospedado permanece autoritativo, então uma solicitação do cliente pode reduzir ou desabilitar o modo configurado, mas não pode escaloná-lo.

Arquitetura

flowchart LR
    Agents["Claude Code, Cursor, Codex, ChatGPT, OpenAI agents"] --> Stdio["snipara-mcp stdio process"]
    Stdio --> Hosted["Hosted Snipara MCP API"]
    Hosted --> Context["Context engine"]
    Hosted --> Memory["Project memory"]
    Hosted --> Graph["Code graph"]
    Context --> AgentLLM["Agent's own LLM"]
    Memory --> AgentLLM
    Graph --> AgentLLM

HTTP Hospedado Ou Stdio?

Use o endpoint HTTP hospedado quando seu cliente MCP suportar HTTP streamable:

{
  "mcpServers": {
    "snipara": {
      "type": "http",
      "url": "https://api.snipara.com/mcp/your-project-id-or-slug",
      "headers": {
        "Authorization": "Bearer snp-your-key"
      }
    }
  }
}

Use snipara-mcp quando seu cliente esperar um comando stdio local:

{
  "mcpServers": {
    "snipara": {
      "command": "uvx",
      "args": ["snipara-mcp"],
      "env": {
        "SNIPARA_API_KEY": "snp-your-key",
        "SNIPARA_PROJECT_ID": "your-project-id-or-slug"
      }
    }
  }
}

Regra de decisão:

HTTP MCP primeiro para clientes modernos
snipara-mcp para clientes somente stdio ou compatibilidade local
create-snipara quando você quiser configuração guiada entre clientes e modelos

Instalação

Sem instalação local:

uvx snipara-mcp

Pacote Python:

pip install snipara-mcp

Com integração do helper RLM Runtime:

pip install "snipara-mcp[rlm]"

Início Rápido

Entre pelo navegador:

pip install snipara-mcp
snipara login

Inicialize um projeto:

snipara init

O inicializador detecta arquivos comuns de projeto, escreve a configuração MCP e pode enviar documentação local do projeto quando você estiver autenticado.

Opções úteis:

snipara init --slug my-project
snipara init --dry-run
snipara init --no-upload
snipara init --skip-test

Claude Code

claude mcp add snipara uvx snipara-mcp

Depois exporte as credenciais no seu shell:

export SNIPARA_API_KEY="snp-your-key"
export SNIPARA_PROJECT_ID="your-project-id-or-slug"

Cursor

Adicione ao ~/.cursor/mcp.json:

{
  "mcpServers": {
    "snipara": {
      "command": "uvx",
      "args": ["snipara-mcp"],
      "env": {
        "SNIPARA_API_KEY": "snp-your-key",
        "SNIPARA_PROJECT_ID": "your-project-id-or-slug"
      }
    }
  }
}

Ambiente

Variável	Obrigatória	Descrição
`SNIPARA_API_KEY`	Sim, a menos que use `snipara login`	Chave da API do Snipara
`SNIPARA_PROJECT_ID`	Sim, a menos que use `SNIPARA_PROJECT_SLUG`	Identificador do projeto
`SNIPARA_PROJECT_SLUG`	Sim, a menos que use `SNIPARA_PROJECT_ID`	Slug do projeto
`SNIPARA_API_URL`	Não	Padrão para `https://api.snipara.com`
`SNIPARA_TOOL_PROFILE`	Não	`core` por padrão; `full` expõe esquemas de ferramentas especializadas

Tokens OAuth criados por snipara login são armazenados em ~/.snipara/tokens.json. Se um id ou slug de projeto for definido, o conector seleciona o token correspondente e não faz fallback silencioso para outro projeto.

O Que Você Obtém

O conector expõe o mesmo contrato MCP padrão compacto que o backend hospedado. A superfície completa empacotada de compatibilidade é gerada a partir da fonte de verdade do servidor e está disponível com SNIPARA_TOOL_PROFILE=full.

Grupos comuns de ferramentas:

recuperação: snipara_context_query, snipara_search, snipara_get_chunk, snipara_load_document
memória durável: snipara_recall, snipara_remember, snipara_memory_compact
bootstrap ciente do proprietário: snipara_session_memories, snipara_owner_profile_get, snipara_owner_profile_update
contexto compartilhado: snipara_shared_context, ferramentas de coleção e modelo
upload de documentos: snipara_upload_document, snipara_sync_documents
configuração de projeto: ferramentas de workspace de cliente, projeto e contexto de negócios
operações: snipara_settings, snipara_index_health, snipara_reindex
grafo de código: ferramentas snipara_code_* quando índices de código estão disponíveis
coordenação: ferramentas de swarm, tarefas hierárquicas e estado quando habilitadas

A disponibilidade de ferramentas pode variar por plano, implantação hospedada e estado do índice do projeto.

Comandos CLI

Comando	Descrição
`snipara login`	Login no navegador e configuração de token
`snipara init`	Inicializa o Snipara no projeto atual
`snipara logout`	Limpa tokens armazenados
`snipara status`	Mostra status de autenticação e projeto
`snipara-mcp`	Executa o servidor MCP stdio
Aliases legados como `snipara-init`, `snipara-mcp-login`,
`snipara-mcp-logout` e `snipara-mcp-status` ainda são suportados.

Relação com Outros Repositórios

Repositório	Papel
`alopez3006/snipara-mcp`	Espelho público atual do conector gerado
`Snipara/snipara-companion`	CLI local de fluxo de trabalho, impacto, verificação e handoff
`Snipara/snipara-memory`	Primitivas de memória abertas e esquema

snipara-mcp é intencionalmente enxuto. Deve ser fácil de instalar, fácil de auditar e monótono de operar. O trabalho pesado permanece no contexto hospedado e no mecanismo de memória do Snipara.

Desenvolvimento

pip install -e ".[dev]"
pytest
ruff check .

A fonte da verdade para o contrato de ferramentas gerado vive no servidor Snipara. Quando as ferramentas de backend mudarem, regenere o contrato empacotado antes de publicar este pacote.

Licença

MIT. Consulte LICENSE.