部落 - 知识服务

Tribal 是一个用于错误知识跟踪和检索的 MCP（模型上下文协议）服务器实现。它提供 REST API 和原生 MCP 接口，可与 Claude Code 和 Cline 等工具集成。

特征

存储和检索具有完整上下文的错误记录
使用 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)

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

工作原理

Tribal 使用 ChromaDB 存储错误记录和解决方案
当 Claude 遇到错误时，它会将错误详细信息发送给 Tribal
Tribal 将错误向量化并搜索类似的错误
克劳德拿回相关解决方案建议
存储新的解决方案以供将来参考

发展

运行测试

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

Linting 和类型检查

ruff check .
mypy .
black .

GitHub 工作流程

该项目使用 GitHub Actions 进行持续集成和部署。工作流程会自动在推送到主代码和拉取请求时运行测试、代码检查和类型检查。

工作流程步骤

测试：运行 linting、类型检查和单元测试
- 使用 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 安装依赖项
使用 ruff 进行除毛
用黑色检查格式
使用 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 用于桌面集成

选项 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