Rize AI Scheduler

A Python-based Rize.io API client and MCP (Model Context Protocol) server for integrating with the Rize time tracking application through Claude Desktop.

Project Status

Current Core Feature: Create Session

The primary fully-implemented and thoroughly tested feature of this project is Create Session - a robust, production-ready capability. Other features are either in development or planned for future expansion.

Core Feature: Create Session (Fully Functional)

Feature Highlights

create_session is the flagship implementation of this project, offering flexible and powerful work session creation:

Implemented and Tested Capabilities

Flexible Time Handling (4 Time Specification Modes)
- Both start and end time specified: Precise control over session timeframe
- Only start time specified: Automatically calculates end time based on duration
- Only end time specified: Automatically calculates start time based on duration
- No time specified: Uses current time as start, calculates end time from duration

Multi-Format Time Parsing

Supports the following ISO8601 time formats:

2024-07-21T09:00:00
2024-07-21 09:00:00
2024-07-21T09:00
2024-07-21 09:00
2024-07-21T09:00:00Z

Session Type Support
- focus - Focus work session (default)
- break - Break time
Optional Metadata
- Session title
- Session description
Flexible Duration Control
- Default duration: 90 minutes
- Customizable to any duration

Usage Examples

Direct Code Usage (RizeClient)

import asyncio
from src.rize_client import RizeClient

async def main():
    # Initialize client
    client = RizeClient(
        api_token="your_token_here",
        api_url="https://api.rize.io/api/v1/graphql"
    )

    # Example 1: Create default session (current time, 90 minutes)
    result = await client.create_session()

    # Example 2: Specify start time and duration
    result = await client.create_session(
        session_type="focus",
        title="Deep Work: Write Project Documentation",
        description="Complete README and API docs",
        duration_minutes=120,
        start_time="2024-07-21T09:00:00"
    )

    # Example 3: Specify complete time range
    result = await client.create_session(
        session_type="focus",
        title="Code Review Meeting",
        start_time="2024-07-21T14:00:00",
        end_time="2024-07-21T15:30:00"
    )

    print(result)

asyncio.run(main())

Usage via MCP Server (Claude Desktop Integration)

In Claude Desktop, use natural language commands:

"Create a 2-hour focus session starting at 2pm titled 'Project Development'"
"Create a 90-minute work session starting now"
"Log a focus time block from 9am to 11am"

Technical Implementation Details

Code Location: src/rize_client.py:619-699

Core Function Signature:

async def create_session(
    self,
    session_type: str = "focus",
    title: Optional[str] = None,
    description: Optional[str] = None,
    duration_minutes: int = 90,
    start_time: Optional[str] = None,
    end_time: Optional[str] = None
) -> Dict[str, Any]

GraphQL Mutation Structure:

mutation CreateSession($input: CreateSessionInput!) {
    createSession(input: $input) {
        session {
            id
            title
            description
            createdAt
            updatedAt
            startTime
            endTime
            duration
            sessionType
        }
        errors {
            message
            path
        }
    }
}

Response Data Structure:

{
  "id": "session_123abc",
  "title": "Deep Work: Write Project Documentation",
  "description": "Complete README and API docs",
  "startTime": "2024-07-21T09:00:00Z",
  "endTime": "2024-07-21T11:00:00Z",
  "duration": 120,
  "sessionType": "focus",
  "createdAt": "2024-07-21T08:55:00Z",
  "updatedAt": "2024-07-21T08:55:00Z"
}

Other Basic Features

The following features are implemented but should be used with caution as they may require further testing and optimization:

Connection Testing

test_connection - Verify API connection and authentication

Project Management

list_projects - Retrieve project list
create_project - Create new project (basic functionality)
Note: Update and delete project operations are coded but not fully tested

Task Management

get_current_session - Retrieve current active session information
Note: Task create, update, and delete operations are coded but not fully tested

Session Timer

Caution: start_session_timer - Start session timer (partially functional, parameter structure may need adjustment)
Not Recommended: stop_session_timer - Stop session timer (incomplete implementation, not recommended)

Future Development Goals

The following features are supported by the Rize API but not yet implemented in this project. They are listed as future expansion directions:

Planned Features

Enhanced Session Timer Control
- Improve reliability of start/stop timer operations
- Implement session pause/resume functionality
- Implement extend current session duration
Time Entry Management
- Create client/project/task-level time entries
- Update and delete time entries
- Time entry queries and statistics
Client Management
- Create and manage client information
- Associate projects with clients
- Client-level time statistics
Advanced Query Features
- App and website usage tracking
- Time categorization and summary statistics
- Time budget tracking and alerts
Data Analysis and Reports
- Work productivity analysis
- Time distribution visualization
- Custom report exports
Comprehensive Task Management
- Task priority settings
- Task status tracking
- Task time budget management

Installation and Configuration

Requirements

Python 3.11+
Conda (recommended) or virtualenv

Installation Steps

Clone Repository

