使用说明

Tempo MCP服务器

模型上下文协议（MCP）服务器，提供与Tempo Cloud API的无缝集成，用于工作日志管理。该服务器使像Claude这样的人工智能助手能够与您的Tempo工作日志、帐户和时间跟踪数据进行交互。

🚀 特性

工作日志管理

列出工作日志 -按日期范围、用户、项目或问题获取工作日志
创建工作日志 -添加带有描述和属性的新时间条目
更新工作日志 -修改现有时间条目
删除工作日志 -删除不需要的条目
获取工作日志详细信息 -检索特定工作日志的详细信息

帐户和属性管理

列出帐户 -获取可用的Tempo帐户
列出工作属性 -检索自定义工作属性及其值
账户分析 -获取特定帐户的时间跟踪数据

搜索和报告

高级工作日志搜索 -按多个条件筛选
时间跟踪报告 -生成摘要和分析
用户生产力洞察 -跨项目和问题跟踪时间

📋 先决条件

Tempo云实例 具有API访问权限
Tempo API代币 -从Tempo设置生成→ API集成
码头工人 （适用于集装箱设置）或 Python 3.8+ （用于本地设置）
MCP兼容客户端 （克劳德桌面、带MCP扩展的VS Code等）

🐳 安装（Docker-推荐）

快速Docker设置

# Clone the repository
git clone https://github.com/seggit/tempo-mcp-server.git
cd tempo-mcp-server

# Run the automated Docker setup
chmod +x docker-setup.sh
./docker-setup.sh

此脚本将：

✅ 检查Docker安装
✅ 构建Docker镜像
✅ 设置环境配置
✅ 测试容器
✅ 生成MCP客户端配置

手动Docker设置

# Build the Docker image
docker build -t tempo-mcp-server .

# Create environment file
cp .env.example .env
# Edit .env and add your TEMPO_API_TOKEN

# Test the server
./docker-wrapper.sh --test

# Use with Docker Compose
docker compose up tempo-mcp-server

🛠️ 安装（本地Python）

选项1：紫外线快速入门（推荐）

# Clone the repository
git clone https://github.com/seggit/tempo-mcp-server.git
cd tempo-mcp-server

# Install with UV (fastest)
uvx tempo-mcp-server

选项2：开发设置

# Clone the repository
git clone https://github.com/seggit/tempo-mcp-server.git
cd tempo-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

⚙️ 配置

1.Tempo API代币

获取Tempo API代币：

前往Tempo→ 设置→ API集成
创建具有适当权限的新令牌
复制令牌（您需要它进行配置）

2.环境变量

创建一个 .env 项目根目录中的文件：

TEMPO_API_TOKEN=your_tempo_api_token_here
TEMPO_BASE_URL=https://api.tempo.io/4

3.MCP客户端配置

适用于Claude Desktop（Docker）

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "tempo": {
      "command": "/absolute/path/to/tempo-mcp-server/docker-wrapper.sh",
      "args": ["--mcp"],
      "env": {
        "TEMPO_API_TOKEN": "your_tempo_api_token_here"
      }
    }
  }
}

适用于Claude Desktop（本地Python）

{
  "mcpServers": {
    "tempo": {
      "command": "python",
      "args": ["/path/to/tempo-mcp-server/src/tempo_mcp_server/server.py"],
      "env": {
        "TEMPO_API_TOKEN": "your_tempo_api_token_here"
      }
    }
  }
}

适用于带有MCP扩展的VS代码（Docker）

添加到您的 .vscode/mcp.json:

{
  "servers": {
    "tempo": {
      "command": "/absolute/path/to/tempo-mcp-server/docker-wrapper.sh",
      "args": ["--mcp"],
      "env": {
        "TEMPO_API_TOKEN": "your_tempo_api_token_here",
        "TEMPO_DEBUG": "false"
      }
    }
  }
}

用于带MCP扩展的VS代码（本地Python）

{
  "servers": {
    "tempo": {
      "command": "python",
      "args": ["/path/to/tempo-mcp-server/src/tempo_mcp_server/server.py"],
      "env": {
        "TEMPO_API_TOKEN": "your_tempo_api_token_here",
        "TEMPO_DEBUG": "false"
      }
    }
  }
}

