@mnicole-dev/rize-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,194 @@
+# @mnicole-dev/rize-mcp-server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Rize](https://rize.io) time tracking GraphQL API. Track focus sessions, monitor app usage, manage projects/tasks/clients, and analyze productivity from any MCP-compatible client.
+
+## Features
+
+**34 tools** covering the full Rize GraphQL API:
+
+### User (1 tool)
+| Tool | Description |
+|------|-------------|
+| `get-me` | Get the authenticated user profile |
+
+### Summaries & Analytics (3 tools)
+| Tool | Description |
+|------|-------------|
+| `get-summaries` | Get time tracking summaries (focus, break, meeting, tracked time) with daily/weekly/monthly breakdown and optional category analysis |
+| `get-apps-and-websites` | Get app and website usage for a time range |
+| `get-categories` | Get time spent by category |
+
+### Sessions (7 tools)
+| Tool | Description |
+|------|-------------|
+| `list-sessions` | List focus/break/meeting sessions |
+| `get-current-session` | Get the currently active session |
+| `start-session-timer` | Start a focus, break, or meeting timer |
+| `stop-session-timer` | Stop the current timer |
+| `extend-current-session` | Extend the current timer by N minutes |
+| `create-session` | Create a manual session entry |
+| `update-session` | Update a session |
+| `delete-session` | Delete a session |
+
+### Projects (5 tools)
+| Tool | Description |
+|------|-------------|
+| `list-projects` | List all projects with time spent and budgets |
+| `get-project` | Get project details |
+| `create-project` | Create a project (with keywords, budget, client) |
+| `update-project` | Update a project |
+| `delete-project` | Delete a project |
+
+### Tasks (4 tools)
+| Tool | Description |
+|------|-------------|
+| `list-tasks` | List all tasks |
+| `create-task` | Create a task (with project, assignee, keywords) |
+| `update-task` | Update a task |
+| `delete-task` | Delete a task |
+
+### Clients (4 tools)
+| Tool | Description |
+|------|-------------|
+| `list-clients` | List all clients |
+| `create-client` | Create a client (with hourly rate, keywords) |
+| `update-client` | Update a client |
+| `delete-client` | Delete a client |
+
+### Time Entries (9 tools)
+| Tool | Description |
+|------|-------------|
+| `list-project-time-entries` | List time entries for projects |
+| `create-project-time-entry` | Log time against a project |
+| `delete-project-time-entry` | Delete a project time entry |
+| `list-task-time-entries` | List time entries for tasks |
+| `create-task-time-entry` | Log time against a task |
+| `delete-task-time-entry` | Delete a task time entry |
+| `list-client-time-entries` | List time entries for clients |
+| `create-client-time-entry` | Log time against a client |
+| `delete-client-time-entry` | Delete a client time entry |
+
+## Requirements
+
+- Node.js 18+
+- A Rize account with API access
+- An API key from [Settings > API](https://app.rize.io) in your Rize account
+
+## Installation
+
+```bash
+npm install -g @mnicole-dev/rize-mcp-server
+```
+
+Or run directly with `npx`:
+
+```bash
+npx @mnicole-dev/rize-mcp-server
+```
+
+## Configuration
+
+Set the `RIZE_API_KEY` environment variable:
+
+```bash
+export RIZE_API_KEY=your-api-key
+```
+
+### Claude Code
+
+Add to your `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "rize": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@mnicole-dev/rize-mcp-server"],
+      "env": {
+        "RIZE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "rize": {
+      "command": "npx",
+      "args": ["-y", "@mnicole-dev/rize-mcp-server"],
+      "env": {
+        "RIZE_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Examples
+
+### Weekly summary
+
+```
+> Show me my time tracking summary for this week
+```
+
+Calls `get-summaries` — returns tracked time, focus time, break time, meeting time, daily breakdown, and category analysis.
+
+### Start a focus session
+
+```
+> Start a 45 minute focus session for deep work
+```
+
+Calls `start-session-timer` with:
+```json
+{
+  "type": "focus",
+  "length": 45,
+  "intention": "deep work"
+}
+```
+
+### Check what apps you used
+
+```
+> What apps did I use today?
+```
+
+Calls `get-apps-and-websites` with today's date range — shows time spent per app with category labels.
+
+### Log time to a project
+
+```
+> Log 2 hours on project abc123 from 9am to 11am today
+```
+
+Calls `create-project-time-entry` with the project ID and time range.
+
+## How it works
+
+1. The MCP client sends a tool call to the server via stdio
+2. The server translates the call into a GraphQL query/mutation
+3. The request is sent to `https://api.rize.io/api/v1/graphql` with Bearer token auth
+4. The response is formatted as human-readable text and returned
+
+## Development
+
+```bash
+git clone https://github.com/mnicole-dev/rize-mcp-server.git
+cd rize-mcp-server
+pnpm install
+pnpm dev          # Run with tsx (requires RIZE_API_KEY)
+pnpm build        # Build to dist/
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,857 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var API_URL = "https://api.rize.io/api/v1/graphql";
+function getApiKey() {
+  const key = process.env["RIZE_API_KEY"];
+  if (!key) throw new Error("RIZE_API_KEY environment variable is required");
+  return key;
+}
+async function gql(query, variables) {
+  const resp = await fetch(API_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${getApiKey()}`
+    },
+    body: JSON.stringify({ query, variables })
+  });
+  const json = await resp.json();
+  if (json.errors?.length) {
+    throw new Error(json.errors.map((e) => e.message).join("; "));
+  }
+  return json.data;
+}
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function formatDuration(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  if (h === 0) return `${m}m`;
+  return m > 0 ? `${h}h${m}m` : `${h}h`;
+}
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+var server = new McpServer({
+  name: "rize-mcp-server",
+  version: "1.0.0"
+});
+server.tool("get-me", "Get the currently authenticated Rize user.", {}, async () => {
+  const data = await gql("{ currentUser { email name } }");
+  const u = data.currentUser;
+  return textResult(`**${u.name}**
+Email: ${u.email}`);
+});
+server.tool(
+  "get-summaries",
+  "Get time tracking summaries (focus, break, meeting, tracked time) for a date range.",
+  {
+    startDate: z.string().default("").describe("Start date (YYYY-MM-DD). Defaults to today."),
+    endDate: z.string().default("").describe("End date (YYYY-MM-DD). Defaults to today."),
+    bucketSize: z.enum(["day", "week", "month"]).default("day").describe("Bucket size for breakdown"),
+    includeCategories: z.boolean().default(false).describe("Include category breakdown")
+  },
+  async (params) => {
+    const start = params.startDate || today();
+    const end = params.endDate || today();
+    const data = await gql(
+      `query($start: ISO8601Date!, $end: ISO8601Date!, $bucket: String!, $cats: Boolean) {
+        summaries(startDate: $start, endDate: $end, bucketSize: $bucket, includeCategories: $cats) {
+          startTime endTime bucketSize
+          trackedTime trackedTimeAverage
+          focusTime focusTimeAverage
+          breakTime breakTimeAverage
+          meetingTime meetingTimeAverage
+          workHours workHoursAverage workHoursTarget
+          buckets { date wday trackedTime focusTime breakTime meetingTime workHours pto }
+          categories { category { name key work focus } timeSpent }
+        }
+      }`,
+      { start, end, bucket: params.bucketSize, cats: params.includeCategories }
+    );
+    const s = data.summaries;
+    const lines = [
+      `**Summary ${start} \u2192 ${end}**`,
+      `Tracked: ${formatDuration(s.trackedTime)} | Focus: ${formatDuration(s.focusTime)} | Break: ${formatDuration(s.breakTime)} | Meeting: ${formatDuration(s.meetingTime)}`,
+      `Work hours: ${formatDuration(s.workHours)} / ${formatDuration(s.workHoursTarget)} target`
+    ];
+    if (s.buckets.length > 0 && s.buckets.length <= 31) {
+      lines.push("", "**Daily breakdown:**");
+      for (const b of s.buckets) {
+        const pto = b.pto ? " [PTO]" : "";
+        lines.push(
+          `- ${b.date} (${b.wday}): tracked ${formatDuration(b.trackedTime)}, focus ${formatDuration(b.focusTime)}, work ${formatDuration(b.workHours)}${pto}`
+        );
+      }
+    }
+    if (s.categories?.length) {
+      lines.push("", "**Categories:**");
+      for (const c of s.categories.sort((a, b) => b.timeSpent - a.timeSpent).slice(0, 15)) {
+        lines.push(`- ${c.category.name}: ${formatDuration(c.timeSpent)}`);
+      }
+    }
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "get-apps-and-websites",
+  "Get apps and websites usage for a time range, showing where time was spent.",
+  {
+    startTime: z.string().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().describe("End datetime (ISO 8601)")
+  },
+  async ({ startTime, endTime }) => {
+    const data = await gql(
+      `query($start: ISO8601DateTime, $end: ISO8601DateTime) {
+        appsAndWebsites(startTime: $start, endTime: $end) {
+          appName title url urlHost type timeSpent
+          timeCategory { name key work focus }
+        }
+      }`,
+      { start: startTime, end: endTime }
+    );
+    const apps = data.appsAndWebsites.sort((a, b) => b.timeSpent - a.timeSpent).slice(0, 30);
+    if (apps.length === 0) return textResult("No app/website activity found.");
+    const lines = apps.map((a) => {
+      const cat = a.timeCategory ? ` [${a.timeCategory.name}]` : "";
+      const host = a.urlHost ? ` (${a.urlHost})` : "";
+      return `- **${a.appName || a.title}**${host}: ${formatDuration(a.timeSpent)}${cat}`;
+    });
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "get-categories",
+  "Get time spent by category for a time range.",
+  {
+    startTime: z.string().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().describe("End datetime (ISO 8601)")
+  },
+  async ({ startTime, endTime }) => {
+    const data = await gql(
+      `query($start: ISO8601DateTime, $end: ISO8601DateTime) {
+        categories(startTime: $start, endTime: $end) {
+          category { name key work focus idle } timeSpent
+        }
+      }`,
+      { start: startTime, end: endTime }
+    );
+    const cats = data.categories.sort((a, b) => b.timeSpent - a.timeSpent);
+    if (cats.length === 0) return textResult("No category data found.");
+    const lines = cats.map((c) => {
+      const tags = [
+        c.category.work ? "work" : "",
+        c.category.focus ? "focus" : "",
+        c.category.idle ? "idle" : ""
+      ].filter(Boolean).join(", ");
+      return `- **${c.category.name}**: ${formatDuration(c.timeSpent)}${tags ? ` (${tags})` : ""}`;
+    });
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "list-sessions",
+  "List focus/break/meeting sessions for a time range.",
+  {
+    startTime: z.string().optional().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().optional().describe("End datetime (ISO 8601)"),
+    sort: z.enum(["created_at", "updated_at", "start_time"]).default("start_time").describe("Sort order")
+  },
+  async (params) => {
+    const data = await gql(
+      `query($start: ISO8601DateTime, $end: ISO8601DateTime, $sort: TimeEntrySortEnum) {
+        sessions(startTime: $start, endTime: $end, sort: $sort) {
+          id title description type source startTime endTime
+        }
+      }`,
+      { start: params.startTime, end: params.endTime, sort: params.sort }
+    );
+    if (data.sessions.length === 0) return textResult("No sessions found.");
+    const lines = data.sessions.map((s) => {
+      const title = s.title ? ` \u2014 ${s.title}` : "";
+      const desc = s.description ? ` (${s.description})` : "";
+      const end = s.endTime ? s.endTime.slice(11, 16) : "running";
+      return `- **[${s.type}]** ${s.startTime.slice(0, 10)} ${s.startTime.slice(11, 16)}\u2192${end}${title}${desc} (id: ${s.id})`;
+    });
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "get-current-session",
+  "Get the currently active session (focus, break, or meeting).",
+  {},
+  async () => {
+    const data = await gql(
+      `{ currentSession { id title description type source startTime endTime } }`
+    );
+    if (!data.currentSession) return textResult("No active session.");
+    const s = data.currentSession;
+    const title = s.title ? `
+Title: ${s.title}` : "";
+    const desc = s.description ? `
+Description: ${s.description}` : "";
+    return textResult(
+      `**Active session: ${s.type}**
+Started: ${s.startTime}${title}${desc}
+ID: ${s.id}`
+    );
+  }
+);
+server.tool(
+  "start-session-timer",
+  "Start a new focus, break, or meeting session timer.",
+  {
+    type: z.enum(["focus", "break", "meeting", "custom", "other"]).describe("Session type"),
+    length: z.number().optional().describe("Duration in minutes"),
+    title: z.string().optional().describe("Session title"),
+    intention: z.string().optional().describe("What you intend to work on")
+  },
+  async (params) => {
+    const input = { type: params.type };
+    if (params.length) input["length"] = params.length;
+    if (params.title) input["title"] = params.title;
+    if (params.intention) input["intention"] = params.intention;
+    const data = await gql(
+      `mutation($input: StartSessionTimerInput!) {
+        startSessionTimer(input: $input) { session { id type title startTime } errors }
+      }`,
+      { input }
+    );
+    const s = data.startSessionTimer.session;
+    const title = s.title ? ` \u2014 ${s.title}` : "";
+    return textResult(`Session started!
+- **${s.type}**${title}
+- Started: ${s.startTime}
+- ID: ${s.id}`);
+  }
+);
+server.tool(
+  "stop-session-timer",
+  "Stop the currently running session timer.",
+  {},
+  async () => {
+    const data = await gql(
+      `mutation($input: StopSessionTimerInput!) {
+        stopSessionTimer(input: $input) { session { id type title startTime endTime } errors }
+      }`,
+      { input: {} }
+    );
+    const s = data.stopSessionTimer.session;
+    return textResult(`Session stopped!
+- **${s.type}** ${s.startTime.slice(11, 16)}\u2192${s.endTime.slice(11, 16)}
+- ID: ${s.id}`);
+  }
+);
+server.tool(
+  "extend-current-session",
+  "Extend the current session timer by a number of minutes.",
+  { length: z.number().describe("Minutes to extend by") },
+  async ({ length }) => {
+    const data = await gql(
+      `mutation($input: ExtendCurrentSessionInput!) {
+        extendCurrentSession(input: $input) { session { id type endTime } errors }
+      }`,
+      { input: { length } }
+    );
+    const s = data.extendCurrentSession.session;
+    return textResult(`Session extended!
+- **${s.type}** now ends at ${s.endTime.slice(11, 16)}
+- ID: ${s.id}`);
+  }
+);
+server.tool(
+  "create-session",
+  "Create a manual session entry.",
+  {
+    type: z.enum(["focus", "break", "meeting", "custom", "other"]).describe("Session type"),
+    startTime: z.string().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().describe("End datetime (ISO 8601)"),
+    title: z.string().optional().describe("Session title"),
+    description: z.string().optional().describe("Session description")
+  },
+  async (params) => {
+    const args = {
+      type: params.type,
+      startTime: params.startTime,
+      endTime: params.endTime
+    };
+    if (params.title) args["title"] = params.title;
+    if (params.description) args["description"] = params.description;
+    const data = await gql(
+      `mutation($input: CreateSessionInput!) {
+        createSession(input: $input) { session { id type title startTime endTime } errors }
+      }`,
+      { input: { args } }
+    );
+    const s = data.createSession.session;
+    return textResult(`Session created!
+- **${s.type}** ${s.startTime.slice(11, 16)}\u2192${s.endTime.slice(11, 16)}
+- ID: ${s.id}`);
+  }
+);
+server.tool(
+  "update-session",
+  "Update an existing session.",
+  {
+    id: z.string().describe("Session ID"),
+    title: z.string().optional().describe("New title"),
+    description: z.string().optional().describe("New description"),
+    type: z.enum(["focus", "break", "meeting", "custom", "other"]).optional().describe("New type"),
+    startTime: z.string().optional().describe("New start time (ISO 8601)"),
+    endTime: z.string().optional().describe("New end time (ISO 8601)")
+  },
+  async (params) => {
+    const args = { id: params.id };
+    if (params.title !== void 0) args["title"] = params.title;
+    if (params.description !== void 0) args["description"] = params.description;
+    if (params.type) args["type"] = params.type;
+    if (params.startTime) args["startTime"] = params.startTime;
+    if (params.endTime) args["endTime"] = params.endTime;
+    const data = await gql(
+      `mutation($input: UpdateSessionInput!) {
+        updateSession(input: $input) { session { id type title } errors }
+      }`,
+      { input: { args } }
+    );
+    const s = data.updateSession.session;
+    return textResult(`Session updated: **${s.type}**${s.title ? ` \u2014 ${s.title}` : ""} (id: ${s.id})`);
+  }
+);
+server.tool(
+  "delete-session",
+  "Delete a session by ID.",
+  { id: z.string().describe("Session ID") },
+  async ({ id }) => {
+    await gql(
+      `mutation($input: DeleteSessionInput!) { deleteSession(input: $input) { session { id } errors } }`,
+      { input: { id } }
+    );
+    return textResult(`Session ${id} deleted.`);
+  }
+);
+server.tool(
+  "list-projects",
+  "List all projects.",
+  {
+    query: z.string().optional().describe("Search by name"),
+    sort: z.enum(["created_at", "updated_at", "last_used_at"]).optional().describe("Sort order")
+  },
+  async (params) => {
+    const vars = {};
+    if (params.query) vars["query"] = params.query;
+    if (params.sort) vars["sort"] = params.sort;
+    const data = await gql(
+      `query($query: String, $sort: SortEnum) {
+        projects(query: $query, sort: $sort, first: 100) {
+          nodes { id name status color emoji totalTimeSpent timeBudget timeBudgetInterval client { name } }
+        }
+      }`,
+      vars
+    );
+    const projects = data.projects.nodes;
+    if (projects.length === 0) return textResult("No projects found.");
+    const lines = projects.map((p) => {
+      const client = p.client ? ` \u2014 ${p.client.name}` : "";
+      const budget = p.timeBudget ? ` / ${formatDuration(p.timeBudget)} budget` : "";
+      const emoji = p.emoji ? `${p.emoji} ` : "";
+      return `- ${emoji}**${p.name}**${client}: ${formatDuration(p.totalTimeSpent)}${budget} [${p.status}] (id: ${p.id})`;
+    });
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "get-project",
+  "Get a project by ID.",
+  { id: z.string().describe("Project ID") },
+  async ({ id }) => {
+    const data = await gql(
+      `query($id: ID!) { project(id: $id) { id name status color emoji totalTimeSpent timeBudget timeBudgetInterval keywords client { name } } }`,
+      { id }
+    );
+    const p = data.project;
+    const client = p.client ? `
+Client: ${p.client.name}` : "";
+    const budget = p.timeBudget ? `
+Budget: ${formatDuration(p.timeBudget)} per ${p.timeBudgetInterval}` : "";
+    const kw = p.keywords?.length ? `
+Keywords: ${p.keywords.join(", ")}` : "";
+    return textResult(`**${p.name}**
+Status: ${p.status}
+Total time: ${formatDuration(p.totalTimeSpent)}${budget}${client}${kw}
+ID: ${p.id}`);
+  }
+);
+server.tool(
+  "create-project",
+  "Create a new project.",
+  {
+    name: z.string().describe("Project name"),
+    color: z.string().optional().describe("Color hex code"),
+    emoji: z.string().optional().describe("Emoji"),
+    keywords: z.array(z.string()).optional().describe("Keywords for auto-categorization"),
+    timeBudget: z.number().optional().describe("Time budget in seconds"),
+    timeBudgetInterval: z.string().optional().describe('Budget interval (e.g. "weekly")'),
+    clientName: z.string().optional().describe("Client name to associate")
+  },
+  async (params) => {
+    const args = { name: params.name };
+    if (params.color) args["color"] = params.color;
+    if (params.emoji) args["emoji"] = params.emoji;
+    if (params.keywords) args["keywords"] = params.keywords;
+    if (params.timeBudget) args["timeBudget"] = params.timeBudget;
+    if (params.timeBudgetInterval) args["timeBudgetInterval"] = params.timeBudgetInterval;
+    if (params.clientName) args["clientName"] = params.clientName;
+    const data = await gql(
+      `mutation($input: CreateProjectInput!) { createProject(input: $input) { project { id name } errors } }`,
+      { input: { args } }
+    );
+    return textResult(`Project created: **${data.createProject.project.name}** (id: ${data.createProject.project.id})`);
+  }
+);
+server.tool(
+  "update-project",
+  "Update an existing project.",
+  {
+    id: z.string().describe("Project ID"),
+    name: z.string().optional().describe("New name"),
+    status: z.string().optional().describe("New status"),
+    color: z.string().optional().describe("Color hex code"),
+    emoji: z.string().optional().describe("Emoji"),
+    keywords: z.array(z.string()).optional().describe("Keywords"),
+    timeBudget: z.number().optional().describe("Time budget in seconds"),
+    timeBudgetInterval: z.string().optional().describe("Budget interval")
+  },
+  async (params) => {
+    const args = { id: params.id };
+    if (params.name) args["name"] = params.name;
+    if (params.status) args["status"] = params.status;
+    if (params.color) args["color"] = params.color;
+    if (params.emoji) args["emoji"] = params.emoji;
+    if (params.keywords) args["keywords"] = params.keywords;
+    if (params.timeBudget !== void 0) args["timeBudget"] = params.timeBudget;
+    if (params.timeBudgetInterval) args["timeBudgetInterval"] = params.timeBudgetInterval;
+    const data = await gql(
+      `mutation($input: UpdateProjectInput!) { updateProject(input: $input) { project { id name } errors } }`,
+      { input: { args } }
+    );
+    return textResult(`Project updated: **${data.updateProject.project.name}** (id: ${data.updateProject.project.id})`);
+  }
+);
+server.tool(
+  "delete-project",
+  "Delete a project by ID.",
+  { id: z.string().describe("Project ID") },
+  async ({ id }) => {
+    await gql(
+      `mutation($input: DeleteProjectInput!) { deleteProject(input: $input) { project { id } errors } }`,
+      { input: { id } }
+    );
+    return textResult(`Project ${id} deleted.`);
+  }
+);
+server.tool(
+  "list-tasks",
+  "List all tasks.",
+  {
+    query: z.string().optional().describe("Search by name"),
+    sort: z.enum(["created_at", "updated_at", "last_used_at"]).optional().describe("Sort order")
+  },
+  async (params) => {
+    const vars = {};
+    if (params.query) vars["query"] = params.query;
+    if (params.sort) vars["sort"] = params.sort;
+    const data = await gql(
+      `query($query: String, $sort: SortEnum) {
+        tasks(query: $query, sort: $sort, first: 100) {
+          nodes { id name status emoji totalTimeSpent project { name } assignee { name } }
+        }
+      }`,
+      vars
+    );
+    const tasks = data.tasks.nodes;
+    if (tasks.length === 0) return textResult("No tasks found.");
+    const lines = tasks.map((t) => {
+      const proj = t.project ? ` (${t.project.name})` : "";
+      const emoji = t.emoji ? `${t.emoji} ` : "";
+      return `- ${emoji}**${t.name}**${proj}: ${formatDuration(t.totalTimeSpent)} [${t.status}] (id: ${t.id})`;
+    });
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "create-task",
+  "Create a new task.",
+  {
+    name: z.string().describe("Task name"),
+    projectName: z.string().optional().describe("Project name to associate"),
+    assigneeEmail: z.string().optional().describe("Assignee email"),
+    color: z.string().optional().describe("Color hex code"),
+    emoji: z.string().optional().describe("Emoji"),
+    keywords: z.array(z.string()).optional().describe("Keywords"),
+    timeBudget: z.number().optional().describe("Time budget in seconds"),
+    timeBudgetInterval: z.string().optional().describe("Budget interval")
+  },
+  async (params) => {
+    const args = { name: params.name };
+    if (params.projectName) args["projectName"] = params.projectName;
+    if (params.assigneeEmail) args["assigneeEmail"] = params.assigneeEmail;
+    if (params.color) args["color"] = params.color;
+    if (params.emoji) args["emoji"] = params.emoji;
+    if (params.keywords) args["keywords"] = params.keywords;
+    if (params.timeBudget) args["timeBudget"] = params.timeBudget;
+    if (params.timeBudgetInterval) args["timeBudgetInterval"] = params.timeBudgetInterval;
+    const data = await gql(
+      `mutation($input: CreateTaskInput!) { createTask(input: $input) { task { id name } errors } }`,
+      { input: { args } }
+    );
+    return textResult(`Task created: **${data.createTask.task.name}** (id: ${data.createTask.task.id})`);
+  }
+);
+server.tool(
+  "update-task",
+  "Update an existing task.",
+  {
+    id: z.string().describe("Task ID"),
+    name: z.string().optional().describe("New name"),
+    status: z.string().optional().describe("New status"),
+    color: z.string().optional().describe("Color hex code"),
+    emoji: z.string().optional().describe("Emoji"),
+    keywords: z.array(z.string()).optional().describe("Keywords"),
+    projectName: z.string().optional().describe("Project name"),
+    assigneeEmail: z.string().optional().describe("Assignee email")
+  },
+  async (params) => {
+    const args = { id: params.id };
+    if (params.name) args["name"] = params.name;
+    if (params.status) args["status"] = params.status;
+    if (params.color) args["color"] = params.color;
+    if (params.emoji) args["emoji"] = params.emoji;
+    if (params.keywords) args["keywords"] = params.keywords;
+    if (params.projectName) args["projectName"] = params.projectName;
+    if (params.assigneeEmail) args["assigneeEmail"] = params.assigneeEmail;
+    const data = await gql(
+      `mutation($input: UpdateTaskInput!) { updateTask(input: $input) { task { id name } errors } }`,
+      { input: { args } }
+    );
+    return textResult(`Task updated: **${data.updateTask.task.name}** (id: ${data.updateTask.task.id})`);
+  }
+);
+server.tool(
+  "delete-task",
+  "Delete a task by ID.",
+  { id: z.string().describe("Task ID") },
+  async ({ id }) => {
+    await gql(
+      `mutation($input: DeleteTaskInput!) { deleteTask(input: $input) { task { id } errors } }`,
+      { input: { id } }
+    );
+    return textResult(`Task ${id} deleted.`);
+  }
+);
+server.tool(
+  "list-clients",
+  "List all clients.",
+  {
+    query: z.string().optional().describe("Search by name"),
+    sort: z.enum(["created_at", "updated_at", "last_used_at"]).optional().describe("Sort order")
+  },
+  async (params) => {
+    const vars = {};
+    if (params.query) vars["query"] = params.query;
+    if (params.sort) vars["sort"] = params.sort;
+    const data = await gql(
+      `query($query: String, $sort: SortEnum) {
+        clients(query: $query, sort: $sort, first: 100) {
+          nodes { id name status emoji hourlyRate totalTimeSpent }
+        }
+      }`,
+      vars
+    );
+    const clients = data.clients.nodes;
+    if (clients.length === 0) return textResult("No clients found.");
+    const lines = clients.map((c) => {
+      const rate = c.hourlyRate ? ` @ ${c.hourlyRate}/h` : "";
+      const emoji = c.emoji ? `${c.emoji} ` : "";
+      return `- ${emoji}**${c.name}**: ${formatDuration(c.totalTimeSpent)}${rate} [${c.status}] (id: ${c.id})`;
+    });
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "create-client",
+  "Create a new client.",
+  {
+    name: z.string().describe("Client name"),
+    color: z.string().optional().describe("Color hex code"),
+    emoji: z.string().optional().describe("Emoji"),
+    hourlyRate: z.number().optional().describe("Hourly rate"),
+    keywords: z.array(z.string()).optional().describe("Keywords"),
+    timeBudget: z.number().optional().describe("Time budget in seconds"),
+    timeBudgetInterval: z.string().optional().describe("Budget interval")
+  },
+  async (params) => {
+    const args = { name: params.name };
+    if (params.color) args["color"] = params.color;
+    if (params.emoji) args["emoji"] = params.emoji;
+    if (params.hourlyRate !== void 0) args["hourlyRate"] = params.hourlyRate;
+    if (params.keywords) args["keywords"] = params.keywords;
+    if (params.timeBudget) args["timeBudget"] = params.timeBudget;
+    if (params.timeBudgetInterval) args["timeBudgetInterval"] = params.timeBudgetInterval;
+    const data = await gql(
+      `mutation($input: CreateClientInput!) { createClient(input: $input) { client { id name } errors } }`,
+      { input: { args } }
+    );
+    return textResult(`Client created: **${data.createClient.client.name}** (id: ${data.createClient.client.id})`);
+  }
+);
+server.tool(
+  "update-client",
+  "Update an existing client.",
+  {
+    id: z.string().describe("Client ID"),
+    name: z.string().optional().describe("New name"),
+    status: z.string().optional().describe("New status"),
+    color: z.string().optional().describe("Color hex code"),
+    emoji: z.string().optional().describe("Emoji"),
+    hourlyRate: z.number().optional().describe("Hourly rate"),
+    keywords: z.array(z.string()).optional().describe("Keywords")
+  },
+  async (params) => {
+    const args = { id: params.id };
+    if (params.name) args["name"] = params.name;
+    if (params.status) args["status"] = params.status;
+    if (params.color) args["color"] = params.color;
+    if (params.emoji) args["emoji"] = params.emoji;
+    if (params.hourlyRate !== void 0) args["hourlyRate"] = params.hourlyRate;
+    if (params.keywords) args["keywords"] = params.keywords;
+    const data = await gql(
+      `mutation($input: UpdateClientInput!) { updateClient(input: $input) { client { id name } errors } }`,
+      { input: { args } }
+    );
+    return textResult(`Client updated: **${data.updateClient.client.name}** (id: ${data.updateClient.client.id})`);
+  }
+);
+server.tool(
+  "delete-client",
+  "Delete a client by ID.",
+  { id: z.string().describe("Client ID") },
+  async ({ id }) => {
+    await gql(
+      `mutation($input: DeleteClientInput!) { deleteClient(input: $input) { client { id } errors } }`,
+      { input: { id } }
+    );
+    return textResult(`Client ${id} deleted.`);
+  }
+);
+server.tool(
+  "list-project-time-entries",
+  "List time entries for projects.",
+  {
+    startTime: z.string().optional().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().optional().describe("End datetime (ISO 8601)"),
+    sort: z.enum(["created_at", "updated_at", "start_time"]).default("start_time").describe("Sort")
+  },
+  async (params) => {
+    const data = await gql(
+      `query($start: ISO8601DateTime, $end: ISO8601DateTime, $sort: TimeEntrySortEnum) {
+        projectTimeEntries(startTime: $start, endTime: $end, sort: $sort) {
+          id description duration startTime endTime source project { name }
+        }
+      }`,
+      { start: params.startTime, end: params.endTime, sort: params.sort }
+    );
+    const entries = data.projectTimeEntries;
+    if (entries.length === 0) return textResult("No project time entries found.");
+    const lines = entries.map((e) => {
+      const desc = e.description ? ` \u2014 ${e.description}` : "";
+      return `- **${e.project.name}** ${e.startTime.slice(0, 10)}: ${formatDuration(e.duration)}${desc} (id: ${e.id})`;
+    });
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "create-project-time-entry",
+  "Create a time entry for a project.",
+  {
+    projectId: z.string().describe("Project ID"),
+    startTime: z.string().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().describe("End datetime (ISO 8601)"),
+    description: z.string().optional().describe("Description"),
+    billable: z.boolean().optional().describe("Billable")
+  },
+  async (params) => {
+    const input = {
+      projectId: params.projectId,
+      startTime: params.startTime,
+      endTime: params.endTime
+    };
+    if (params.description) input["description"] = params.description;
+    if (params.billable !== void 0) input["billable"] = params.billable;
+    const data = await gql(
+      `mutation($input: CreateProjectTimeEntryInput!) {
+        createProjectTimeEntry(input: $input) { timeEntry { id duration project { name } } errors }
+      }`,
+      { input }
+    );
+    const e = data.createProjectTimeEntry.timeEntry;
+    return textResult(`Time entry created: **${e.project.name}** ${formatDuration(e.duration)} (id: ${e.id})`);
+  }
+);
+server.tool(
+  "delete-project-time-entry",
+  "Delete a project time entry.",
+  { id: z.string().describe("Time entry ID") },
+  async ({ id }) => {
+    await gql(
+      `mutation($input: DeleteProjectTimeEntryInput!) { deleteProjectTimeEntry(input: $input) { timeEntry { id } errors } }`,
+      { input: { id } }
+    );
+    return textResult(`Project time entry ${id} deleted.`);
+  }
+);
+server.tool(
+  "list-task-time-entries",
+  "List time entries for tasks.",
+  {
+    startTime: z.string().optional().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().optional().describe("End datetime (ISO 8601)"),
+    sort: z.enum(["created_at", "updated_at", "start_time"]).default("start_time").describe("Sort")
+  },
+  async (params) => {
+    const data = await gql(
+      `query($start: ISO8601DateTime, $end: ISO8601DateTime, $sort: TimeEntrySortEnum) {
+        taskTimeEntries(startTime: $start, endTime: $end, sort: $sort) {
+          id description duration startTime endTime task { name }
+        }
+      }`,
+      { start: params.startTime, end: params.endTime, sort: params.sort }
+    );
+    const entries = data.taskTimeEntries;
+    if (entries.length === 0) return textResult("No task time entries found.");
+    const lines = entries.map((e) => {
+      const desc = e.description ? ` \u2014 ${e.description}` : "";
+      return `- **${e.task.name}** ${e.startTime.slice(0, 10)}: ${formatDuration(e.duration)}${desc} (id: ${e.id})`;
+    });
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "create-task-time-entry",
+  "Create a time entry for a task.",
+  {
+    taskId: z.string().describe("Task ID"),
+    startTime: z.string().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().describe("End datetime (ISO 8601)"),
+    description: z.string().optional().describe("Description"),
+    billable: z.boolean().optional().describe("Billable")
+  },
+  async (params) => {
+    const input = {
+      taskId: params.taskId,
+      startTime: params.startTime,
+      endTime: params.endTime
+    };
+    if (params.description) input["description"] = params.description;
+    if (params.billable !== void 0) input["billable"] = params.billable;
+    const data = await gql(
+      `mutation($input: CreateTaskTimeEntryInput!) {
+        createTaskTimeEntry(input: $input) { timeEntry { id duration task { name } } errors }
+      }`,
+      { input }
+    );
+    const e = data.createTaskTimeEntry.timeEntry;
+    return textResult(`Time entry created: **${e.task.name}** ${formatDuration(e.duration)} (id: ${e.id})`);
+  }
+);
+server.tool(
+  "delete-task-time-entry",
+  "Delete a task time entry.",
+  { id: z.string().describe("Time entry ID") },
+  async ({ id }) => {
+    await gql(
+      `mutation($input: DeleteTaskTimeEntryInput!) { deleteTaskTimeEntry(input: $input) { timeEntry { id } errors } }`,
+      { input: { id } }
+    );
+    return textResult(`Task time entry ${id} deleted.`);
+  }
+);
+server.tool(
+  "list-client-time-entries",
+  "List time entries for clients.",
+  {
+    startTime: z.string().optional().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().optional().describe("End datetime (ISO 8601)"),
+    sort: z.enum(["created_at", "updated_at", "start_time"]).default("start_time").describe("Sort")
+  },
+  async (params) => {
+    const data = await gql(
+      `query($start: ISO8601DateTime, $end: ISO8601DateTime, $sort: TimeEntrySortEnum) {
+        clientTimeEntries(startTime: $start, endTime: $end, sort: $sort) {
+          id description duration startTime endTime client { name }
+        }
+      }`,
+      { start: params.startTime, end: params.endTime, sort: params.sort }
+    );
+    const entries = data.clientTimeEntries;
+    if (entries.length === 0) return textResult("No client time entries found.");
+    const lines = entries.map((e) => {
+      const desc = e.description ? ` \u2014 ${e.description}` : "";
+      return `- **${e.client.name}** ${e.startTime.slice(0, 10)}: ${formatDuration(e.duration)}${desc} (id: ${e.id})`;
+    });
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "create-client-time-entry",
+  "Create a time entry for a client.",
+  {
+    clientId: z.string().describe("Client ID"),
+    startTime: z.string().describe("Start datetime (ISO 8601)"),
+    endTime: z.string().describe("End datetime (ISO 8601)"),
+    description: z.string().optional().describe("Description"),
+    billable: z.boolean().optional().describe("Billable")
+  },
+  async (params) => {
+    const input = {
+      clientId: params.clientId,
+      startTime: params.startTime,
+      endTime: params.endTime
+    };
+    if (params.description) input["description"] = params.description;
+    if (params.billable !== void 0) input["billable"] = params.billable;
+    const data = await gql(
+      `mutation($input: CreateClientTimeEntryInput!) {
+        createClientTimeEntry(input: $input) { timeEntry { id duration client { name } } errors }
+      }`,
+      { input }
+    );
+    const e = data.createClientTimeEntry.timeEntry;
+    return textResult(`Time entry created: **${e.client.name}** ${formatDuration(e.duration)} (id: ${e.id})`);
+  }
+);
+server.tool(
+  "delete-client-time-entry",
+  "Delete a client time entry.",
+  { id: z.string().describe("Time entry ID") },
+  async ({ id }) => {
+    await gql(
+      `mutation($input: DeleteClientTimeEntryInput!) { deleteClientTimeEntry(input: $input) { timeEntry { id } errors } }`,
+      { input: { id } }
+    );
+    return textResult(`Client time entry ${id} deleted.`);
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mnicole-dev/rize-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for the Rize time tracking GraphQL API",
+  "type": "module",
+  "bin": {
+    "rize-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --out-dir dist --clean",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "rize",
+    "time-tracking",
+    "focus",
+    "productivity",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}