Tenets

Servidor MCP offline que ranqueia e resume código usando BM25, TF-IDF, embeddings e sinais do git; integra-se com Cursor, Claude Desktop e Windsurf; preserva a privacidade.

GitHub

Experimente este MCPPatrocinado

Documentação

tenets

Servidor MCP para contexto que alimenta seus prompts.

Agregação inteligente de contexto de código + injeção automática de princípios orientadores—100% local.

Nota de cobertura: Mede módulos principais (distiller, ranking, MCP, CLI, models). Recursos opcionais (viz, analisadores de linguagem) são excluídos.

tenets é um servidor MCP para assistentes de codificação com IA. Ele resolve dois problemas críticos:

Contexto Inteligente de Código — Encontra, classifica e agrega o código mais relevante usando NLP (BM25, TF-IDF, centralidade de imports, sinais de git). Chega de procurar arquivos manualmente.
Princípios Orientadores Automáticos — Injeta seus princípios (padrões de codificação, regras de arquitetura, requisitos de segurança) em cada prompt automaticamente. Evita a perda de contexto em conversas longas.

Integra-se nativamente com Cursor, Claude Desktop, Windsurf, VS Code via Model Context Protocol. Também inclui CLI e biblioteca Python. Processamento 100% local — sem custos de API, sem dados saindo da sua máquina.

O que é tenets?

Encontra todos os arquivos relevantes automaticamente usando análise NLP
Classifica por importância usando BM25, TF-IDF, embeddings de ML e sinais de git
Agrega dentro do seu orçamento de tokens com sumarização inteligente
Injeta princípios orientadores (tenets) automaticamente em cada prompt para consistência
Integra nativamente com assistentes de IA via Model Context Protocol (MCP)
Fixa arquivos críticos por sessão para inclusão garantida
Transforma conteúdo sob demanda (remove comentários, condensa espaços em branco ou força contexto bruto completo)

Quickstart MCP-first (recomendado)

Instalar + iniciar servidor MCP
```
pip install tenets[mcp]
tenets-mcp
```

Claude Code (extensão CLI / VS Code)

claude mcp add tenets -s user -- tenets-mcp

Ou adicione manualmente ao ~/.claude.json:

{ "mcpServers": { "tenets": { "type": "stdio", "command": "tenets-mcp", "args": [] } } }

Claude Desktop (app macOS - ~/Library/Application Support/Claude/claude_desktop_config.json)
```
{ "mcpServers": { "tenets": { "command": "tenets-mcp" } } }
```

Cursor (~/.cursor/mcp.json)

{ "mcpServers": { "tenets": { "command": "tenets-mcp" } } }

Windsurf (~/.windsurf/mcp.json)

{ "tenets": { "command": "tenets-mcp" } }

Extensão VS Code (alternativa para usuários de VS Code)
- Instalar do VS Code Marketplace ⭐
- Ou pesquise "Tenets MCP Server" nas Extensões do VS Code
- A extensão inicia o servidor automaticamente e fornece indicador de status + comandos
Docs (lista completa de ferramentas e transportes): https://tenets.dev/MCP/

Instalação (CLI/Python)

# Using pipx (recommended for CLI tools)
pipx install tenets[mcp]     # MCP server + CLI (recommended)
pipx install tenets          # CLI only (no MCP server)

# Or using pip
pip install tenets[mcp]      # Adds MCP server dependencies (REQUIRED for MCP)
pip install tenets           # CLI + Python, BM25/TF-IDF ranking (no MCP)
pip install tenets[light]    # RAKE/YAKE keyword extraction
pip install tenets[viz]      # Visualization features
pip install tenets[ml]       # ML embeddings / reranker (2GB+)
pip install tenets[all]      # Everything

Importante: O extra [mcp] é obrigatório para a funcionalidade do servidor MCP. Sem ele:

O executável tenets-mcp existe, mas falhará ao tentar executá-lo
Dependências ausentes: mcp, sse-starlette, uvicorn (15 pacotes adicionais)
Você receberá um erro claro: ImportError: MCP dependencies not installed

Superfície de Ferramentas MCP (assistentes de IA)

Iniciar o servidor MCP
```
pip install tenets[mcp]
tenets-mcp
```

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "tenets": { "command": "tenets-mcp" }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)
```
{
  "mcpServers": {
    "tenets": { "command": "tenets-mcp" }
  }
}
```
Ferramentas expostas: distill, rank, examine, session_*, tenet_*, além de search_tools + get_tool_schema para descoberta sob demanda.
Docs: veja docs/MCP.md para a lista completa de endpoints/ferramentas, detalhes de SSE/HTTP e notas de IDE.

