Tribal - Knowledge Service

Tribal is an MCP (Model Context Protocol) server implementation for error knowledge tracking and retrieval. It provides both REST API and native MCP interfaces for integration with tools like Claude Code and Cline.

Features

• Store and retrieve error records with full context

• Vector similarity search using ChromaDB

• REST API (FastAPI) and native MCP interfaces

• JWT authentication with API keys

• Local storage (ChromaDB) and AWS integration

• Docker-compose deployment

• CLI client integration

Overview

Tribal helps Claude remember and learn from programming errors. When you start a Claude Code session, Tribal is automatically available through MCP without additional imports.

Claude will:

1. Store programming errors and solutions

2. Search for similar errors when you encounter problems

3. Build a knowledge base specific to your coding patterns

Packaging and Installing Tribal with uv

Prerequisites

• Python 3.12+

• uv package manager (recommended)

Build and Install Steps

Option 1: Direct installation with uv

The simplest approach is to install directly from the current directory:

Option 2: Development Installation

For development work where you want changes to be immediately reflected:

Option 3: Build the package first

If you want to build a distributable package:

Option 4: Using the uv tool install command

You can also use the tool installation approach:

Verification

After installation, verify that the tool is properly installed:

Integration with Claude

After installation, you can integrate with Claude:

Usage

Available MCP Tools

Tribal provides these MCP tools:

1. add_error - Create new error record (POST /errors)

2. get_error - Retrieve error by UUID (GET /errors/{id})

3. update_error - Modify existing error (PUT /errors/{id})

4. delete_error - Remove error record (DELETE /errors/{id})

5. search_errors - Find errors by criteria (GET /errors)

6. find_similar - Semantic similarity search (GET /errors/similar)

7. get_token - Obtain JWT token (POST /token)

Example Usage with Claude

When Claude encounters an error:

When Claude finds a solution:

Commands for Claude

You can ask Claude to:

• "Look for similar errors in our Tribal knowledge base"

• "Store this solution to our error database"

• "Check if we've seen this error before"

Running the Server

Using the tribal command

Using Python modules

Using legacy entry points

Command-line Options

The FastAPI server will be available at http://localhost:8000 with API documentation at /docs. The MCP server will be available at http://localhost:5000 for Claude and other MCP-compatible LLMs.

Environment Variables

FastAPI Server

• PERSIST_DIRECTORY: ChromaDB storage path (default: "./chroma_db")

• API_KEY: Authentication key (default: "dev-api-key")

• SECRET_KEY: JWT signing key (default: "insecure-dev-key-change-in-production")

• REQUIRE_AUTH: Authentication requirement (default: "false")

• PORT: Server port (default: 8000)

MCP Server

• MCP_API_URL: FastAPI server URL (default: "http://localhost:8000")

• MCP_PORT: MCP server port (default: 5000)

• MCP_HOST: Host to bind to (default: "0.0.0.0")

• API_KEY: FastAPI access key (default: "dev-api-key")

• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_BUCKET: For AWS integration

API Endpoints

• POST /errors: Create new error record

• GET /errors/{error_id}: Get error by ID

• PUT /errors/{error_id}: Update error record

• DELETE /errors/{error_id}: Delete error

• GET /errors: Search errors by criteria

• GET /errors/similar: Find similar errors

• POST /token: Get authentication token

Using the Client

How It Works

1. Tribal uses ChromaDB to store error records and solutions

2. When Claude encounters an error, it sends the error details to Tribal

3. Tribal vectorizes the error and searches for similar ones

4. Claude gets back relevant solutions to suggest

5. New solutions are stored for future reference

Development

Running Tests

Linting and Type Checking

GitHub Workflow

This project uses GitHub Actions for continuous integration and deployment. The workflow automatically runs tests, linting, and type checking on push to main and pull requests.

Workflow Steps

1. Test: Runs linting, type checking, and unit tests

   • Uses Python 3.12

   • Installs dependencies with uv

   • Runs ruff, black, mypy, and pytest

2. Build and Publish: Builds and publishes the package to PyPI

   • Triggered only on push to main branch

   • Uses Python's build system

   • Publishes to PyPI using twine

Testing Locally

You can test the GitHub workflow locally using the provided script:

This script simulates the GitHub workflow steps on your local machine:

• Checks Python version (3.12 recommended)

• Installs dependencies using uv

• Runs linting with ruff

• Checks formatting with black

• Runs type checking with mypy

• Runs tests with pytest

• Builds the package

Note: The script skips the publishing step for local testing.

Project Structure

Versioning

Tribal follows Semantic Versioning. See VERSIONING.md for complete details about:

• Version numbering (MAJOR.MINOR.PATCH)

• Schema versioning for database compatibility

• Branch naming conventions

• Release and hotfix procedures

Check the version with:

Managing Dependencies

Deployment

Docker Deployment

Claude for Desktop Integration

Option 1: Let Claude for Desktop Launch the Server

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

2. Add the MCP server configuration (assumes Tribal tool is already installed):

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

3. Restart Claude for Desktop

Option 2: Connect to Running Docker Container

1. Start the container:

   cd /path/to/tribal docker-start

2. Configure Claude for Desktop:

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

Claude Code CLI Integration

Troubleshooting

1. Verify Tribal installation: which tribal

2. Check configuration: claude mcp list

3. Test server status: tribal status

4. Look for error messages in the Claude output

5. Check the database directory exists and has proper permissions

Cloud Deployment

The project includes placeholder implementations for AWS services:

• S3Storage: For storing error records in Amazon S3

• DynamoDBStorage: For using DynamoDB as the database

License

MIT License