Tenets

Servidor MCP offline que clasifica y resume código usando BM25, TF-IDF, embeddings y señales de git; se integra con Cursor, Claude Desktop y Windsurf; preserva la privacidad.

GitHub

Prueba este MCPPatrocinado

Documentación

tenets

Servidor MCP para contexto que alimenta tus prompts.

Agregación inteligente de contexto de código + inyección automática de principios rectores—100% local.

Nota de cobertura: Mide los módulos principales (distiller, ranking, MCP, CLI, models). Las funciones opcionales (viz, language analyzers) están excluidas.

tenets es un servidor MCP para asistentes de codificación con IA. Resuelve dos problemas críticos:

Contexto de Código Inteligente — Encuentra, clasifica y agrega el código más relevante usando NLP (BM25, TF-IDF, centralidad de imports, señales de git). No más búsqueda manual de archivos.
Principios Rectores Automáticos — Inyecta tus tenets (estándares de codificación, reglas de arquitectura, requisitos de seguridad) en cada prompt automáticamente. Previene la deriva de contexto en conversaciones largas.

Se integra nativamente con Cursor, Claude Desktop, Windsurf, VS Code mediante Model Context Protocol. También incluye una CLI y una biblioteca de Python. Procesamiento 100% local — sin costos de API, sin que tus datos salgan de tu máquina.

¿Qué es tenets?

Encuentra todos los archivos relevantes automáticamente usando análisis NLP
Clasifica por importancia usando BM25, TF-IDF, ML embeddings y señales de git
Agrega dentro de tu presupuesto de tokens con resumen inteligente
Inyecta principios rectores (tenets) automáticamente en cada prompt para mantener la consistencia
Se integra nativamente con asistentes de IA mediante Model Context Protocol (MCP)
Fija archivos críticos por sesión para garantizar su inclusión
Transforma contenido bajo demanda (elimina comentarios, condensa espacios en blanco o fuerza contexto crudo completo)

Inicio rápido con MCP primero (recomendado)

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

Claude Code (CLI / extensión de VS Code)

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

O añade manualmente a ~/.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" } }

Extensión de VS Code (alternativa para usuarios de VS Code)
- Instalar desde VS Code Marketplace ⭐
- O busca "Tenets MCP Server" en las extensiones de VS Code
- La extensión inicia automáticamente el servidor y proporciona indicador de estado + comandos
Docs (lista completa de herramientas y transportes): https://tenets.dev/MCP/

Instalación (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: El extra [mcp] es requerido para la funcionalidad del servidor MCP. Sin él:

El ejecutable tenets-mcp existe pero fallará cuando intentes ejecutarlo
Dependencias faltantes: mcp, sse-starlette, uvicorn (15 paquetes adicionales)
Recibirás un error claro: ImportError: MCP dependencies not installed

Superficie de Herramientas MCP (asistentes de IA)

Iniciar el 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" }
  }
}
```
Herramientas expuestas: distill, rank, examine, session_*, tenet_*, más search_tools + get_tool_schema para descubrimiento bajo demanda.
Docs: consulta docs/MCP.md para la lista completa de endpoints/herramientas, detalles SSE/HTTP y notas de IDE.

Servidor MCP (integración con asistentes de IA)

Una vez que inicies tenets-mcp y coloques una de las configuraciones anteriores en tu IDE, pregúntale a tu IA:

"Usa tenets para encontrar el código de autenticación" (llama a distill)
"Fija src/auth a la sesión auth-feature" (llama a session_pin_folder)
"Clasifica archivos para el bug de pagos" (llama a rank_files)

Consulta docs de MCP para transportes (stdio/SSE/HTTP), esquemas de herramientas y ejemplos completos.

Inicio Rápido

Tres Modos de Clasificación

Tenets ofrece tres modos que equilibran velocidad vs. precisión para los comandos distill y rank:

Modo	Velocidad	Precisión	Caso de Uso	Qué Hace
fast	La más rápida	Buena	Exploración rápida	Coincidencia de palabras clave y rutas, relevancia básica
balanced	1.5x más lenta	Mejor	La mayoría de casos de uso (predeterminado)	Puntuación BM25, extracción de palabras clave, análisis de estructura
thorough	4x más lenta	La mejor	Refactorización compleja	Similitud semántica ML, detección de patrones, grafos de dependencias

Comandos Principales

`distill` - Construir Contexto con Contenido

# 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` - Previsualizar Archivos Sin Contenido

# 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

Sesiones y Principios Rectores (Tenets)

