Tribal - Servicio de Conocimiento

Tribal es una implementación de servidor MCP (Protocolo de Contexto de Modelo) para el seguimiento y la recuperación de conocimiento de errores. Ofrece API REST e interfaces MCP nativas para la integración con herramientas como Claude Code y Cline.

Características

Almacenar y recuperar registros de errores con contexto completo
Búsqueda de similitud de vectores usando ChromaDB
API REST (FastAPI) e interfaces MCP nativas
Autenticación JWT con claves API
Almacenamiento local (ChromaDB) e integración con AWS
Implementación de Docker-compose
Integración del cliente CLI

Related MCP server: MCP Claude Code

Descripción general

Tribal ayuda a Claude a recordar y aprender de los errores de programación. Al iniciar una sesión de Claude Code, Tribal está disponible automáticamente a través de MCP sin necesidad de importaciones adicionales.

Claude querrá:

Errores de programación de la tienda y soluciones
Busque errores similares cuando encuentre problemas
Cree una base de conocimientos específica para sus patrones de codificación

Embalaje e instalación de Tribal con uv

Prerrequisitos

Python 3.12+
Gestor de paquetes uv (recomendado)

Pasos de construcción e instalación

Opción 1: Instalación directa con uv

El enfoque más simple es instalar directamente desde el directorio actual:

# From the project root directory
cd /path/to/tribal

# Install using uv
uv pip install .

Opción 2: Instalación de desarrollo

Para trabajos de desarrollo donde desea que los cambios se reflejen inmediatamente:

# From the project root directory
cd /path/to/tribal

# Install in development mode
uv pip install -e .

Opción 3: Construya el paquete primero

Si desea crear un paquete distribuible:

# Make sure you're in the project root directory
cd /path/to/tribal

# Install the build package if needed
uv pip install build

# Build the package
python -m build

# This creates distribution files in the dist/ directory
# Now install the wheel file
uv pip install dist/tribal-0.1.0-py3-none-any.whl

Opción 4: Usar el comando `uv tool install`

También puede utilizar el método de instalación de herramientas:

# Install as a global tool
cd /path/to/tribal
uv tool install .

# Or install in development mode
uv tool install -e .

Verificación

Después de la instalación, verifique que la herramienta esté correctamente instalada:

# Check the installation
which tribal

# Check the version
tribal version

Integración con Claude

Después de la instalación, puedes integrarlo con Claude:

# Add Tribal to Claude Code
claude mcp add tribal --launch "tribal"

# Verify the configuration
claude mcp list

# For Docker container
claude mcp add tribal http://localhost:5000

Uso

Herramientas MCP disponibles

Tribal proporciona estas herramientas MCP:

add_error - Crea un nuevo registro de error (POST/errors)
get_error - Recuperar error por UUID (GET /errors/{id})
update_error - Modificar el error existente (PUT /errors/{id})
delete_error - Eliminar registro de error (DELETE /errors/{id})
search_errors - Buscar errores por criterios (GET /errors)
find_similar - Búsqueda de similitud semántica (GET /errors/similar)
get_token - Obtener el token JWT (POST /token)

Ejemplo de uso con Claude

Cuando Claude encuentra un error:

I'll track this error and look for similar problems in our knowledge base.

Cuando Claude encuentra una solución:

I've found a solution! I'll store this in our knowledge base for next time.

Órdenes para Claude

Puedes pedirle a Claude que:

Busque errores similares en nuestra base de conocimientos tribales.
"Guarde esta solución en nuestra base de datos de errores"
"Comprobar si hemos visto este error antes"

Ejecución del servidor

Usando el comando tribal

# Run the server
tribal

# Get help
tribal help

# Show version
tribal version

# Run with options
tribal server --port 5000 --auto-port

Uso de módulos de Python

# Run the Tribal server
python -m mcp_server_tribal.mcp_app

# Run the FastAPI backend server
python -m mcp_server_tribal.app

Uso de puntos de entrada heredados

# Legacy MCP server
mcp-server

# Legacy FastAPI server
mcp-api

Opciones de la línea de comandos

# Development mode with auto-reload
mcp-api --reload
mcp-server --reload

# Custom port
mcp-api --port 8080
mcp-server --port 5000

# Auto port selection
mcp-api --auto-port
mcp-server --auto-port

El servidor FastAPI estará disponible en http://localhost:8000 con la documentación de la API en /docs. El servidor MCP estará disponible en http://localhost:5000 para Claude y otros LLM compatibles con MCP.

Variables de entorno

Servidor FastAPI

PERSIST_DIRECTORY : Ruta de almacenamiento de ChromaDB (predeterminado: "./chroma_db")
API_KEY : Clave de autenticación (predeterminada: "dev-api-key")
SECRET_KEY : Clave de firma JWT (valor predeterminado: "insecure-dev-key-change-in-production")
REQUIRE_AUTH : Requisito de autenticación (predeterminado: "falso")
PORT : Puerto del servidor (predeterminado: 8000)

Servidor MCP

MCP_API_URL : URL del servidor FastAPI (predeterminado: " http://localhost:8000 ")
MCP_PORT : puerto del servidor MCP (predeterminado: 5000)
MCP_HOST : Host al que vincular (predeterminado: "0.0.0.0")
API_KEY : Clave de acceso de FastAPI (predeterminada: "dev-api-key")
AWS_ACCESS_KEY_ID , AWS_SECRET_ACCESS_KEY , AWS_S3_BUCKET : para la integración con AWS

Puntos finales de API

