Tribal Knowledge Service for Claude

Overview

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. Tribal helps Claude remember and learn from programming errors, storing solutions and searching for similar problems when encountered.

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

Packaging and Installing Tribal with uv

Prerequisites

• Python 3.12+
• uv package manager (recommended)

Build and Install Steps

Option 1: Direct installation with uv

cd /path/to/tribal
uv pip install .

Option 2: Development Installation

cd /path/to/tribal
uv pip install -e .

Option 3: Build the package first

cd /path/to/tribal
uv pip install build
python -m build
uv pip install dist/tribal-0.1.0-py3-none-any.whl

Option 4: Using the uv tool install command

cd /path/to/tribal
uv tool install .

Verification

which tribal
tribal version

Integration with Claude

claude mcp add tribal --launch "tribal"
claude mcp list
claude mcp add tribal http://localhost:5000

Usage

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

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

When Claude finds a solution:

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

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

tribal
tribal help
tribal version
tribal server --port 5000 --auto-port

Using Python modules

python -m mcp_server_tribal.mcp_app
python -m mcp_server_tribal.app

Using legacy entry points

mcp-server
mcp-api

Command-line Options

mcp-api --reload
mcp-server --reload
mcp-api --port 8080
mcp-server --port 5000
mcp-api --auto-port
mcp-server --auto-port

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

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"
mcp-client --action get --id <error-id>
mcp-client --action search --error-type ImportError --language python
mcp-client --action similar --query "ModuleNotFoundError: No module named 'pandas'"

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

pytest
pytest tests/path_to_test.py::test_name

Linting and Type Checking

ruff check .
mypy .
black .

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
2. Build and Publish: Builds and publishes the package to PyPI

Testing Locally

chmod +x scripts/test-workflow.sh
./scripts/test-workflow.sh

Project Structure

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

Versioning

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

Managing Dependencies

uv pip add <package-name>
uv pip sync requirements.txt requirements-dev.txt

Deployment

Docker Deployment

docker-compose up -d --build
docker-compose logs -f
docker-compose down
API_PORT=8080 MCP_PORT=5000 REQUIRE_AUTH=true API_KEY=your-secret-key docker-start

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:

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

3. Restart Claude for Desktop

Option 2: Connect to Running Docker Container

1. Start the container:

   shell cd /path/to/tribal docker-start

2. Configure Claude for Desktop:

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

Claude Code CLI Integration

claude mcp add tribal http://localhost:5000
claude mcp add tribal --launch "tribal"
claude mcp list
claude mcp test tribal

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