Tribal Knowledge Service

部落 - 知识服务

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

克劳德将：

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

使用 uv 打包并安装 Tribal

先决条件

• Python 3.12+
• uv 包管理器（推荐）

构建和安装步骤

选项 1：直接使用 uv 安装

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

选项 2：开发安装

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

选项 3：首先构建包

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

选项 4：使用uv tool install命令

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

确认

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

与克劳德的整合

安装完成后，即可与Claude集成：

用法

可用的 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：

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

运行服务器

使用部落命令

使用 Python 模块

使用旧式入口点

命令行选项

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 ：获取身份验证令牌

使用客户端

工作原理

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

发展

运行测试

Linting 和类型检查

GitHub 工作流程

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

工作流程步骤

1. 测试：运行 linting、类型检查和单元测试
   • 使用 Python 3.12
   • 使用 uv 安装依赖项
   • 运行 ruff、black、mypy 和 pytest
2. 构建并发布：构建包并将其发布到 PyPI
   • 仅在推送到主分支时触发
   • 使用 Python 的构建系统
   • 使用 twine 发布到 PyPI

本地测试

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

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

• 检查 Python 版本（建议 3.12）
• 使用 uv 安装依赖项
• 使用 ruff 进行除毛
• 用黑色检查格式
• 使用 mypy 运行类型检查
• 使用 pytest 运行测试
• 构建包

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

项目结构

版本控制

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

• 版本编号（MAJOR.MINOR.PATCH）
• 数据库兼容性的架构版本控制
• 分支命名约定
• 发布和修补程序程序

使用以下命令检查版本：

管理依赖关系

部署

Docker 部署

Claude 用于桌面集成

选项 1：让 Claude for Desktop 启动服务器

1. 打开~/Library/Application Support/Claude/claude_desktop_config.json
2. 添加 MCP 服务器配置（假设 Tribal 工具已安装）：
   { "mcpServers": [ { "name": "tribal", "launchCommand": "tribal" } ] }
3. 重启 Claude 桌面版

选项 2：连接到正在运行的 Docker 容器

1. 启动容器：
   cd /path/to/tribal docker-start
2. 配置 Claude 桌面版：
   { "mcpServers": [ { "name": "tribal", "url": "http://localhost:5000" } ] }

Claude Code CLI 集成

故障排除

1. 验证部落安装： which tribal
2. 检查配置： claude mcp list
3. 测试服务器状态： tribal status
4. 在 Claude 输出中查找错误消息
5. 检查数据库目录是否存在并且具有适当的权限

云部署

该项目包括 AWS 服务的占位符实现：

• S3Storage ：用于在 Amazon S3 中存储错误记录
• DynamoDBStorage ：使用 DynamoDB 作为数据库

执照

MIT 许可证