Servidor MCP (integração com assistentes de IA)

Depois de iniciar o tenets-mcp e adicionar uma das configurações acima ao seu IDE, pergunte à sua IA:

"Use tenets para encontrar o código de autenticação" (chama distill)
"Fixe src/auth na sessão auth-feature" (chama session_pin_folder)
"Classifique arquivos para o bug de pagamento" (chama rank_files)

Veja docs MCP para transportes (stdio/SSE/HTTP), esquemas de ferramentas e exemplos completos.

Início Rápido

Três Modos de Classificação

Tenets oferece três modos que equilibram velocidade vs. precisão para os comandos distill e rank:

Modo	Velocidade	Precisão	Caso de Uso	O Que Faz
fast	Mais rápida	Boa	Exploração rápida	Correspondência de palavras-chave e caminhos, relevância básica
balanced	1,5x mais lenta	Melhor	Maioria dos casos (padrão)	Pontuação BM25, extração de palavras-chave, análise de estrutura
thorough	4x mais lenta	Melhor	Refatoração complexa	Similaridade semântica ML, detecção de padrões, grafos de dependências

Comandos Principais

`distill` - Construir Contexto com Conteúdo

# Basic usage - finds and aggregates relevant files
tenets distill "implement OAuth2"  # Searches current directory by default

# Search specific directory
tenets distill "implement OAuth2" ./src

# Copy to clipboard (great for AI chats)
tenets distill "fix payment bug" --copy

# Generate interactive HTML report
tenets distill "analyze auth flow" --format html -o report.html

# Speed/accuracy trade-offs
tenets distill "debug issue" --mode fast       # <5s, keyword matching
tenets distill "refactor API" --mode thorough  # Semantic analysis

# ML-enhanced ranking (requires pip install tenets[ml])
tenets distill "fix auth bug" --ml              # Semantic embeddings
tenets distill "optimize queries" --ml --reranker  # Neural reranking (best accuracy)

# Transform content to save tokens
tenets distill "review code" --remove-comments --condense

# Adjust timeout (default 120s; set 0 to disable)
tenets distill "implement OAuth2" --timeout 180

`rank` - Visualizar Arquivos Sem Conteúdo

# See what files would be included (much faster than distill!)
tenets rank "implement payments" --top 20  # Searches current directory by default

# Understand WHY files are ranked
tenets rank "fix auth" --factors

# Tree view for structure understanding
tenets rank "add caching" --tree --scores

# ML-enhanced ranking for better accuracy
tenets rank "fix authentication" --ml           # Uses semantic embeddings
tenets rank "database optimization" --ml --reranker  # Cross-encoder reranking

# Export for automation
tenets rank "database migration" --format json | jq '.files[].path'

# Search specific directory
tenets rank "payment refactoring" ./src --top 10

Sessões e Princípios Orientadores (Tenets)

O recurso matador: defina princípios orientadores uma vez, e eles são injetados automaticamente em cada prompt.

# Create a working session
tenets session create payment-feature

# Add guiding principles (tenets) — these auto-inject into all prompts
tenets tenet add "Always validate user inputs before database operations" --priority critical
tenets tenet add "Use Decimal for monetary calculations, never float" --priority high
tenets tenet add "Log all payment state transitions" --priority medium

# Pin critical files (guaranteed inclusion in context)
tenets session pin-file payment-feature src/core/payment.py

# Instill tenets to the session
tenets instill --session payment-feature

# Now every distill automatically includes your tenets + pinned files
tenets distill "add refund flow" --session payment-feature
# Output includes: relevant code + your 3 guiding principles

Por que isso importa: Em conversas longas com IA, o contexto se perde. A IA esquece seus padrões de codificação. Tenets resolve isso re-injetando suas regras toda vez.

Outros Comandos

# Visualize architecture
tenets viz deps --output architecture.svg   # Dependency graph
tenets viz deps --format html -o deps.html  # Interactive HTML

# Track development patterns
tenets chronicle --since "last week"        # Git activity
tenets momentum --team                      # Sprint velocity

# Analyze codebase
tenets examine . --complexity --threshold 10  # Find complex code

Configuração

Crie .tenets.yml no seu projeto:

ranking:
  algorithm: balanced # fast | balanced | thorough
  threshold: 0.1
  use_git: true # Use git signals for relevance

context:
  max_tokens: 100000

output:
  format: markdown
  copy_on_distill: true # Auto-copy to clipboard

ignore:
  - vendor/
  - '*.generated.*'

Como Funciona

Inteligência de análise de código

