Rize MCP Server

Rize MCP 服务器

A. 模型上下文协议（MCP） 提供无缝集成的服务器 里泽 时间追踪和生产力API。该服务器采用FastMCP构建，向Claude等AI助手提供了Rize强大的时间追踪功能。

    

特点/功能

🎯 时间追踪

• 开始/停止计时器为项目和任务控制时间追踪会话
• 当前会话检查活跃的时间追踪会话
• 手动时间输入以自定义描述追溯记录日志时间
• 时间总结获取包含专注时间、会议时间及细分详情的详细分析报告

📊 生产力洞察

• 应用程序与网站查看您使用过哪些应用程序和网站，以及使用了多长时间
• 任务时间记录检索特定任务的时间记录
• 项目工时记录获取详细的项目级时间跟踪数据
• 类别活动的自动分类（开发、沟通等）

🏗️ 项目管理

• 列出项目浏览所有包含客户信息的Rize项目
• 项目详情访问项目元数据、状态和使用历史

🛡️ 坚固可靠

• 100%测试覆盖率包含109个通过测试的全面测试套件
• 自动重试对于失败的请求，采用指数退避策略
• 速率限制内置速率限制处理
• 错误恢复优雅的错误处理，配以详细的日志记录
• 输入验证强大的日期时间解析功能，支持自动回退

安装

先决条件

• Python 3.12或更高版本
• 紫外线 包管理器
• 一个具有API访问权限的Rize账户

从GitHub安装

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

# Install dependencies
uv pip install -e .

配置

获取您的Rize API密钥

1. 登录您的Rize账户于 rize.io（注：这是一个域名或特定服务的名称，直接翻译可能无法准确传达其含义，因此保持原样）
2. 导航至设置 → API
3. 生成一个新的API密钥
4. 复制密钥以用于配置

为Claude Desktop/Cursor进行配置

在您的MCP配置文件中添加：

对于Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rize": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/rize-mcp-server",
        "run",
        "rize-mcp"
      ],
      "env": {
        "RIZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

对于Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "rize": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/rize-mcp-server",
        "run",
        "rize-mcp"
      ],
      "env": {
        "RIZE_API_KEY": "your-api-key-here"
      }
    }
  }
}

环境变量

可用工具

定时器管理

start_timer

为项目或任务启动一个新的时间追踪会话。

# Start timer for a project
start_timer(project_id="proj_abc123")

# Start timer for a specific task
start_timer(project_id="proj_abc123", task_id="task_xyz789")

stop_timer

停止当前正在运行的时间追踪会话。

stop_timer()

get_current_session

检查是否有一个正在进行的时间跟踪会话。

session = get_current_session()
if session:
    print(f"Currently tracking: {session['title']}")

手动时间输入

log_time

为过去的工作创建手动时间记录。

# Log 3.5 hours for yesterday
log_time(
    project_id="proj_abc123",
    hours=3.5,
    entry_date="2024-01-15",
    description="Implemented login feature"
)

分析与报告

get_time_summary

获取指定日期范围的全面时间追踪分析。

# Get this week's summary
summary = get_time_summary(
    start_date="2024-01-15",
    end_date="2024-01-21",
    bucket_size="day"  # Options: day, week, month
)

# Returns: tracked time, focus time, meeting time, break time, category breakdowns

get_apps_and_websites

查看你使用过哪些应用程序和网站，以及使用了多长时间。

# Get last 30 days (default)
apps = get_apps_and_websites()

# Get specific date range
apps = get_apps_and_websites(
    start_time="2024-01-01T00:00:00Z",
    end_time="2024-01-31T23:59:59Z"
)

# Returns structured response with:
# - entries: List of apps/websites with time spent
# - count: Number of entries
# - message: Human-readable status

get_task_time_entries

检索任务的详细时间记录。

# Get task entries for last 30 days
entries = get_task_time_entries()

# Get specific date range
entries = get_task_time_entries(
    start_time="2024-01-15T00:00:00Z",
    end_time="2024-01-22T00:00:00Z"
)

get_project_time_entries

检索项目的详细时间记录。

# Get project entries for last 30 days
entries = get_project_time_entries()

# Get specific date range
entries = get_project_time_entries(
    start_time="2024-01-15T00:00:00Z",
    end_time="2024-01-22T00:00:00Z"
)

项目管理

list_projects

浏览您所有的Rize项目。

projects = list_projects()
# Returns: List of projects with IDs, names, status, client info, etc.

响应格式

所有时间记录和分析工具都会返回结构化响应：

{
  "entries": [...],
  "count": 42,
  "start_time": "2024-01-15T00:00:00Z",
  "end_time": "2024-01-22T00:00:00Z",
  "message": "Found 42 task time entries"
}

