부족 - 지식 서비스

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을 자동으로 사용할 수 있습니다.

클로드는 다음을 할 것입니다:

스토어 프로그래밍 오류 및 솔루션
문제가 발생하면 유사한 오류를 검색하세요
귀하의 코딩 패턴에 맞는 지식 기반을 구축하세요

UV를 이용한 Tribal 패키징 및 설치

필수 조건

파이썬 3.12+
uv 패키지 관리자(추천)

빌드 및 설치 단계

옵션 1: UV를 이용한 직접 설치

가장 간단한 방법은 현재 디렉토리에서 직접 설치하는 것입니다.

지엑스피1

옵션 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 도구를 제공합니다.

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)

Claude를 사용한 예시 사용

클로드가 오류를 발견했을 때:

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.

클로드에 대한 명령

Claude에게 다음을 요청할 수 있습니다.

"우리 부족 지식 기반에서 유사한 오류를 찾아보세요"
"이 솔루션을 오류 데이터베이스에 저장하세요"
"이 오류가 이전에 발생했는지 확인하세요"

서버 실행

부족 명령 사용

# 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를 사용하여 오류 레코드와 솔루션을 저장합니다.
Claude가 오류를 발견하면 오류 세부 정보를 Tribal로 전송합니다.
Tribal은 오류를 벡터화하고 유사한 오류를 검색합니다.
Claude는 제안할 관련 솔루션을 다시 가져옵니다.
새로운 솔루션은 향후 참조를 위해 저장됩니다.

개발

테스트 실행

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은 의미적 버전 관리(Semantic Versioning)를 따릅니다. 자세한 내용은 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

전개

도커 배포

# 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

옵션 1: 데스크톱용 Claude가 서버를 시작하도록 합니다.

~/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