tenets emprega uma abordagem em múltiplas camadas otimizada especificamente para compreensão de código (mas sua funcionalidade principal pode ser aplicada a qualquer campo de correspondência de documentos). Ele tokeniza identificadores camelCase e snake_case de forma inteligente. Arquivos de teste são excluídos por padrão, a menos que sejam especificamente mencionados de alguma forma. Análise AST específica por linguagem para 15+ linguagens está incluída.

NLP de múltipla classificação

Algoritmos determinísticos em balanced funcionam de forma confiável e rápida, destinados ao uso padrão. A pontuação BM25 evita o viés de arquivos que podem usar padrões redundantes (arquivos de teste com "response" referenciado repetidamente não dominarão necessariamente buscas por "response").

Os fatores de classificação padrão consistem em: pontuação BM25 (25% - relevância estatística prevenindo viés de repetição), correspondência de palavras-chave (20% - correspondência direta de substrings), relevância de caminho (15%), similaridade TF-IDF (10%), centralidade de imports (10%), sinais de git (10% - recência 5%, frequência 5%), relevância de complexidade (5%) e relevância de tipo (5%).

Sumarização Inteligente

Quando arquivos excedem os orçamentos de tokens, tenets preserva inteligentemente:

Assinaturas de funções/classes
Declarações de import
Blocos de lógica complexa
Documentação e comentários
Alterações recentes

Embeddings de ML / deep learning

A compreensão semântica pode ser obtida com recursos de ML: pip install tenets[ml]. Ative com flags --ml --reranker ou defina use_ml: true e use_reranker: true na configuração.

No modo thorough, embeddings de sentence-transformer são habilitados, e entenda que authenticate() e login() são conceitualmente relacionados, por exemplo, e que payment até tem alguma sobreposição em relevância (já que normalmente são associados).

Re-classificação neural opcional com cross-encoder neste modo avalia conjuntamente pares consulta-documento com self-attention para precisão superior.

Um cross-encoder, por exemplo, classificará corretamente "DEPRECATED: We no longer implement oauth2" mais baixo que implement_authorization_flow() para a consulta "implement oauth2", entendendo o contexto negativo apesar das correspondências de palavras-chave.

Como cross-encoders processam pares documento-consulta juntos (complexidade O(n²)), eles são muito mais lentos que bi-encoders e são usados apenas para re-classificar os top K resultados.

Documentação

Documentação Completa - Guia completo e referência de API
Referência CLI - Todos os comandos e opções
Guia de Configuração - Opções de configuração detalhadas
Visão Geral da Arquitetura - Como tenets funciona internamente

Formatos de Saída

# Markdown (default, optimized for AI)
tenets distill "implement OAuth2" --format markdown

# Interactive HTML with search, charts, copy buttons
tenets distill "review API" --format html -o report.html

# JSON for programmatic use
tenets distill "analyze" --format json | jq '.files[0]'

# XML optimized for Claude
tenets distill "debug issue" --format xml

API Python

from tenets import Tenets

# Initialize
tenets = Tenets()

# Basic usage
result = tenets.distill("implement user authentication")
print(f"Generated {result.token_count} tokens")

# Rank files without content
from tenets.core.ranking import RelevanceRanker
ranker = RelevanceRanker(algorithm="balanced")
ranked_files = ranker.rank(files, prompt_context, threshold=0.1)

for file in ranked_files[:10]:
    print(f"{file.path}: {file.relevance_score:.3f}")

Linguagens Suportadas

Analisadores especializados para Python, JavaScript/TypeScript, Go, Java, C/C++, Ruby, PHP, Rust e mais. Arquivos de configuração e documentação são analisados com heurísticas inteligentes para YAML, TOML, JSON, Markdown, etc.

Contribuindo

Veja CONTRIBUTING.md para diretrizes.

Licença

Licença MIT - veja LICENSE para detalhes.

Documentação · Guia MCP · Privacidade · Termos

team@tenets.dev // team@manic.agency

Tenets

Documentação

tenets

O que é tenets?

Quickstart MCP-first (recomendado)

Instalação (CLI/Python)

Superfície de Ferramentas MCP (assistentes de IA)

Servidor MCP (integração com assistentes de IA)

Início Rápido

Três Modos de Classificação

Comandos Principais

distill - Construir Contexto com Conteúdo

rank - Visualizar Arquivos Sem Conteúdo

Sessões e Princípios Orientadores (Tenets)

Outros Comandos

Configuração

Como Funciona

Inteligência de análise de código

NLP de múltipla classificação

Sumarização Inteligente

Embeddings de ML / deep learning

Documentação

Formatos de Saída

API Python

Linguagens Suportadas

Contribuindo

Licença

`distill` - Construir Contexto com Conteúdo

`rank` - Visualizar Arquivos Sem Conteúdo