git clone <repository-url>
cd rize-ai-scheduler

Create Conda Environment

conda env create -f environment.yml
conda activate ClaudecodeDemo

Or use pip:

pip install -r requirements.txt

Configure Environment Variables

Copy .env.example to .env:
```
cp .env.example .env
```
Edit .env file and add your Rize API Token:
```
RIZE_API_TOKEN=your_rize_api_token_here
RIZE_API_URL=https://api.rize.io/api/v1/graphql
DEBUG=False
```
Steps to Obtain API Token:
1. Open Rize app
2. Go to Settings > API
3. Click "Generate new token"
4. Copy token and paste into .env file

Run Tests

Verify create_session functionality:

python src/test_basic_api.py

Start MCP Server

python src/server_simple.py

Project Structure

rize-ai-scheduler/
├── src/
│   ├── rize_client.py       # Rize API client core implementation
│   ├── server_simple.py     # MCP server (Claude Desktop integration)
│   └── test_basic_api.py    # Basic functionality tests
├── .env.example             # Environment variable template
├── requirements.txt         # Python dependencies
├── environment.yml          # Conda environment configuration
├── RizeIOAPIScheme          # Rize GraphQL API Schema
└── README.md               # Project documentation

Core Files Description

File	Size	Description
`src/rize_client.py`	28.7 KB	API client with complete `create_session` implementation
`src/server_simple.py`	18.1 KB	MCP server exposing 7 tool interfaces
`src/test_basic_api.py`	2.8 KB	Test script focusing on `create_session`
`RizeIOAPIScheme`	33 KB	Rize GraphQL Schema (JSON format)

Claude Desktop Integration

Configure Claude Desktop

Edit Claude Desktop configuration file to add MCP server:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "rize-scheduler": {
      "command": "python",
      "args": ["C:\\Users\\yeche\\Desktop\\rize-ai-scheduler\\src\\server_simple.py"],
      "env": {
        "RIZE_API_TOKEN": "your_token_here",
        "RIZE_API_URL": "https://api.rize.io/api/v1/graphql"
      }
    }
  }
}

Available MCP Tools

Currently exposed 7 tools:

Fully Functional: create_session - Create work session
Basic: test_connection - Test API connection
Basic: list_projects - List projects
Basic: create_project - Create project
Basic: get_current_session - Get current session
Caution: start_session_timer - Start timer (partially functional)
Not Recommended: stop_session_timer - Stop timer (not recommended)

Dependencies

mcp>=1.0.0                  # Model Context Protocol
httpx>=0.24.0               # Async HTTP client
graphql-core>=3.2.0         # GraphQL support
pydantic>=2.0.0             # Data validation
python-dotenv>=1.0.0        # Environment variable loading
colorama>=0.4.6             # Terminal colored output (Windows compatible)

Technical Architecture

Design Patterns

Async-First
- All API calls use asyncio and httpx.AsyncClient
- Supports high-concurrency request handling
Separation of Concerns
- RizeClient handles pure API communication
- server_simple.py adds MCP server wrapper with user-friendly responses
Multi-Layer Error Handling
- Network layer error handling (timeout, connection failures)
- HTTP error handling (401 auth, 429 rate limit, 5xx server errors)
- GraphQL error handling (field validation, business logic errors)
Cross-Platform Support
- Windows special handling (sets WindowsSelectorEventLoopPolicy)
- Emoji compatibility handling (Windows console)

API Response Structure

{
  "data": {
    "createSession": {
      "session": { ... },
      "errors": [
        {
          "message": "Error description",
          "path": ["field", "path"]
        }
      ]
    }
  },
  "errors": [...]  // GraphQL top-level errors
}

Known Limitations

Session Timer Functionality Unstable
- stop_session_timer has unclear input structure and may not work properly
- Recommend using create_session to log completed work sessions
Time Entry Not Implemented
- Supported in GraphQL Schema but not implemented in client code
- Important direction for future development
Some Features Not Fully Tested
- Project and task update/delete operations are coded but not verified in production
- Recommend testing in a test environment before use
Chinese Comments
- Code contains Chinese comments which may display incorrectly in some editors

Contributing

Issues and Pull Requests are welcome!

Priority Development Directions

Improve Session Timer Functionality - Confirm correct API input structure
Implement Time Entry Management - Complete Time Entry CRUD operations
Add Unit Tests - Improve code quality and stability
Enhance Error Handling - More user-friendly error messages and auto-retry mechanisms
Add English Comments - Improve code maintainability

Acknowledgments

Rize.io - Providing powerful time tracking API
Anthropic - Model Context Protocol specification

Project Status: Core Feature (Create Session) Stable & Production-Ready | Other Features In Development

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.claude		.claude
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
RizeIOAPIScheme		RizeIOAPIScheme
environment.yml		environment.yml
requirements.txt		requirements.txt

YeChen-coder/RizeIO-LocalMCPServer

Folders and files

Latest commit

History

Repository files navigation