Skip to main content
Glama
Sign In
enesjakozh

Tribal Knowledge Service

by agentience
GitHub
Python
MIT License
2
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Integration with Amazon S3 for storing error records, providing cloud-based storage for the knowledge database through the S3Storage implementation

  • Supports Docker-based deployment using docker-compose for containerized production environments

  • Provides a REST API interface using FastAPI with endpoints for creating, retrieving, updating, and deleting error records

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

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:

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

  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:

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

  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

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

  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:

# 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

  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

# 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

  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

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

Tools

Una implementación de servidor MCP que ayuda a Claude a recordar y aprender de los errores de programación almacenando, recuperando y encontrando errores similares con contexto completo.

  1. Features
    1. Overview
      1. Packaging and Installing Tribal with uv
        1. Prerequisites
        2. Build and Install Steps
        3. Verification
        4. Integration with Claude
      2. Usage
        1. Available MCP Tools
        2. Example Usage with Claude
        3. Commands for Claude
        4. Running the Server
        5. Command-line Options
        6. Environment Variables
        7. API Endpoints
        8. Using the Client
        9. How It Works
      3. Development
        1. Running Tests
        2. Linting and Type Checking
        3. GitHub Workflow
        4. Project Structure
      4. Versioning
        1. Managing Dependencies
      5. Deployment
        1. Docker Deployment
        2. Claude for Desktop Integration
        3. Claude Code CLI Integration
      6. Troubleshooting
        1. Cloud Deployment
          1. License

            Related Resources

            Appeared in Searches

            ID: zo517uh6mq