Tribal - 知识服务

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

功能

• 存储和检索带有完整上下文的错误记录
• 使用 ChromaDB 进行向量相似性搜索
• REST API (FastAPI) 和原生 MCP 接口
• 使用 API 密钥进行 JWT 认证
• 本地存储 (ChromaDB) 和 AWS 集成
• Docker-compose 部署
• CLI 客户端集成

概述

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 的 LLMs 提供服务。

环境变量

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 进行持续集成和部署。工作流会在推送到主分支和拉取请求时自动运行测试、代码检查和类型检查。

工作流步骤

1. 测试：运行代码检查、类型检查和单元测试

   • 使用 Python 3.12
   • 使用 uv 安装依赖
   • 运行 ruff, black, mypy 和 pytest

2. 构建和发布：构建并将包发布到 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 进行代码检查
• 使用 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 遵循 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

部署

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 License