Tugra

tugra

Parte do VERAX, da VERAX Teknoloji. Comece pelo corpo do VERAX: verax-ai/verax. Projetos irmãos: Conarium · Cedulon.

Listado em: npm · Glama · MCP Registry · MCP Market · LobeHub

npx tugra init

Isso cria um cofre, grava um fato de exemplo e imprime um bloco de configuração. Cole o bloco no seu cliente MCP. Em um TTY, npx tugra imprime ajuda e sai. Em modo pipe (Claude Desktop, Cursor, Claude Code), é o servidor MCP.

Memória com proveniência para agentes de IA. Cada afirmação carrega sua fonte, sua idade e seu limite. Não há nuvem.

O que é

Um fato que não consegue nomear sua origem não é um fato. O Tugra armazena cada afirmação como um arquivo cujo frontmatter contém fonte, data da última verificação, validade e — quando o tópico é proibido — um limite que impede invenções. A busca classifica por pontuação de token, depois por frescor, depois por confiança. Fatos aposentados e estragados ficam fora do conjunto padrão.

Ferramentas

Ferramenta	O que faz
fact_search	Busca no cofre. Aposentados/estragados omitidos, exceto se archive: true.
fact_read	Lê um fato por uid. O corpo é escapado antes de o modelo vê-lo.
fact_propose	Grava um rascunho. Padrões de segredo são rejeitados antes de qualquer gravação. type: "boundary" é sempre colocado em quarentena.
event_report	Acrescenta uma linha de telemetria local. Sem rede.

Os nomes dos campos armazenados permanecem na forma nativa do cofre (kaynak, guven, raf_omru, sinir). Os nomes das ferramentas e parâmetros acima são o contrato público.

Instalação — caminhos de ambiente (opcional)

tugra init é suficiente para começar. Substitua os dois caminhos apenas se você já tiver um cofre em outro lugar. Sem eles, o servidor procura ao lado do pacote instalado — isso está errado para um npx puro sem init.

• TUGRA_VAULT — cofre (fatos em markdown)
• TUGRA_EVENTS — diretório de telemetria

Autorização: se nenhum armazenamento de autorização estiver configurado, o modo de usuário único está ativo — busca e proposta de trabalho funcionam sem perfil. Se um armazenamento de autorização estiver configurado (um diretório yetki/, ou TUGRA_AUTH), cada agente precisa de um perfil JSON ou a busca retorna não autorizado.

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_VAULT": "/absolute/path/to/vault",
        "TUGRA_EVENTS": "/absolute/path/to/events"
      }
    }
  }
}

Claude Code

.mcp.json na raiz do projeto, ou claude mcp add:

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_VAULT": "/absolute/path/to/vault",
        "TUGRA_EVENTS": "/absolute/path/to/events"
      }
    }
  }
}

Cursor

.cursor/mcp.json ou Configurações do Cursor → MCP:

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_VAULT": "/absolute/path/to/vault",
        "TUGRA_EVENTS": "/absolute/path/to/events"
      }
    }
  }
}

Windsurf

mcp_config.json:

{
  "mcpServers": {
    "tugra": {
      "command": "npx",
      "args": ["-y", "tugra"],
      "env": {
        "TUGRA_VAULT": "/absolute/path/to/vault",
        "TUGRA_EVENTS": "/absolute/path/to/events"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.tugra]
command = "npx"
args = ["-y", "tugra"]

[mcp_servers.tugra.env]
TUGRA_VAULT = "/absolute/path/to/vault"
TUGRA_EVENTS = "/absolute/path/to/events"

Windows: use um caminho completo (C:\\Users\\…\\vault). Node 20 ou mais recente.

Mais notas sobre clientes: docs/install.md.

Autorização de cofre compartilhado (opcional)

Configurações de usuário único não precisam disso. Adicione TUGRA_AUTH apenas quando vários agentes compartilham um cofre e cada um precisa do seu próprio perfil (mcp-readonly@tugra e outros como arquivos JSON nesse diretório). Um perfil ausente então retorna não autorizado. Um TUGRA_AUTH vazio é tratado como não definido — o modo de usuário único permanece ativo.

Superfície da biblioteca do host (não o wire do MCP)

As ferramentas MCP (fact_search, fact_read, fact_propose, event_report) aplicam autorização em cada chamada. O pacote publicado também inclui dist-paket/akis.js e dist-paket/yetki.js para que um aplicativo host (cron, espelho, cockpit) possa gravar telemetria sem passar por JSON-RPC.

Esses módulos são públicos de propósito. akisBildir({ atlaYetki: true }), eylem: "yetki_talebi" e dosyaYoksaIzin (padrão verdadeiro) pulam ou relaxam a verificação. harcamaEkle altera um perfil. O host que os importa é dono da autorização. O wire do MCP não pode definir essas flags — o esquema da ferramenta não as aceita.

Cofre de escala vs cofre de destino

Os níveis A0–A5 são fatos (yonetisim.yetki.a0 … a5) em um cofre. O servidor stdio os lê de TUGRA_VAULT, ou do cockpit kasa/ quando essa variável não está definida.

tugraArac / createTugraMcp aceitam um kasaKok opcional (o destino de gravação/busca). A escala não segue esse destino. Ela usa por padrão varsayilanKasa() — o mesmo cofre central que o servidor stdio usa. Um host que aponta kasaKok para uma árvore somente de dados continua usando a escala do cockpit / TUGRA_VAULT. Para ler a escala de uma árvore diferente, passe skalaKasa explicitamente.

Todas as quatro ferramentas compartilham um resolvedor. Este é o contrato: destino separado + governança central permanece acessível. YAYIN/12 brevemente definiu a escala padrão como kasaKok; isso quebrou o host de raiz dividida. YAYIN/13 restaura o padrão central.

O que não garantimos

• Sem sincronização em nuvem. O cofre são os arquivos que você apontou. Nada é enviado.
• Sem mesclagem automática. Dois gravadores, dois arquivos. Você reconcilia.
• Sem exclusão nesta versão. Aposentadoria existe; apagamento vem depois.
• Sem detecção automática de conflitos. Fatos contraditórios podem coexistir até que um humano decida.
• Sem serviço hospedado. npx tugra é um processo stdio local.

Este pacote não é publicado como SaaS. Não há tabela de preços aqui.

Requisitos

• Node.js 20 ou mais recente. Esta é uma decisão de suporte, não um piso técnico: o pacote é testado nas versões 20 e 22 no CI, e também roda na 18 — mas a 18 passou do fim da vida útil, então não a suportamos.
• Um diretório de cofre que você possua

Mapa de tópicos (opcional)

<vault>/_konu-haritasi.json — regras { "desen", "bayrak", "konu" } em harita, alt_kirilim e stem. Se o arquivo estiver ausente, o mapa fica vazio: texto desconhecido cai em kurum.genel ou dunya.<world>.genel. Padrões quebrados ou longos demais são ignorados e registrados. Este pacote não inclui uma taxonomia empresarial.

Licença

Apache-2.0. Veja LICENSE e NOTICE.

A página de marketing vive em ../site/ (npm run preview lá). Ela não é implantada a partir deste pacote.

Compatibilidade: TUGRA_KASA, TUGRA_AKIS, TUGRA_YETKI (e os nomes mais antigos TALAMUS_* / MULTI_*) ainda funcionam como fallback quando o nome em inglês não está definido.