Tribal - 知识服务

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 提供，无需额外导入。

Claude 将：

1. 存储编程错误和解决方案
2. 在遇到问题时搜索类似的错误
3. 构建特定于您的编码模式的知识库

使用 uv 打包和安装 Tribal

前提条件

• Python 3.12+
• uv 包管理器 (推荐)

构建和安装步骤

选项 1：使用 uv 直接安装

最简单的方法是从当前目录直接安装：

# 从项目根目录
cd /path/to/tribal

# 使用 uv 安装
uv pip install .

选项 2：开发安装

对于您希望更改立即反映的开发工作：

# 从项目根目录
cd /path/to/tribal

# 以开发模式安装
uv pip install -e .

选项 3：先构建包

如果您想构建一个可分发的包：

# 确保您位于项目根目录
cd /path/to/tribal

# 如果需要，安装 build 包
uv pip install build

# 构建包
python -m build

# 这将在 dist/ 目录中创建分发文件
# 现在安装 wheel 文件
uv pip install dist/tribal-0.1.0-py3-none-any.whl

选项 4：使用 uv tool install 命令

您也可以使用工具安装方法：

# 作为全局工具安装
cd /path/to/tribal
uv tool install .

# 或者以开发模式安装
uv tool install -e .

验证

安装后，验证工具是否已正确安装：

# 检查安装
which tribal

# 检查版本
tribal version

与 Claude 集成

安装后，您可以与 Claude 集成：

# 将 Tribal 添加到 Claude Code
claude mcp add tribal --launch "tribal"

# 验证配置
claude mcp list

# 对于 Docker 容器
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 遇到错误时：

我会跟踪这个错误，并在我们的知识库中寻找类似的问题。

当 Claude 找到解决方案时：

我找到了一个解决方案！我会将其存储在我们的知识库中，以备下次使用。

Claude 的命令

您可以要求 Claude：

• "在我们的 Tribal 知识库中查找类似的错误"
• "将此解决方案存储到我们的错误数据库中"
• "检查我们以前是否见过这个错误"

运行服务器

使用 tribal 命令

# 运行服务器
tribal

# 获取帮助
tribal help

# 显示版本
tribal version

# 使用选项运行
tribal server --port 5000 --auto-port

使用 Python 模块

# 运行 Tribal 服务器
python -m mcp_server_tribal.mcp_app

# 运行 FastAPI 后端服务器
python -m mcp_server_tribal.app

使用旧的入口点

# 旧版 MCP 服务器
mcp-server

# 旧版 FastAPI 服务器
mcp-api

命令行选项

# 具有自动重载的开发模式
mcp-api --reload
mcp-server --reload

# 自定义端口
mcp-api --port 8080
mcp-server --port 5000

# 自动端口选择
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: 获取身份验证令牌

使用客户端

# 添加新的错误记录
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"

# 按 ID 获取错误
mcp-client --action get --id <error-id>

# 搜索错误
mcp-client --action search --error-type ImportError --language python

# 查找类似的错误
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  # 对于特定测试

Linting 和类型检查

ruff check .
mypy .
black .

GitHub 工作流程

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

工作流程步骤

1. 测试: 运行 linting、类型检查和单元测试

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

2. 构建和发布: 构建并将包发布到 PyPI

   • 仅在推送到 main 分支时触发
   • 使用 Python 的构建系统
   • 使用 twine 发布到 PyPI

在本地测试

您可以使用提供的脚本在本地测试 GitHub 工作流程：

# 使脚本可执行
chmod +x scripts/test-workflow.sh

# 在本地运行工作流程
./scripts/test-workflow.sh

此脚本模拟您本地机器上的 GitHub 工作流程步骤：

• 检查 Python 版本 (推荐 3.12)
• 使用 uv 安装依赖项
• 使用 ruff 运行 linting
• 使用 black 检查格式
• 使用 mypy 运行类型检查
• 使用 pytest 运行测试
• 构建包

注意：该脚本跳过本地测试的发布步骤。

项目结构

tribal/
├── src/
│   ├── mcp_server_tribal/      # 核心包
│   │   ├── api/                # FastAPI 端点
│   │   ├── cli/                # 命令行界面
│   │   ├── models/             # Pydantic 模型
│   │   ├── services/           # 服务层
│   │   │   ├── aws/            # AWS 集成
│   │   │   └── chroma_storage.py # ChromaDB 实现
│   │   └── utils/              # 实用函数
│   └── examples/               # 示例用法代码
├── tests/                      # pytest 测试套件
├── docker-compose.yml          # Docker 生产设置
├── pyproject.toml              # 项目配置
├── VERSIONING.md               # 版本控制策略文档
├── CHANGELOG.md                # 版本历史
├── .bumpversion.cfg            # 版本递增配置
└── README.md                   # 项目文档

版本控制

Tribal 遵循 语义版本控制。有关以下内容的完整详细信息，请参阅 VERSIONING.md：

• 版本编号 (MAJOR.MINOR.PATCH)
• 数据库兼容性的模式版本控制
• 分支命名约定
• 发布和热修复程序

使用以下命令检查版本：

# 显示版本信息
tribal version

管理依赖项

# 添加依赖项
uv pip add <package-name>

# 添加开发依赖项
uv pip add <package-name>

# 更新依赖项
uv pip sync requirements.txt requirements-dev.txt

部署

Docker 部署

# 构建并启动容器
docker-compose up -d --build

# 查看日志
docker-compose logs -f

# 停止容器
docker-compose down

# 使用自定义环境变量
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 集成

# 对于 Docker 容器
claude mcp add tribal http://localhost:5000

# 对于直接启动的服务器
claude mcp add tribal --launch "tribal"

# 测试连接
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 许可证