Tribal MCP Server

部落-知识服务

Tribal是一个用于错误知识跟踪和检索的MCP（模型上下文协议）服务器实现。它提供REST API和本地MCP接口，用于与Claude Code和Cline等工具集成。

特性

• 存储和检索具有完整上下文的错误记录
• 基于ChromaDB的矢量相似性搜索
• REST API（FastAPI）和本机MCP接口
• 使用API密钥的JWT身份验证
• 本地存储（ChromaDB）和AWS集成
• Docker组合部署
• CLI客户端集成

概述

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

克劳德将：

1. 存储编程错误和解决方案
2. 遇到问题时搜索类似错误
3. 构建一个专门针对您的编码模式的知识库

用紫外线包装和安装Tribal

先决条件

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

构建和安装步骤

选项1：直接安装紫外线

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

# 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/错误）
2. get_error -按UUID检索错误（GET/errors/{id}）
3. update_error -修改现有错误（PUT/errors/{id}）
4. delete_error -删除错误记录（删除/错误/｛id｝）
5. search_errors -按条件查找错误（GET/错误）
6. find_similar -语义相似性搜索（GET/错误/相似）
7. get_token -获取JWT令牌（POST/令牌）

Claude使用示例

当Claude遇到错误时：

I'll track this error and look for similar problems in our knowledge base.

当克劳德找到解决方案时：

I've found a solution! I'll store this in our knowledge base for next time.

克劳德的命令

你可以要求克劳德：

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

运行服务器

使用部落命令

# 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:8000API文档位于/docs。 MCP服务器将在http://localhost:5000适用于Claude和其他兼容MCP的LLM。

环境变量

FastAPI服务器

• PERSIST_DIRECTORY：ChromaDB存储路径（默认：“./chroma_db”）
• API_KEY：身份验证密钥（默认：“dev-api-key”）
• SECRET_KEY：JWT签名密钥（默认：“生产中不安全的开发密钥更改”）
• 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密钥”）
• 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 

# 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. 部落将错误矢量化并搜索类似的错误
4. Claude收到相关解决方案并提出建议
5. 存储新的解决方案以供将来参考

发展

运行测试

pytest
pytest tests/path_to_test.py::test_name  # For specific tests

过梁和类型检查

ruff check .
mypy .
black .

GitHub工作流

该项目使用GitHub Actions进行持续集成和部署。工作流会自动对push-to-main和pull请求运行测试、linting和类型检查。

工作流程步骤

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

- 使用Python 3.12 - 使用uv安装依赖项 - 运行ruff，黑色，mypy和pytest

1. 构建和发布：构建包并将其发布到PyPI

- 仅在向主分支推送时触发 - 使用Python的构建系统 - 使用麻线发布到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安装依赖项
• 长着褶边
• 用黑色检查格式
• 使用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

版本控制

• 版本编号（主要、次要、补丁）
• 数据库兼容性的架构版本控制
• 分支命名约定
• 发布和修补程序

检查版本：

# Display version information
tribal version

管理依赖关系

# Add a dependency
uv pip add 

# Add a development dependency
uv pip add 

# 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桌面集成

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

1. 打开 ~/Library/Application Support/Claude/claude_desktop_config.json

1. 添加MCP服务器配置（假设已安装Tribal工具）：

   {
     "mcpServers": [
       {
         "name": "tribal",
         "launchCommand": "tribal"
       }
     ]
   }

1. 重新启动桌面版的Claude

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

1. 启动容器：

   cd /path/to/tribal
   docker-start

1. 为桌面配置Claude：

   {
     "mcpServers": [
       {
         "name": "tribal",
         "url": "http://localhost:5000"
       }
     ]
   }

Claude代码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. 验证部落安装： which tribal
2. 检查配置： claude mcp list
3. 测试服务器状态： tribal status
4. 在Claude输出中查找错误消息
5. 检查数据库目录是否存在以及是否具有适当的权限

云部署

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

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

许可证

MIT许可证