Tribal - Knowledge Service

Tribal - 知识服务

Tribal 是一个用于错误知识追踪和检索的 MCP（Model Context Protocol）服务实现。它同时提供 REST API 和原生 MCP 接口，可与 Claude Code 和 Cline 等工具集成。

功能

• 存储和检索包含完整上下文的错误记录
• 使用 ChromaDB 进行向量相似度搜索
• REST API（FastAPI）和原生 MCP 接口
• 使用 API 密钥进行 JWT 身份验证
• 本地存储（ChromaDB）和 AWS 集成
• 使用 Docker-compose 部署
• 集成命令行客户端

概览

Tribal 帮助 Claude 记住并从编程错误中学习。启动 Claude Code 会话时，Tribal 会通过 MCP 自动可用，无需额外导入。

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 的大模型使用。

环境变量

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 许可证