Tribal - Knowledge Service

Tribal - ナレッジサービス

Tribal は、エラーのナレッジ追跡と検索のための MCP（Model Context Protocol）サーバー実装です。Claude Code や Cline などのツールと統合するための REST API とネイティブ MCP インターフェースの両方を提供します。

機能

• コンテキストをすべて含めてエラー記録を保存、取得
• ChromaDB を使用したベクトル類似検索
• REST API（FastAPI）とネイティブ MCP インターフェース
• API キーを使用した JWT 認証
• ローカルストレージ（ChromaDB）と AWS の統合
• Docker-compose によるデプロイ
• CLI クライアントとの統合

概要

Tribal は、Claude がプログラミングエラーを記憶し、そこから学習できるようにします。Claude Code のセッションを開始すると、追加のインポートなしで MCP 経由で Tribal を自動的に利用できます。

Claude は次のことを行います。

1. プログラミングエラーと解決策を保存する
2. 問題が発生したときに、類似するエラーを検索する
3. コーディングパターンに特化したナレッジベースを構築する

uv を使用した Tribal のパッケージ化とインストール

前提条件

• Python 3.12+
• uv パッケージマネージャー（推奨）

ビルドとインストールの手順

オプション 1：uv で直接インストール

最も簡単な方法は、現在のディレクトリから直接インストールすることです。

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

# Install using uv
uv pip install .

オプション 2：開発用インストール

変更をすぐに反映させたい開発作業向けです。

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

# Install in development mode
uv pip install -e .

オプション 3：先にパッケージをビルド

配布可能なパッケージをビルドする場合は、次の手順を実行します。

# 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

オプション 4：uv tool install コマンドを使用

ツールをインストールする方法も利用できます。

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

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

確認

インストール後、ツールが正しくインストールされたことを確認します。

# Check the installation
which tribal

# Check the version
tribal version

Claude との統合

インストール後、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

使用方法

利用可能な MCP ツール

Tribal は次の MCP ツールを提供します。

1. add_error - 新しいエラー記録を作成（POST /errors）
2. get_error - UUID でエラーを取得（GET /errors/{id}）
3. update_error - 既存のエラーを変更（PUT /errors/{id}）
4. delete_error - エラー記録を削除（DELETE /errors/{id}）
5. search_errors - 条件に基づいてエラーを検索（GET /errors）
6. find_similar - 意味的類似検索（GET /errors/similar）
7. get_token - JWT トークンを取得（POST /token）

Claude での使用例

Claude がエラーに遭遇したとき：

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

Claude が解決策を見つけたとき：

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

Claude への指示

Claude に次のように依頼できます。

• 「Tribal のナレッジベースで類似のエラーを探してください」
• 「この解決策をエラーデータベースに保存してください」
• 「このエラーが以前にも発生したことがあるか確認してください」

サーバーの実行

tribal コマンドを使用

# Run the server
tribal

# Get help
tribal help

# Show version
tribal version

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

Python モジュールを使用

# Run the Tribal server
python -m mcp_server_tribal.mcp_app

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

従来のエントリーポイントを使用

# Legacy MCP server
mcp-server

# Legacy FastAPI server
mcp-api

コマンドラインオプション

# 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

FastAPI サーバーは http://localhost:8000 で利用でき、API ドキュメントは /docs で確認できます。 MCP サーバーは http://localhost:5000 で利用でき、Claude やその他の MCP 互換 LLM からアクセスできます。

環境変数

FastAPI サーバー

• PERSIST_DIRECTORY：ChromaDB のストレージパス（デフォルト："./chroma_db"）
• API_KEY：認証キー（デフォルト："dev-api-key"）
• SECRET_KEY：JWT 署名キー（デフォルト："insecure-dev-key-change-in-production"）
• REQUIRE_AUTH：認証の要否（デフォルト："false"）
• PORT：サーバーのポート（デフォルト：8000）

MCP サーバー