这确保了即使在条目列表为空的情况下，AI助手也能始终获得有意义的回复。

发展

设置开发环境

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

# Install with development dependencies
uv pip install -e '.[dev]'

# Set up pre-commit hooks (optional)
pre-commit install

运行测试

# Run full test suite with coverage
invoke test

# Run specific test file
pytest tests/unit/test_time_tracking.py -v

# Run with coverage report
pytest tests/ --cov=src --cov-report=html

代码质量

# Format code
invoke format

# Run linter
invoke lint

# Type checking
invoke typecheck

# Run all checks
invoke check

项目结构

rize-mcp-server/
├── src/
│   ├── config.py           # Configuration management
│   ├── server.py           # MCP server entry point
│   ├── models/             # Data models
│   │   ├── errors.py       # Error types
│   │   ├── query.py        # GraphQL query models
│   │   └── retry.py        # Retry configuration
│   ├── tools/              # MCP tool implementations
│   │   ├── query.py        # Custom GraphQL queries
│   │   └── time_tracking.py  # Time tracking operations
│   └── utils/              # Utility functions
│       ├── graphql.py      # GraphQL client
│       ├── logging.py      # JSON logging
│       └── retry.py        # Retry logic with backoff
├── tests/
│   ├── unit/               # Unit tests (100% coverage)
│   └── contract/           # MCP protocol compliance tests
└── scripts/                # Development scripts

建筑学

技术栈

• FastMCPMCP服务器框架
• httpxGraphQL的异步HTTP客户端
• Pydantic数据验证和设置
• pytest测试框架
• mypy（注：mypy是一个用于Python类型检查的工具，直接翻译为中文即“mypy”，在中文语境下通常保持原名，不进行额外翻译。）静态类型检查
• “ruff”可以翻译成中文为“粗糙的”或者“粗犷的”，具体取决于上下文和语境。如果是指外观或质地，可能翻译为“粗糙的”；如果是指性格或风格，可能翻译为“粗犷的”快速的Python代码检查器和格式化工具

关键特性

• 以异步优先所有输入/输出操作均使用 async/await
• 类型安全带有严格mypy检查的完整类型提示
• 已测试109项测试，代码覆盖率100%
• 有韧性的具有速率限制处理的指数退避重试逻辑
• 可观察的结构化JSON日志记录，包含凭证信息的脱敏处理
• 可配置的基于环境的配置并包含验证

故障排除

常见问题

在Cursor/Claude中出现“工具未返回结果”错误

在v1.0版本中，此问题已通过返回包含元数据的结构化响应得到解决。请确保您运行的是最新版本。

日期时间参数错误

服务器现在包含了强大的日期时间验证功能，并具备自动回退机制。空的或截断的日期时间字符串会自动更正为合理的默认值（最近30天）。

速率限制错误

服务器会自动处理带指数退避的速率限制。如果您持续看到速率限制错误，请检查Rize帐户设置中的API使用配额。

调试

启用调试日志以查看详细信息：

export LOG_LEVEL=DEBUG
export LOG_FORMAT=text  # For human-readable logs

贡献

欢迎贡献！请随时提交拉取请求。对于重大更改，请先打开一个问题进行讨论，说明您想要做出的更改。

开发工作流程

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支（git checkout -b feature/amazing-feature）
3. 做出你的更改
4. 运行测试（invoke check)
5. 提交您的更改（git commit -m 'Add amazing feature'）
6. 推送至分支（git push origin feature/amazing-feature)
7. 提交一个拉取请求

许可证

这个项目遵循MIT许可证授权——详见 许可证 文件中有详细信息。

作者

特洛伊·拉森

• 电子邮箱： troy@troylarson.com（这个邮箱地址本身在中文中没有直接的翻译，但可以解释为“特洛伊·拉森（Troy Larson）的电子邮件地址是troy@troylarson.com”）
• GitHub： @troylar

致谢

• 用……建造/构建 FastMCP 由Marvin AI创作
• 由……提供动力/支持 里泽 时间追踪API
• 遵循 模型上下文协议 规范；规格说明

支持

对于问题、疑问或贡献：

• 🐛 蝴蝶（或表示小错误、问题的“bug”） 报告一个错误
• 💡（这个表情符号在中文里通常被理解为“灯泡”或“灵感”的意思，可以翻译为“灵感来了”或“点子来了”等，具体根据上下文而定。） 请求添加一个功能
• 📧 电子邮件（electronic mail）的符号 电子邮件支持

链接

• Rize API 文档
• Rize GraphQL 探索器
• 模型上下文协议规范
• FastMCP 文档

______________________________________________________________________

Made with ❤️ by Troy Larson