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á:

1. Errores de programación de la tienda y soluciones

2. Busque errores similares cuando encuentre problemas

3. 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:

Opción 2: Instalación de desarrollo

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

Opción 3: Construya el paquete primero

Si desea crear un paquete distribuible:

Opción 4: Usar el comando uv tool install

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

Verificación

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

Integración con Claude

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

Uso

Herramientas MCP disponibles

Tribal proporciona estas herramientas MCP:

1. add_error - Crea un nuevo registro de error (POST/errors)

2. get_error - Recuperar error por UUID (GET /errors/{id})

3. update_error - Modificar el error existente (PUT /errors/{id})

4. delete_error - Eliminar registro de error (DELETE /errors/{id})

5. search_errors - Buscar errores por criterios (GET /errors)

6. find_similar - Búsqueda de similitud semántica (GET /errors/similar)

7. get_token - Obtener el token JWT (POST /token)

Ejemplo de uso con Claude

Cuando Claude encuentra un error:

Cuando Claude encuentra una solución:

Ó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

Uso de módulos de Python

Uso de puntos de entrada heredados

Opciones de la línea de comandos

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

Cómo funciona

1. Tribal utiliza ChromaDB para almacenar registros de errores y soluciones

2. Cuando Claude encuentra un error, envía los detalles del error a Tribal.

3. Tribal vectoriza el error y busca otros similares

4. Claude recupera soluciones relevantes para sugerir

5. Las nuevas soluciones se almacenan para futuras referencias.

Desarrollo

Ejecución de pruebas

Comprobación de tipo y desbastado

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

1. Prueba : ejecuta pelusa, verificación de tipos y pruebas unitarias

   • Utiliza Python 3.12

   • Instala dependencias con uv

   • Ejecuta ruff, black, mypy y pytest

2. 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:

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

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:

Gestión de dependencias

Despliegue

Implementación de Docker

Claude para integración de escritorio

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

1. Abra ~/Library/Application Support/Claude/claude_desktop_config.json

2. Agregue la configuración del servidor MCP (supone que la herramienta Tribal ya está instalada):

   { "mcpServers": [ { "name": "tribal", "launchCommand": "tribal" } ] }

3. Reiniciar Claude para escritorio

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

1. Iniciar el contenedor:

   cd /path/to/tribal docker-start

2. Configurar Claude para escritorio:

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

Integración CLI de Claude Code

Solución de problemas

1. Verificar la instalación tribal: which tribal

2. Comprobar configuración: claude mcp list

3. Estado del servidor de prueba: tribal status

4. Busque mensajes de error en la salida de Claude

5. 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