• MCP_API_URL：FastAPI サーバーの URL（デフォルト："http://localhost:8000"）
• MCP_PORT：MCP サーバーのポート（デフォルト：5000）
• MCP_HOST：バインドするホスト（デフォルト："0.0.0.0"）
• API_KEY：FastAPI アクセスキー（デフォルト："dev-api-key"）
• AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_S3_BUCKET：AWS 統合用

API エンドポイント

• POST /errors：新しいエラー記録を作成
• GET /errors/{error_id}：ID でエラーを取得
• PUT /errors/{error_id}：エラー記録を更新
• DELETE /errors/{error_id}：エラーを削除
• GET /errors：条件に基づいてエラーを検索
• GET /errors/similar：類似するエラーを検索
• POST /token：認証トークンを取得

クライアントの使用方法

# 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'"

仕組み

1. Tribal は ChromaDB を使用して、エラーレコードと解決策を保存します
2. Claude がエラーに遭遇すると、エラーの詳細を Tribal に送信します
3. Tribal はエラーをベクトル化し、類似するエラーを検索します
4. Claude は関連する解決策を受け取り、提案します
5. 新しい解決策は、今後参照できるように保存されます

開発

テストの実行

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

リントと型チェック

ruff check .
mypy .
black .

GitHub ワークフロー

このプロジェクトでは、継続的インテグレーションとデプロイに GitHub Actions を使用しています。このワークフローでは、main へのプッシュ時とプルリクエスト時に、テスト、リント、型チェックが自動的に実行されます。

ワークフローの手順

1. テスト：リント、型チェック、ユニットテストを実行します

   • Python 3.12 を使用します
   • uv で依存関係をインストールします
   • ruff、black、mypy、pytest を実行します

2. ビルドと公開：パッケージをビルドし、PyPI に公開します

   • main ブランチへのプッシュ時のみ実行されます
   • Python のビルドシステムを使用します
   • twine を使用して PyPI に公開します

ローカルでのテスト

付属のスクリプトを使用して、GitHub ワークフローをローカルでテストできます。

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

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

このスクリプトは、ローカルマシン上で GitHub ワークフローの手順をシミュレートします。

• Python のバージョンを確認します（3.12 を推奨）
• uv を使用して依存関係をインストールします
• ruff でリントを実行します
• black でフォーマットを確認します
• mypy で型チェックを実行します
• pytest でテストを実行します
• パッケージをビルドします

注：このスクリプトは、ローカルでのテスト時には公開手順をスキップします。

プロジェクト構成

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

バージョン管理

Tribal はセマンティック バージョニングに従います。以下の詳細については、VERSIONING.md を参照してください。

• バージョン番号（MAJOR.MINOR.PATCH）
• データベースとの互換性を保つためのスキーマのバージョン管理
• ブランチの命名規則
• リリースおよびホットフィックスの手順

次のコマンドでバージョンを確認します。

# Display version information
tribal version

依存関係の管理

# 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

デプロイ

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 for Desktop との連携

オプション 1：Claude for Desktop にサーバーを起動させる

1. ~/Library/Application Support/Claude/claude_desktop_config.json を開きます

2. MCP サーバーの設定を追加します（Tribal ツールがすでにインストールされていることを前提とします）。

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

3. Claude for Desktop を再起動します

オプション 2：実行中の Docker コンテナに接続する

1. コンテナを起動します。

   cd /path/to/tribal
   docker-start
   

2. Claude for Desktop を設定します。

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

Claude Code CLI との連携

# 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

トラブルシューティング

1. Tribal がインストールされていることを確認します：which tribal
2. 設定を確認します：claude mcp list
3. サーバーのステータスを確認します：tribal status
4. Claude の出力にエラーメッセージがないか確認します
5. データベースのディレクトリが存在し、適切なアクセス権があることを確認します

クラウドへのデプロイ

このプロジェクトには、AWS サービスのプレースホルダー実装が含まれています。

• S3Storage：エラーレコードを Amazon S3 に保存します
• DynamoDBStorage：データベースとして DynamoDB を使用します

ライセンス

MIT ライセンス