部落_mcp_服务器
项目介绍
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 将：
- 存储编程错误及其解决方案
- 当遇到问题时搜索类似的错误
- 构建特定于你的编码模式的知识库
使用 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
# 如果需要，安装构建包
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 工具：
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 的示例使用
当 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 "你需要安装 requests 包"
# 根据 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'"
工作原理
- Tribal 使用 ChromaDB 存储错误记录和解决方案
- 当 Claude 遇到错误时，它将错误详情发送给 Tribal
- Tribal 对错误进行向量化并搜索相似的错误
- Claude 收回相关的解决方案建议
- 新的解决方案被存储以备将来参考
开发
运行测试
pytest
pytest tests/path_to_test.py::test_name # 对于特定的测试
代码检查和类型检查
ruff check .
mypy .
black .
GitHub 工作流
该项目使用 GitHub Actions 进行持续集成和部署。工作流在主分支推送和拉取请求时自动运行测试、代码检查和类型检查。
工作流步骤
-
测试：运行代码检查、类型检查和单元测试
- 使用 Python 3.12
- 使用 uv 安装依赖项
- 运行 ruff、black、mypy 和 pytest
-
构建和发布：构建并发布包到 PyPI
- 触发仅在主分支推送时
- 使用 Python 的构建系统
- 使用 twine 发布到 PyPI
在本地测试
你可以使用提供的脚本在本地测试 GitHub 工作流：
# 使脚本可执行
chmod +x scripts/test-workflow.sh
# 在本地运行工作流
./scripts/test-workflow.sh
该脚本模拟 GitHub 工作流步骤在你的本地机器上：
- 检查 Python 版本（推荐 3.12）
- 使用 uv 安装依赖项
- 使用 ruff 进行代码检查
- 使用 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 了解关于以下内容的详细信息：
- 版本编号（主版本.次版本.修订版）
- 数据库兼容性的模式版本控制
- 分支命名约定
- 发布和热修复程序
查看版本：
# 显示版本信息
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 启动服务器
-
打开
~/Library/Application Support/Claude/claude_desktop_config.json -
添加 MCP 服务器配置（假设已安装 Tribal 工具）：
{ "mcpServers": [ { "name": "tribal", "launchCommand": "tribal" } ] } -
重启 Claude for Desktop
方案 2：连接到正在运行的 Docker 容器
-
启动容器：
cd /path/to/tribal docker-start -
配置 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
故障排除
- 验证 Tribal 安装：
which tribal - 检查配置：
claude mcp list - 测试服务器状态：
tribal status - 查看 Claude 输出中的错误消息
- 检查数据库目录是否存在且具有适当的权限
云部署
项目包括针对 AWS 服务的占位符实现：
S3Storage: 用于在 Amazon S3 中存储错误记录DynamoDBStorage: 用于使用 DynamoDB 作为数据库