POST /errors : Crear nuevo registro de errores
GET /errors/{error_id} : Obtener el error por ID
PUT /errors/{error_id} : Actualizar registro de errores
DELETE /errors/{error_id} : Eliminar error
GET /errors : Buscar errores por criterios
GET /errors/similar : Encuentra errores similares
POST /token : Obtener el token de autenticación

Uso del cliente

# Add a new error record
mcp-client --action add --error-type ImportError --language python --error-message "No module named 'requests'" --solution-description "Install requests" --solution-explanation "You need to install the requests package"

# Get an error by ID
mcp-client --action get --id <error-id>

# Search for errors
mcp-client --action search --error-type ImportError --language python

# Find similar errors
mcp-client --action similar --query "ModuleNotFoundError: No module named 'pandas'"

Cómo funciona

Tribal utiliza ChromaDB para almacenar registros de errores y soluciones
Cuando Claude encuentra un error, envía los detalles del error a Tribal.
Tribal vectoriza el error y busca otros similares
Claude recupera soluciones relevantes para sugerir
Las nuevas soluciones se almacenan para futuras referencias.

Desarrollo

Ejecución de pruebas

pytest
pytest tests/path_to_test.py::test_name  # For specific tests

Comprobación de tipo y desbastado

ruff check .
mypy .
black .

Flujo de trabajo de GitHub

Este proyecto utiliza GitHub Actions para la integración y el despliegue continuos. El flujo de trabajo ejecuta automáticamente pruebas, análisis de errores y verificación de tipos en las solicitudes de inserción y extracción.

Pasos del flujo de trabajo

Prueba : ejecuta pelusa, verificación de tipos y pruebas unitarias
- Utiliza Python 3.12
- Instala dependencias con uv
- Ejecuta ruff, black, mypy y pytest
Construir y publicar : construye y publica el paquete en PyPI
- Se activa solo al enviar a la rama principal
- Utiliza el sistema de compilación de Python
- Publica en PyPI usando twine

Pruebas locales

Puede probar el flujo de trabajo de GitHub localmente utilizando el script proporcionado:

# Make the script executable
chmod +x scripts/test-workflow.sh

# Run the workflow locally
./scripts/test-workflow.sh

Este script simula los pasos del flujo de trabajo de GitHub en su máquina local:

Comprueba la versión de Python (se recomienda 3.12)
Instala dependencias usando uv
Se corre con pelusa
Comprueba el formato con negro
Ejecuta la verificación de tipos con mypy
Ejecuta pruebas con pytest
Construye el paquete

Nota: el script omite el paso de publicación para las pruebas locales.

Estructura del proyecto

tribal/
├── src/
│   ├── mcp_server_tribal/      # Core package
│   │   ├── api/                # FastAPI endpoints
│   │   ├── cli/                # Command-line interface
│   │   ├── models/             # Pydantic models
│   │   ├── services/           # Service layer
│   │   │   ├── aws/            # AWS integrations
│   │   │   └── chroma_storage.py # ChromaDB implementation
│   │   └── utils/              # Utility functions
│   └── examples/               # Example usage code
├── tests/                      # pytest test suite
├── docker-compose.yml          # Docker production setup
├── pyproject.toml              # Project configuration
├── VERSIONING.md               # Versioning strategy documentation
├── CHANGELOG.md                # Version history
├── .bumpversion.cfg            # Version bumping configuration
└── README.md                   # Project documentation

Control de versiones

Tribal sigue el control de versiones semántico . Consulte VERSIONING.md para obtener más información sobre:

Numeración de versiones (MAYOR.MINOR.PATCH)
Control de versiones del esquema para compatibilidad con bases de datos
Convenciones de nombres de ramas
Procedimientos de lanzamiento y revisión

Compruebe la versión con:

# Display version information
tribal version

Gestión de dependencias

# Add a dependency
uv pip add <package-name>

# Add a development dependency
uv pip add <package-name>

# Update dependencies
uv pip sync requirements.txt requirements-dev.txt

Despliegue

Implementación de Docker

# Build and start containers
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop containers
docker-compose down

# With custom environment variables
API_PORT=8080 MCP_PORT=5000 REQUIRE_AUTH=true API_KEY=your-secret-key docker-start

Claude para integración de escritorio

Opción 1: Dejar que Claude for Desktop inicie el servidor

Abra ~/Library/Application Support/Claude/claude_desktop_config.json
Agregue la configuración del servidor MCP (supone que la herramienta Tribal ya está instalada):
```
{
  "mcpServers": [
    {
      "name": "tribal",
      "launchCommand": "tribal"
    }
  ]
}
```
Reiniciar Claude para escritorio

Opción 2: Conectarse al contenedor Docker en ejecución

Iniciar el contenedor:
```
cd /path/to/tribal
docker-start
```

Configurar Claude para escritorio:

{
  "mcpServers": [
    {
      "name": "tribal",
      "url": "http://localhost:5000"
    }
  ]
}

Integración CLI de Claude Code

# For Docker container
claude mcp add tribal http://localhost:5000

# For directly launched server
claude mcp add tribal --launch "tribal"

# Test the connection
claude mcp list
claude mcp test tribal

Solución de problemas

Verificar la instalación tribal: which tribal
Comprobar configuración: claude mcp list
Estado del servidor de prueba: tribal status
Busque mensajes de error en la salida de Claude
Verifique que el directorio de la base de datos exista y tenga los permisos adecuados

Implementación en la nube

El proyecto incluye implementaciones de marcador de posición para los servicios de AWS:

S3Storage : para almacenar registros de errores en Amazon S3
DynamoDBStorage : para utilizar DynamoDB como base de datos

Licencia

Licencia MIT