La función estrella: define principios rectores una vez, y se inyectan automáticamente en 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 qué importa: En conversaciones largas con IA, el contexto se desvía. La IA olvida tus estándares de codificación. Tenets resuelve esto reinyectando tus reglas cada vez.

Otros 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

Configuración

Crea .tenets.yml en tu proyecto:

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.*'

Cómo Funciona

Inteligencia de análisis de código

tenets emplea un enfoque multicapa optimizado específicamente para la comprensión de código (pero su funcionalidad principal podría aplicarse a cualquier campo de coincidencia de documentos). Tokeniza identificadores de camelCase y snake_case de forma inteligente. Los archivos de prueba se excluyen por defecto a menos que se mencionen específicamente de alguna manera. Se incluye análisis AST específico por lenguaje para 15+ lenguajes.

NLP de clasificación múltiple

Los algoritmos deterministas en balanced funcionan de manera confiable y rápida, pensados para usarse por defecto. La puntuación BM25 evita el sesgo de archivos que pueden usar patrones redundantes (los archivos de prueba que podrían tener "response" referenciado una y otra vez no necesariamente dominarán las búsquedas de "response").

Los factores de clasificación predeterminados consisten en: puntuación BM25 (25% - relevancia estadística que previene el sesgo por repetición), coincidencia de palabras clave (20% - coincidencia directa de subcadenas), relevancia de ruta (15%), similitud TF-IDF (10%), centralidad de imports (10%), señales de git (10% - actualidad 5%, frecuencia 5%), relevancia de complejidad (5%) y relevancia de tipo (5%).

Resumen Inteligente

Cuando los archivos exceden los presupuestos de tokens, tenets preserva inteligentemente:

Firmas de funciones/clases
Declaraciones de import
Bloques de lógica compleja
Documentación y comentarios
Cambios recientes

Embeddings de ML / deep learning

La comprensión semántica se puede lograr con funciones de ML: pip install tenets[ml]. Habilítalas con las banderas --ml --reranker o configura use_ml: true y use_reranker: true en la configuración.

En el modo thorough, los embeddings de sentence-transformer están habilitados, y comprende que authenticate() y login() están conceptualmente relacionados, por ejemplo, y que payment incluso tiene cierta superposición en relevancia (ya que típicamente se asocian entre sí).

Re-clasificación neuronal opcional con cross-encoder en este modo evalúa conjuntamente pares consulta-documento con self-attention para una precisión superior.

Un cross-encoder, por ejemplo, clasificará correctamente "DEPRECATED: We no longer implement oauth2" más abajo que implement_authorization_flow() para la consulta "implement oauth2", comprendiendo el contexto negativo a pesar de las coincidencias de palabras clave.

Dado que los cross-encoders procesan pares documento-consulta juntos (complejidad O(n²)), son mucho más lentos que los bi-encoders y solo se usan para re-clasificar los K mejores resultados.

Documentación

Documentación Completa - Guía completa y referencia de API
Referencia CLI - Todos los comandos y opciones
Guía de Configuración - Opciones de configuración detalladas
Resumen de Arquitectura - Cómo funciona tenets internamente

Formatos de Salida

# 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

Python API

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}")

Lenguajes Soportados

Analizadores especializados para Python, JavaScript/TypeScript, Go, Java, C/C++, Ruby, PHP, Rust y más. Los archivos de configuración y documentación se analizan con heurísticas inteligentes para YAML, TOML, JSON, Markdown, etc.

Contribuciones

Consulta CONTRIBUTING.md para las pautas.

Licencia

Licencia MIT - consulta LICENSE para más detalles.

Documentación · Guía MCP · Privacidad · Términos

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

Tenets

Documentación

tenets

¿Qué es tenets?

Inicio rápido con MCP primero (recomendado)

Instalación (CLI/Python)

Superficie de Herramientas MCP (asistentes de IA)

Servidor MCP (integración con asistentes de IA)

Inicio Rápido

Tres Modos de Clasificación

Comandos Principales

distill - Construir Contexto con Contenido

rank - Previsualizar Archivos Sin Contenido

Sesiones y Principios Rectores (Tenets)

Otros Comandos

Configuración

Cómo Funciona

Inteligencia de análisis de código

NLP de clasificación múltiple

Resumen Inteligente

Embeddings de ML / deep learning

Documentación

Formatos de Salida

Python API

Lenguajes Soportados

Contribuciones

Licencia

`distill` - Construir Contexto con Contenido

`rank` - Previsualizar Archivos Sin Contenido