# Chatlog MCP Server - 项目封装完整指南
## 📦 项目概述
我们已经将 Chatlog MCP Server 封装成了一个完整的、可复用的 Python 包。这个包包含所有必要的文件，可以直接安装和使用。
## 🏗️ 项目结构
```
chatlog-mcp-server/
├── 📄 README.md # 项目说明文档
├── 📄 LICENSE # MIT 许可证
├── 📄 setup.py # Python 包安装配置
├── 📄 requirements.txt # 依赖列表
├── 📄 MANIFEST.in # 包文件清单
├── 📄 .gitignore # Git 忽略文件
├── 📄 CONTRIBUTING.md # 贡献指南
│
├── 📁 chatlog_mcp/ # Python 包主目录
│ ├── 📄 __init__.py # 包初始化文件
│ ├── 📄 server.py # MCP 服务器实现
│ ├── 📄 cli.py # 命令行入口
│ │
│ ├── 📁 examples/ # 示例文件
│ │ ├── 📄 analyze.py # 数据分析示例
│ │ └── 📄 mcp-servers.json # MCP 配置示例
│ │
│ └── 📁 tests/ # 测试文件
│ ├── 📄 __init__.py
│ └── 📄 test_server.py # 单元测试
│
├── 📁 scripts/ # 安装和构建脚本
│ ├── 📄 install.sh # Linux/macOS 安装脚本
│ ├── 📄 install.bat # Windows 安装脚本
│ ├── 📄 build.py # 构建脚本
│ └── 📄 publish.sh # 发布脚本
│
└── 📁 docs/ # 文档目录
├── 📄 API.md # API 文档
└── 📄 TROUBLESHOOTING.md # 故障排除
```
## 🚀 快速开始
### 1. 安装（任选一种方式）
#### 方式 A：从源码安装（推荐）
```bash
# 克隆或下载项目
git clone https://github.com/yourusername/chatlog-mcp-server.git
cd chatlog-mcp-server
# 安装
pip install -e .
# 验证安装
chatlog-mcp --version
```
#### 方式 B：使用安装脚本
**Linux/macOS:**
```bash
chmod +x install.sh
./install.sh
```
**Windows:**
```cmd
install.bat
```
#### 方式 C：直接安装（如果有发布到 PyPI）
```bash
pip install chatlog-mcp-server
```
### 2. 配置 MCP 客户端
创建配置文件 `~/.config/claude/mcp-servers.json` (Linux/macOS) 或 `%APPDATA%\Claude\mcp-servers.json` (Windows):
```json
{
"mcpServers": {
"chatlog": {
"command": "chatlog-mcp",
"args": [],
"env": {
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
### 3. 使用
在 Claude Code 中直接说:
```
Use the chatlog tool to list chatrooms
```
## 📋 核心文件说明
### 安装和配置
| 文件 | 描述 |
|------|------|
| `setup.py` | Python 包安装配置文件 |
| `requirements.txt` | 依赖包列表 |
| `install.sh` | Linux/macOS 自动安装脚本 |
| `install.bat` | Windows 自动安装脚本 |
| `README.md` | 项目说明文档 |
| `LICENSE` | MIT 许可证 |
### 核心代码
| 文件 | 描述 |
|------|------|
| `chatlog_mcp/__init__.py` | 包初始化文件 |
| `chatlog_mcp/server.py` | MCP 服务器实现 |
| `chatlog_mcp/cli.py` | 命令行入口 |
### 示例和测试
| 文件 | 描述 |
|------|------|
| `chatlog_mcp/examples/analyze.py` | 数据分析示例脚本 |
| `chatlog_mcp/examples/mcp-servers.json` | MCP 配置示例 |
| `chatlog_mcp/tests/test_server.py` | 单元测试 |
### 构建和发布
| 文件 | 描述 |
|------|------|
| `build.py` | 构建脚本 |
| `publish.sh` | 发布到 PyPI 脚本 |
| `MANIFEST.in` | 包文件清单 |
### 文档
| 文件 | 描述 |
|------|------|
| `CONTRIBUTING.md` | 贡献指南 |
| `README.md` | 项目说明 |
## 🛠️ 开发指南
### 本地开发
```bash
# 克隆项目
git clone https://github.com/yourusername/chatlog-mcp-server.git
cd chatlog-mcp-server
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/macOS
# 或 venv\Scripts\activate # Windows
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest
# 格式化代码
black chatlog_mcp/
flake8 chatlog_mcp/
```
### 构建包
```bash
# 清理构建文件
python build.py --clean
# 构建包
python build.py
# 检查包
twine check dist/*
```
### 发布到 PyPI
```bash
# 发布到测试 PyPI
./publish.sh --test
# 发布到生产 PyPI
./publish.sh --prod
```
## 📦 分发方式
### 方式 1: 源码分发
```bash
# 打包源码
tar -czf chatlog-mcp-server-1.0.0.tar.gz chatlog-mcp-server/
# 分发给用户
# 用户解压后:
cd chatlog-mcp-server
pip install -e .
```
### 方式 2: Wheel 分发
```bash
# 构建 Wheel
python -m build
# 分发 wheel 文件
# 用户安装:
pip install dist/chatlog_mcp_server-1.0.0-py3-none-any.whl
```
### 方式 3: PyPI 分发
```bash
# 发布到 PyPI
./publish.sh --prod
# 用户安装:
pip install chatlog-mcp-server
```
### 方式 4: Docker 分发
```bash
# 构建镜像
docker build -t chatlog-mcp-server .
# 分发镜像
# 用户使用:
docker run -it chatlog-mcp-server
```
## 🎯 完整使用示例
### 示例 1: 分析聊天记录
```bash
# 获取数据
curl "http://127.0.0.1:5030/api/v1/chatlog?time=2026-01-13&talker=123@chatroom&format=json" > data.json
# 分析数据
python -m chatlog_mcp.examples.analyze data.json --output report.html
```
### 示例 2: 批量分析
```python
import json
from chatlog_mcp.examples.analyze import analyze_chatlog
# 加载数据
with open('data.json', 'r') as f:
data = json.load(f)
# 分析
results = analyze_chatlog(data)
print(f"Total messages: {results['total_messages']}")
```
## 🔧 自定义配置
### 环境变量
| 变量 | 默认值 | 描述 |
|------|--------|------|
| `CHATLOG_API_URL` | `http://127.0.0.1:5030` | HTTP API 服务器地址 |
| `CHATLOG_LOG_LEVEL` | `info` | 日志级别 |
### 命令行参数
```bash
chatlog-mcp --help
```
## 📊 测试和质量保证
### 单元测试
```bash
# 运行所有测试
pytest
# 运行特定测试
pytest chatlog_mcp/tests/test_server.py
# 生成覆盖率报告
pytest --cov=chatlog_mcp
```
### 代码质量检查
```bash
# flake8 检查
flake8 chatlog_mcp/
# black 格式化
black chatlog_mcp/
# mypy 类型检查
mypy chatlog_mcp/
```
## 🚨 故障排除
### 常见问题
1. **安装失败**
- 检查 Python 版本: `python --version`
- 检查 pip: `pip --version`
- 升级 pip: `pip install --upgrade pip`
2. **命令不存在**
- 确保安装完成: `pip list | grep chatlog`
- 检查 PATH 环境变量
- 尝试: `python -m chatlog_mcp.cli`
3. **MCP 连接失败**
- 检查 HTTP API 服务器是否运行
- 验证 API URL: `curl http://127.0.0.1:5030/api/v1/chatroom`
### 调试模式
```bash
# 启用调试日志
export CHATLOG_LOG_LEVEL=debug
chatlog-mcp
# 或者修改配置
{
"env": {
"PYTHONIOENCODING": "utf-8",
"CHATLOG_LOG_LEVEL": "debug"
}
}
```
## 📚 文档资源
- **README.md**: 项目概述和快速开始
- **CONTRIBUTING.md**: 贡献指南
- **API.md**: API 文档
- **TROUBLESHOOTING.md**: 故障排除指南
## 🎉 总结
我们已经创建了一个完整的、可复用的 MCP 服务包，包含:
✅ **完整的项目结构**
✅ **自动化安装脚本**
✅ **详细的文档**
✅ **单元测试**
✅ **示例代码**
✅ **构建和发布工具**
用户现在可以通过以下方式使用:
1. **pip install** - 直接安装
2. **克隆源码** - 本地安装
3. **Docker** - 容器化部署
4. **PyPI** - 包管理器安装
这个包已经完全准备好分发给其他人使用!
---
*最后更新: 2026-01-14*
