部族 - 知識サービス

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セッションを開始すると、追加のインポートなしでTribalがMCPを通じて自動的に利用可能になります。

クロードは次のことを行います:

ストアプログラミングエラーと解決策
問題が発生した場合に類似のエラーを検索する
コーディングパターンに特化した知識ベースを構築する

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 と統合できます。

# 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 ツールを提供します。

add_error - 新しいエラーレコードを作成する (POST /errors)
get_error - UUIDでエラーを取得する (GET /errors/{id})
update_error - 既存のエラーを変更する (PUT /errors/{id})
delete_error - エラーレコードを削除する (DELETE /errors/{id})
search_errors - 条件でエラーを検索する (GET /errors)
find_similar - 意味的類似性検索 (GET /errors/similar)
get_token - JWTトークンを取得する（POST /token）

クロードとの使用例

クロードがエラーに遭遇した場合:

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

クロードが解決策を見つけたとき:

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

クロードへのコマンド

クロードに次のことを依頼できます。

「部族の知識ベースで同様のエラーを探してください」
「このソリューションをエラーデータベースに保存します」
「このエラーが以前に発生したかどうかを確認してください」

サーバーの実行

部族の命令を使う

# 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にあります。Claudeやその他のMCP対応LLM用のMCPサーバーはhttp://localhost:5000で利用可能になります。

環境変数

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

仕組み

TribalはChromaDBを使用してエラー記録と解決策を保存します
クロードがエラーに遭遇すると、エラーの詳細をTribalに送信します。
トライバルはエラーをベクトル化し、類似のエラーを検索します
クロードは適切な解決策を提案します
新しいソリューションは将来の参照用に保存されます

発達

テストの実行

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

リンティングと型チェック

ruff check .
mypy .
black .

GitHubワークフロー

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

ワークフローの手順

テスト: リンティング、型チェック、ユニットテストを実行します
- Python 3.12 を使用
- uvで依存関係をインストールします
- ruff、black、mypy、pytest を実行
ビルドと公開: パッケージをビルドしてPyPIに公開します
- メインブランチへのプッシュ時にのみトリガーされます
- 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を使用して依存関係をインストールします
毛羽立ちとひだのある走り
黒でフォーマットをチェック
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

デスクトップ統合のクロード

オプション1: Claude for Desktopでサーバーを起動する

~/Library/Application Support/Claude/claude_desktop_config.json開きます。
MCP サーバー構成を追加します (Tribal ツールがすでにインストールされていることを前提としています)。
{ "mcpServers": [ { "name": "tribal", "launchCommand": "tribal" } ] }
デスクトップ版のClaudeを再起動する

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

コンテナを起動します。
cd /path/to/tribal docker-start
Claude をデスクトップ用に設定する:
{ "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

トラブルシューティング

部族のインストールを確認する: which tribal
設定を確認してください: claude mcp list
テストサーバーのステータス: tribal status
Claudeの出力でエラーメッセージを探す
データベースディレクトリが存在し、適切な権限があることを確認してください

クラウド展開

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

S3Storage : Amazon S3にエラーレコードを保存する
DynamoDBStorage : データベースとして DynamoDB を使用する場合

ライセンス

MITライセンス

Integrations