🚀 用法

基本示例

列出今天的工作日志：
```
Show me all worklogs for today
```

创建新的工作日志：

Create a worklog for 2 hours on issue DEV-123 with description "Fixed login bug"

获取项目时间摘要：

How much time was logged on project XYZ this week?

按用户查找工作日志：

Show all worklogs by john.doe@company.com this month

高级用法

Create a worklog for 3.5 hours on issue PROJ-456 starting at 9:00 AM today with:
- Description: "API integration development"
- Account: Development
- Work category: External

🐳 Docker命令

Docker基本用法

# Build image
docker build -t tempo-mcp-server .

# Run server (interactive)
./docker-wrapper.sh

# Run with debug logging
./docker-wrapper.sh --test

# Force rebuild image
./docker-wrapper.sh --build

# Get help
./docker-wrapper.sh --help

Docker编写用法

# Start production server
docker compose up tempo-mcp-server

# Start development server (with volume mounts)
docker compose --profile dev up tempo-mcp-dev

# Run tests in container
docker compose --profile test up tempo-mcp-test

# Run in background
docker compose up -d tempo-mcp-server

容器管理

# View logs
docker logs tempo-mcp-server

# Access container shell
docker exec -it tempo-mcp-server bash

# Stop all containers
docker compose down

# Clean up everything
docker compose down -v --rmi all

🔧 发展

运行测试

# Install test dependencies
pip install -e ".[test]"

# Run tests (local)
pytest tests/

# Run tests (Docker)
docker compose --profile test up tempo-mcp-test

# Run with coverage
pytest --cov=src/tempo_mcp_server tests/

使用MCP检查器进行开发

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run the inspector (local)
mcp-inspector python src/tempo_mcp_server/server.py

# Run the inspector (Docker)
mcp-inspector ./docker-wrapper.sh

速率限制

Tempo API的费率限制为 每秒5个请求服务器自动处理速率限制，并实现指数回退的重试逻辑。

📚 api参考

可用工具

工具	说明	参数
`get_worklogs`	按条件检索工作日志	`from`, `to`, `user`, `project`, `issue`
`create_worklog`	创建新的工作日志条目	`issue_id`, `time_spent`, `description`, `start_date`
`update_worklog`	更新现有工作日志	`worklog_id`, `time_spent`, `description`
`delete_worklog`	删除工作日志	`worklog_id`
`get_accounts`	列出可用帐户	无
`get_work_attributes`	获取工作属性	无
`search_worklogs`	高级工作日志搜索	`query`, `filters`

可用资源

资源	描述
`worklog_summary`	每日/每周/每月时间总结
`user_productivity`	用户生产力报告
`project_analytics`	基于项目的时间分析

🐛 故障排除

常见问题

身份验证错误：
- 验证您的API令牌是否正确
- 检查Tempo设置中的令牌权限
- 确保令牌未过期
速率限制：
- 服务器自动处理速率限制
- 对于批量操作，考虑使用较小的批量
MCP连接问题：
- 验证MCP配置中的Python路径（本地）或Docker包装器路径（Docker）
- 检查环境变量是否已设置
- 查看服务器日志以了解详细错误
Docker问题：
- 确保Docker正在运行： docker info
- 检查图像是否存在： docker images | grep tempo-mcp-server
- 如有需要，进行重建： ./docker-wrapper.sh --build
- 查看日志： docker logs tempo-mcp-server

调试模式

本地Python：

TEMPO_DEBUG=true python src/tempo_mcp_server/server.py

Docker：

./docker-wrapper.sh --test
# or
docker compose --profile dev up tempo-mcp-dev

部署选项

方法	最佳	优点	缺点
码头工人	生产，易于设置	独立、一致、易于部署	需要Docker
本地Python	开发，轻量级	直接控制，更容易调试	需要环境设置
Docker Compose	开发、多服务	易于编排、批量装载	更复杂的设置

🤝 贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

Anthropic 对于模型上下文协议
节奏为其全面的API
MCP社区的灵感和例子

📞 支持

🐛 Bug报告： GitHub问题
💡 功能请求： GitHub讨论
📖 文档： 维基

注：此服务器使用Tempo API v4.0。确保您的Tempo实例支持此版本。