busy-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# Busy MCP Server
+
+An MCP (Model Context Protocol) server for [Busy](https://busy.no) time tracking. Log hours with natural language through Claude.
+
+## Installation
+
+### Via npx (recommended)
+
+```bash
+npx busy-mcp-server
+```
+
+### Via npm
+
+```bash
+npm install -g busy-mcp-server
+```
+
+## Setup
+
+### 1. Get your Busy API token
+
+1. Log in to [Busy](https://app.busy.no)
+2. Go to profile settings → API
+3. Generate an API token
+
+### 2. Configure Claude Code
+
+Add to your Claude Code MCP settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "busy": {
+      "command": "npx",
+      "args": ["busy-mcp-server"],
+      "env": {
+        "BUSY_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### 3. First-time setup
+
+When you first use the server, Claude will guide you through setup:
+
+1. **User ID** - Found via email lookup or in your Busy URL: `app.busy.no/timeline/{org}/users/{YOUR_ID}`
+2. **Projects** - Select which projects you work on
+3. **Aliases** - Add shortcuts like "novem" for "Cube - Novem - Retainer"
+
+Configuration is saved to `~/.config/busy-mcp/config.json`.
+
+## Usage
+
+Once configured, you can:
+
+- **Log time:** "Log 2 hours to novem for code review"
+- **Check entries:** "What did I log today?"
+- **Update entries:** "Change that last entry to 3 hours"
+- **Delete entries:** "Delete entry 12345"
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_time_entry` | Log hours to a project |
+| `get_entries` | View time entries for a date range |
+| `list_projects` | Show configured projects and tags |
+| `update_entry` | Modify an existing entry |
+| `delete_entry` | Remove an entry |
+| `reconfigure` | Reset and run setup again |
+
+## Limitations
+
+- **Recurring entries** cannot be modified via the API. Edit them in the Busy web app.
+
+## License
+
+MIT

package/dist/busy-api.d.ts

@@ -0,0 +1,47 @@
+export interface HourEntry {
+    id: string;
+    userId: string;
+    projectId: string;
+    tagId: string;
+    billableMinutes: number;
+    totalMinutes: number;
+    description: string;
+    startTime: string;
+    stopTime: string;
+}
+export interface User {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+}
+export interface Project {
+    id: string;
+    name: string;
+}
+export interface Tag {
+    id: string;
+    name: string;
+}
+export interface CreateEntryParams {
+    projectId: number;
+    totalMinutes: number;
+    tagId: number;
+    description?: string;
+    date?: string;
+}
+export interface UpdateEntryParams {
+    projectId?: number;
+    totalMinutes?: number;
+    tagId?: number;
+    description?: string;
+}
+export declare function getUsers(): Promise<User[]>;
+export declare function getProjects(): Promise<Project[]>;
+export declare function getTags(): Promise<Tag[]>;
+export declare function createHourEntry(params: CreateEntryParams & {
+    userId: string;
+}): Promise<HourEntry>;
+export declare function getHourEntries(dateFrom?: string, dateTo?: string, userId?: string): Promise<HourEntry[]>;
+export declare function updateHourEntry(entryId: string, params: UpdateEntryParams): Promise<HourEntry>;
+export declare function deleteHourEntry(entryId: string): Promise<void>;

package/dist/busy-api.js

@@ -0,0 +1,114 @@
+import { BUSY_API_BASE_URL } from "./config.js";
+function getToken() {
+    const token = process.env.BUSY_API_TOKEN;
+    if (!token) {
+        throw new Error("BUSY_API_TOKEN environment variable is not set. " +
+            "Please set it in your shell profile or Claude Code MCP config.");
+    }
+    return token;
+}
+async function request(endpoint, options = {}) {
+    const token = getToken();
+    const response = await fetch(`${BUSY_API_BASE_URL}${endpoint}`, {
+        ...options,
+        headers: {
+            "Authorization": `Bearer ${token}`,
+            "Content-Type": "application/json",
+            ...options.headers,
+        },
+    });
+    if (!response.ok) {
+        const errorBody = await response.text();
+        throw new Error(`Busy API error (${response.status}): ${errorBody}`);
+    }
+    return response.json();
+}
+export async function getUsers() {
+    const response = await request("/users");
+    return response.data;
+}
+export async function getProjects() {
+    const response = await request("/projects");
+    return response.data;
+}
+export async function getTags() {
+    const response = await request("/tags");
+    return response.data;
+}
+export async function createHourEntry(params) {
+    const date = params.date || new Date().toISOString().split("T")[0];
+    // Create start and stop times for the given date
+    // Default: 8am to 8am + hours
+    const hours = params.totalMinutes / 60;
+    const startHour = 8;
+    const endHour = startHour + hours;
+    const startTime = `${date}T${String(startHour).padStart(2, "0")}:00:00.000Z`;
+    const stopTime = `${date}T${String(Math.floor(endHour)).padStart(2, "0")}:${String(Math.round((endHour % 1) * 60)).padStart(2, "0")}:00.000Z`;
+    const body = {
+        userId: params.userId,
+        projectId: String(params.projectId),
+        startTime,
+        stopTime,
+        totalMinutes: params.totalMinutes,
+        billableMinutes: params.totalMinutes,
+        tagId: String(params.tagId),
+        description: params.description || "",
+        externalId: null,
+    };
+    const response = await request("/hourEntries", {
+        method: "POST",
+        body: JSON.stringify(body),
+    });
+    return response.data;
+}
+export async function getHourEntries(dateFrom, dateTo, userId) {
+    if (!userId) {
+        throw new Error("userId is required");
+    }
+    const today = new Date().toISOString().split("T")[0];
+    const from = dateFrom || today;
+    const to = dateTo || today;
+    const params = new URLSearchParams({
+        startTimeFrom: from,
+        startTimeTo: to,
+        userIdIn: userId,
+        limit: "100",
+    });
+    const response = await request(`/hourEntries/?${params.toString()}`);
+    return response.data;
+}
+export async function updateHourEntry(entryId, params) {
+    const body = {};
+    if (params.projectId !== undefined) {
+        body.projectId = String(params.projectId);
+    }
+    if (params.totalMinutes !== undefined) {
+        body.totalMinutes = params.totalMinutes;
+        body.billableMinutes = params.totalMinutes;
+        // Recalculate stop time if we have new minutes
+        // This is a simplification - in reality we'd want to fetch the entry first
+        const hours = params.totalMinutes / 60;
+        const startHour = 8;
+        const endHour = startHour + hours;
+        const today = new Date().toISOString().split("T")[0];
+        body.startTime = `${today}T${String(startHour).padStart(2, "0")}:00:00.000Z`;
+        body.stopTime = `${today}T${String(Math.floor(endHour)).padStart(2, "0")}:${String(Math.round((endHour % 1) * 60)).padStart(2, "0")}:00.000Z`;
+    }
+    if (params.tagId !== undefined) {
+        body.tagId = String(params.tagId);
+    }
+    if (params.description !== undefined) {
+        body.description = params.description;
+    }
+    const response = await request(`/hourEntries/${entryId}`, {
+        method: "PATCH",
+        body: JSON.stringify(body),
+    });
+    return response.data;
+}
+export async function deleteHourEntry(entryId) {
+    await request(`/hourEntries/${entryId}`, {
+        method: "PATCH",
+        body: JSON.stringify({ isActive: false }),
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+import { type ProjectConfig } from "./setup/config-store.js";
+export declare const BUSY_API_BASE_URL = "https://api.busy.no/v2";
+export declare const USER_ID = 169169;
+export interface Project {
+    id: number;
+    name: string;
+    aliases: string[];
+}
+export interface Tag {
+    id: number;
+    name: string;
+}
+export declare function getConfiguredProjects(): ProjectConfig[];
+export declare function getUserId(): string | null;
+export declare function getDefaultTagId(): string | null;
+export declare function findProject(query: string): ProjectConfig | undefined;
+export declare function getProjectList(): string;

package/dist/config.js

@@ -0,0 +1,44 @@
+import { loadConfig } from "./setup/config-store.js";
+export const BUSY_API_BASE_URL = "https://api.busy.no/v2";
+// Legacy USER_ID for backwards compatibility during migration
+export const USER_ID = 169169;
+// These are now loaded from config, with fallback to empty
+export function getConfiguredProjects() {
+    const config = loadConfig();
+    return config?.projects || [];
+}
+export function getUserId() {
+    const config = loadConfig();
+    return config?.userId || null;
+}
+export function getDefaultTagId() {
+    const config = loadConfig();
+    return config?.defaultTagId || null;
+}
+export function findProject(query) {
+    const projects = getConfiguredProjects();
+    const q = query.toLowerCase().trim();
+    // Exact match on name
+    const exactMatch = projects.find((p) => p.name.toLowerCase() === q);
+    if (exactMatch)
+        return exactMatch;
+    // Match on alias
+    const aliasMatch = projects.find((p) => p.aliases.some((a) => a.toLowerCase() === q));
+    if (aliasMatch)
+        return aliasMatch;
+    // Partial match on name or alias
+    const partialMatch = projects.find((p) => p.name.toLowerCase().includes(q) ||
+        p.aliases.some((a) => a.toLowerCase().includes(q)));
+    if (partialMatch)
+        return partialMatch;
+    return undefined;
+}
+export function getProjectList() {
+    const projects = getConfiguredProjects();
+    if (projects.length === 0) {
+        return "No projects configured. Run setup first.";
+    }
+    return projects
+        .map((p) => `- ${p.name} (aliases: ${p.aliases.join(", ") || "none"})`)
+        .join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { configExists, setupStart, setupStartSchema, setupFindUser, setupFindUserSchema, setupSetUserId, setupSetUserIdSchema, setupListAvailableProjects, setupListProjectsSchema, setupSelectProjects, setupSelectProjectsSchema, setupComplete, setupCompleteSchema, } from "./setup/index.js";
+import { createEntry, createEntrySchema } from "./tools/create-entry.js";
+import { listProjects } from "./tools/list-projects.js";
+import { getEntries, getEntriesSchema } from "./tools/get-entries.js";
+import { updateEntry, updateEntrySchema } from "./tools/update-entry.js";
+import { deleteEntry, deleteEntrySchema } from "./tools/delete-entry.js";
+import { reconfigure, reconfigureSchema } from "./tools/reconfigure.js";
+const server = new McpServer({
+    name: "busy-time-tracker",
+    version: "1.0.0",
+});
+function registerSetupTools() {
+    server.tool("setup_start", "Start the Busy MCP setup process. Checks for API token and provides instructions.", setupStartSchema.shape, async () => {
+        const result = await setupStart();
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("setup_find_user_by_email", "Look up your Busy user ID by email address", setupFindUserSchema.shape, async (args) => {
+        const input = setupFindUserSchema.parse(args);
+        const result = await setupFindUser(input);
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("setup_set_user_id", "Set your Busy user ID (from email lookup or timeline URL)", setupSetUserIdSchema.shape, async (args) => {
+        const input = setupSetUserIdSchema.parse(args);
+        const result = await setupSetUserId(input);
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("setup_list_available_projects", "List all projects available in your Busy account", setupListProjectsSchema.shape, async () => {
+        const result = await setupListAvailableProjects();
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("setup_select_projects", "Select which projects you want to use and optionally add aliases", setupSelectProjectsSchema.shape, async (args) => {
+        const input = setupSelectProjectsSchema.parse(args);
+        const result = await setupSelectProjects(input);
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("setup_complete", "Complete the setup process and save configuration", setupCompleteSchema.shape, async (args) => {
+        const input = setupCompleteSchema.parse(args);
+        const result = await setupComplete(input);
+        return { content: [{ type: "text", text: result }] };
+    });
+}
+function registerNormalTools() {
+    server.tool("create_time_entry", "Log hours to a project in Busy. Accepts fuzzy project names like 'novem' or 'internal'.", createEntrySchema.shape, async (args) => {
+        const input = createEntrySchema.parse(args);
+        const result = await createEntry(input);
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("list_projects", "List all available projects and tags in Busy", {}, async () => {
+        const result = await listProjects();
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("get_entries", "Get time entries for a date range. Defaults to today if no dates specified.", getEntriesSchema.shape, async (args) => {
+        const input = getEntriesSchema.parse(args);
+        const result = await getEntries(input);
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("update_entry", "Update an existing time entry. Can change hours, description, project, or tag.", updateEntrySchema.shape, async (args) => {
+        const input = updateEntrySchema.parse(args);
+        const result = await updateEntry(input);
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("delete_entry", "Delete a time entry by its ID", deleteEntrySchema.shape, async (args) => {
+        const input = deleteEntrySchema.parse(args);
+        const result = await deleteEntry(input);
+        return { content: [{ type: "text", text: result }] };
+    });
+    server.tool("reconfigure", "Reset configuration and run setup again", reconfigureSchema.shape, async (args) => {
+        const input = reconfigureSchema.parse(args);
+        const result = await reconfigure(input);
+        return { content: [{ type: "text", text: result }] };
+    });
+}
+async function main() {
+    const isConfigured = configExists();
+    if (isConfigured) {
+        // Normal operation: register all normal tools + reconfigure
+        registerNormalTools();
+        console.error("Busy MCP server running (configured)");
+    }
+    else {
+        // Setup mode: register setup tools + limited normal tools for seamless transition
+        registerSetupTools();
+        registerNormalTools(); // Also register normal tools so they work after setup completes
+        console.error("Busy MCP server running (setup mode - no config found)");
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/setup/config-store.d.ts

@@ -0,0 +1,15 @@
+export interface ProjectConfig {
+    id: string;
+    name: string;
+    aliases: string[];
+}
+export interface Config {
+    userId: string;
+    projects: ProjectConfig[];
+    defaultTagId: string;
+}
+export declare function getConfigPath(): string;
+export declare function configExists(): boolean;
+export declare function loadConfig(): Config | null;
+export declare function saveConfig(config: Config): void;
+export declare function deleteConfig(): void;

package/dist/setup/config-store.js

@@ -0,0 +1,35 @@
+import envPaths from "env-paths";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from "fs";
+import { join } from "path";
+const paths = envPaths("busy-mcp", { suffix: "" });
+export function getConfigPath() {
+    return join(paths.config, "config.json");
+}
+export function configExists() {
+    return existsSync(getConfigPath());
+}
+export function loadConfig() {
+    if (!configExists()) {
+        return null;
+    }
+    try {
+        const content = readFileSync(getConfigPath(), "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(config) {
+    const configDir = paths.config;
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
+    writeFileSync(getConfigPath(), JSON.stringify(config, null, 2));
+}
+export function deleteConfig() {
+    const configPath = getConfigPath();
+    if (existsSync(configPath)) {
+        unlinkSync(configPath);
+    }
+}

package/dist/setup/index.d.ts

@@ -0,0 +1,8 @@
+export { setupStart, setupStartSchema } from "./tools/start.js";
+export { setupFindUser, setupFindUserSchema } from "./tools/find-user.js";
+export { setupSetUserId, setupSetUserIdSchema } from "./tools/set-user-id.js";
+export { setupListAvailableProjects, setupListProjectsSchema } from "./tools/list-available-projects.js";
+export { setupSelectProjects, setupSelectProjectsSchema } from "./tools/select-projects.js";
+export { setupComplete, setupCompleteSchema } from "./tools/complete.js";
+export { loadConfig, configExists, saveConfig, deleteConfig, getConfigPath } from "./config-store.js";
+export type { Config, ProjectConfig } from "./config-store.js";

package/dist/setup/index.js

@@ -0,0 +1,7 @@
+export { setupStart, setupStartSchema } from "./tools/start.js";
+export { setupFindUser, setupFindUserSchema } from "./tools/find-user.js";
+export { setupSetUserId, setupSetUserIdSchema } from "./tools/set-user-id.js";
+export { setupListAvailableProjects, setupListProjectsSchema } from "./tools/list-available-projects.js";
+export { setupSelectProjects, setupSelectProjectsSchema } from "./tools/select-projects.js";
+export { setupComplete, setupCompleteSchema } from "./tools/complete.js";
+export { loadConfig, configExists, saveConfig, deleteConfig, getConfigPath } from "./config-store.js";

package/dist/setup/tools/complete.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const setupCompleteSchema: z.ZodObject<{
+    default_tag: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    default_tag?: string | undefined;
+}, {
+    default_tag?: string | undefined;
+}>;
+export type SetupCompleteInput = z.infer<typeof setupCompleteSchema>;
+export declare function setupComplete(input: SetupCompleteInput): Promise<string>;

package/dist/setup/tools/complete.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { loadConfig, saveConfig, getConfigPath } from "../config-store.js";
+import { getTags } from "../../busy-api.js";
+export const setupCompleteSchema = z.object({
+    default_tag: z.string().optional().describe("Default tag name (e.g., 'Working hours'). If not specified, uses first available tag."),
+});
+export async function setupComplete(input) {
+    const config = loadConfig();
+    if (!config || !config.userId) {
+        return "Setup incomplete: User ID not set. Use setup_set_user_id first.";
+    }
+    if (config.projects.length === 0) {
+        return "Setup incomplete: No projects selected. Use setup_select_projects to add at least one project.";
+    }
+    try {
+        const tags = await getTags();
+        if (tags.length === 0) {
+            return "Warning: No tags found in your Busy account. Using empty default.";
+        }
+        let defaultTag = tags[0];
+        if (input.default_tag) {
+            const matchedTag = tags.find((t) => t.name.toLowerCase() === input.default_tag.toLowerCase());
+            if (matchedTag) {
+                defaultTag = matchedTag;
+            }
+        }
+        else {
+            // Try to find "Working hours" as default
+            const workingHours = tags.find((t) => t.name.toLowerCase() === "working hours");
+            if (workingHours) {
+                defaultTag = workingHours;
+            }
+        }
+        config.defaultTagId = defaultTag.id;
+        saveConfig(config);
+        const projectList = config.projects
+            .map((p) => {
+            const aliasText = p.aliases.length > 0 ? ` (${p.aliases.join(", ")})` : "";
+            return `- ${p.name}${aliasText}`;
+        })
+            .join("\n");
+        return `## Setup Complete!
+
+**Configuration saved to:** \`${getConfigPath()}\`
+
+**User ID:** ${config.userId}
+
+**Projects:**
+${projectList}
+
+**Default tag:** ${defaultTag.name}
+
+---
+
+You can now use the Busy time tracking tools:
+- \`create_time_entry\` - Log hours
+- \`get_entries\` - View your time entries
+- \`list_projects\` - See your configured projects
+- \`update_entry\` - Modify entries
+- \`delete_entry\` - Remove entries
+
+To reconfigure later, use the \`reconfigure\` tool.
+
+**Note:** Recurring time entries cannot be modified via this integration. Use the Busy web app for those.`;
+    }
+    catch (error) {
+        return `Error completing setup: ${error instanceof Error ? error.message : "Unknown error"}`;
+    }
+}

package/dist/setup/tools/find-user.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const setupFindUserSchema: z.ZodObject<{
+    email: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+}, {
+    email: string;
+}>;
+export type SetupFindUserInput = z.infer<typeof setupFindUserSchema>;
+export declare function setupFindUser(input: SetupFindUserInput): Promise<string>;

package/dist/setup/tools/find-user.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { getUsers } from "../../busy-api.js";
+export const setupFindUserSchema = z.object({
+    email: z.string().email().describe("Your email address used in Busy"),
+});
+export async function setupFindUser(input) {
+    try {
+        const users = await getUsers();
+        const user = users.find((u) => u.email.toLowerCase() === input.email.toLowerCase());
+        if (!user) {
+            const similarUsers = users.filter((u) => u.email.toLowerCase().includes(input.email.split("@")[0].toLowerCase()));
+            if (similarUsers.length > 0) {
+                const suggestions = similarUsers
+                    .slice(0, 5)
+                    .map((u) => `- ${u.firstName} ${u.lastName} (${u.email}) - ID: ${u.id}`)
+                    .join("\n");
+                return `No exact match for "${input.email}". Similar users found:\n\n${suggestions}\n\nUse setup_set_user_id with the correct ID.`;
+            }
+            return `No user found with email "${input.email}". Please check the email or use setup_set_user_id to enter your ID manually from your Busy timeline URL.`;
+        }
+        return `Found user: **${user.firstName} ${user.lastName}** (${user.email})\n\nUser ID: **${user.id}**\n\nIs this correct? If yes, use setup_set_user_id with ID "${user.id}".`;
+    }
+    catch (error) {
+        return `Error looking up user: ${error instanceof Error ? error.message : "Unknown error"}. Please use setup_set_user_id to enter your ID manually.`;
+    }
+}

package/dist/setup/tools/list-available-projects.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export declare const setupListProjectsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export type SetupListProjectsInput = z.infer<typeof setupListProjectsSchema>;
+export declare function setupListAvailableProjects(): Promise<string>;

package/dist/setup/tools/list-available-projects.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { getProjects } from "../../busy-api.js";
+export const setupListProjectsSchema = z.object({});
+export async function setupListAvailableProjects() {
+    try {
+        const projects = await getProjects();
+        if (projects.length === 0) {
+            return "No projects found. Please check your API token has access to projects.";
+        }
+        const projectList = projects
+            .map((p) => `- **${p.name}** (ID: ${p.id})`)
+            .join("\n");
+        return `## Available Projects
+
+${projectList}
+
+---
+
+Use setup_select_projects to choose which projects you want to use. You can also add aliases for quick access (e.g., "novem" for "Cube - Novem - Retainer").
+
+Example: setup_select_projects with projects like:
+\`[{"id": "123", "aliases": ["shortname"]}]\``;
+    }
+    catch (error) {
+        return `Error fetching projects: ${error instanceof Error ? error.message : "Unknown error"}`;
+    }
+}

package/dist/setup/tools/select-projects.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const setupSelectProjectsSchema: z.ZodObject<{
+    projects: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        aliases?: string[] | undefined;
+    }, {
+        id: string;
+        aliases?: string[] | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    projects: {
+        id: string;
+        aliases?: string[] | undefined;
+    }[];
+}, {
+    projects: {
+        id: string;
+        aliases?: string[] | undefined;
+    }[];
+}>;
+export type SetupSelectProjectsInput = z.infer<typeof setupSelectProjectsSchema>;
+export declare function setupSelectProjects(input: SetupSelectProjectsInput): Promise<string>;

package/dist/setup/tools/select-projects.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { loadConfig, saveConfig } from "../config-store.js";
+import { getProjects } from "../../busy-api.js";
+const projectSelectionSchema = z.object({
+    id: z.string().describe("Project ID"),
+    aliases: z.array(z.string()).optional().describe("Short names for quick access"),
+});
+export const setupSelectProjectsSchema = z.object({
+    projects: z
+        .array(projectSelectionSchema)
+        .describe("Array of projects to add with optional aliases"),
+});
+export async function setupSelectProjects(input) {
+    const config = loadConfig();
+    if (!config || !config.userId) {
+        return "Please set your user ID first using setup_set_user_id.";
+    }
+    try {
+        const allProjects = await getProjects();
+        const selectedProjects = [];
+        for (const selection of input.projects) {
+            const project = allProjects.find((p) => p.id === selection.id);
+            if (!project) {
+                return `Project with ID "${selection.id}" not found. Use setup_list_available_projects to see valid IDs.`;
+            }
+            selectedProjects.push({
+                id: project.id,
+                name: project.name,
+                aliases: selection.aliases || [],
+            });
+        }
+        config.projects = [...config.projects, ...selectedProjects];
+        saveConfig(config);
+        const projectSummary = selectedProjects
+            .map((p) => {
+            const aliasText = p.aliases.length > 0 ? ` (aliases: ${p.aliases.join(", ")})` : "";
+            return `- ${p.name}${aliasText}`;
+        })
+            .join("\n");
+        return `Added ${selectedProjects.length} project(s):\n\n${projectSummary}\n\nTotal projects configured: ${config.projects.length}\n\nAdd more projects or use setup_complete to finish setup.`;
+    }
+    catch (error) {
+        return `Error selecting projects: ${error instanceof Error ? error.message : "Unknown error"}`;
+    }
+}

package/dist/setup/tools/set-user-id.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const setupSetUserIdSchema: z.ZodObject<{
+    user_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    user_id: string;
+}, {
+    user_id: string;
+}>;
+export type SetupSetUserIdInput = z.infer<typeof setupSetUserIdSchema>;
+export declare function setupSetUserId(input: SetupSetUserIdInput): Promise<string>;

package/dist/setup/tools/set-user-id.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { loadConfig, saveConfig } from "../config-store.js";
+export const setupSetUserIdSchema = z.object({
+    user_id: z.string().describe("Your Busy user ID (found in timeline URL or from email lookup)"),
+});
+export async function setupSetUserId(input) {
+    const existingConfig = loadConfig();
+    const config = {
+        userId: input.user_id,
+        projects: existingConfig?.projects || [],
+        defaultTagId: existingConfig?.defaultTagId || "",
+    };
+    saveConfig(config);
+    return `User ID set to: **${input.user_id}**
+
+Next step: Let's select your projects. Use setup_list_available_projects to see all available projects.`;
+}

package/dist/setup/tools/start.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export declare const setupStartSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export type SetupStartInput = z.infer<typeof setupStartSchema>;
+export declare function setupStart(): Promise<string>;

package/dist/setup/tools/start.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export const setupStartSchema = z.object({});
+export async function setupStart() {
+    const token = process.env.BUSY_API_TOKEN;
+    if (!token) {
+        return `## Busy MCP Setup
+
+Welcome! Let's set up your Busy time tracking integration.
+
+**Step 1: Get your API token**
+
+1. Log in to Busy at https://app.busy.no
+2. Go to your profile settings
+3. Find the API section and generate a token
+4. Set it as an environment variable: \`BUSY_API_TOKEN=your-token-here\`
+
+Once you have the token set, run this setup again.`;
+    }
+    return `## Busy MCP Setup
+
+API token found! Now we need your user ID.
+
+**Two options:**
+
+1. **Find by email** - Tell me your email and I'll look up your user ID
+2. **Enter manually** - Find your ID in the Busy URL: \`https://app.busy.no/timeline/{org}/users/{YOUR_ID}\`
+
+Which would you prefer?`;
+}

package/dist/tools/create-entry.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const createEntrySchema: z.ZodObject<{
+    project: z.ZodString;
+    hours: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    date: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    hours: number;
+    description?: string | undefined;
+    tag?: string | undefined;
+    date?: string | undefined;
+}, {
+    project: string;
+    hours: number;
+    description?: string | undefined;
+    tag?: string | undefined;
+    date?: string | undefined;
+}>;
+export type CreateEntryInput = z.infer<typeof createEntrySchema>;
+export declare function createEntry(input: CreateEntryInput): Promise<string>;

package/dist/tools/create-entry.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { createHourEntry, getTags } from "../busy-api.js";
+import { findProject, getProjectList, getUserId, getDefaultTagId } from "../config.js";
+export const createEntrySchema = z.object({
+    project: z.string().describe("Project name or alias (e.g., 'novem', 'internal', 'dnb')"),
+    hours: z.number().positive().describe("Number of hours to log"),
+    description: z.string().optional().describe("Description of the work done"),
+    tag: z.string().optional().describe("Tag name (e.g., 'Development', 'Design'). Defaults to configured default tag"),
+    date: z.string().optional().describe("Date in YYYY-MM-DD format. Defaults to today"),
+});
+export async function createEntry(input) {
+    const userId = getUserId();
+    if (!userId) {
+        return "Not configured. Please run setup first.";
+    }
+    const project = findProject(input.project);
+    if (!project) {
+        return `Could not find project matching "${input.project}". Available projects:\n${getProjectList()}`;
+    }
+    let tagId = getDefaultTagId();
+    if (input.tag) {
+        try {
+            const tags = await getTags();
+            const tag = tags.find((t) => t.name.toLowerCase().includes(input.tag.toLowerCase()));
+            if (tag) {
+                tagId = tag.id;
+            }
+            else {
+                return `Could not find tag matching "${input.tag}".`;
+            }
+        }
+        catch {
+            return `Error fetching tags. Using default tag.`;
+        }
+    }
+    if (!tagId) {
+        return "No default tag configured. Please run setup again.";
+    }
+    const entry = await createHourEntry({
+        projectId: Number(project.id),
+        totalMinutes: Math.round(input.hours * 60),
+        tagId: Number(tagId),
+        description: input.description,
+        date: input.date,
+        userId,
+    });
+    return `Created time entry:\n- Project: ${project.name}\n- Hours: ${input.hours}\n- Description: ${input.description || "(none)"}\n- Entry ID: ${entry.id}`;
+}

package/dist/tools/delete-entry.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const deleteEntrySchema: z.ZodObject<{
+    entry_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    entry_id: string;
+}, {
+    entry_id: string;
+}>;
+export type DeleteEntryInput = z.infer<typeof deleteEntrySchema>;
+export declare function deleteEntry(input: DeleteEntryInput): Promise<string>;

package/dist/tools/delete-entry.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { deleteHourEntry } from "../busy-api.js";
+export const deleteEntrySchema = z.object({
+    entry_id: z.string().describe("The ID of the entry to delete"),
+});
+export async function deleteEntry(input) {
+    try {
+        await deleteHourEntry(input.entry_id);
+        return `Deleted entry ${input.entry_id}`;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        if (message.includes("recurring")) {
+            return `Cannot delete entry ${input.entry_id}: This is a recurring entry and cannot be deleted via the API. Please remove it in the Busy web app at https://app.busy.no`;
+        }
+        return `Error deleting entry: ${message}`;
+    }
+}

package/dist/tools/get-entries.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export declare const getEntriesSchema: z.ZodObject<{
+    date_from: z.ZodOptional<z.ZodString>;
+    date_to: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+}, {
+    date_from?: string | undefined;
+    date_to?: string | undefined;
+}>;
+export type GetEntriesInput = z.infer<typeof getEntriesSchema>;
+export declare function getEntries(input: GetEntriesInput): Promise<string>;

package/dist/tools/get-entries.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { getHourEntries, getTags } from "../busy-api.js";
+import { getConfiguredProjects, getUserId } from "../config.js";
+export const getEntriesSchema = z.object({
+    date_from: z.string().optional().describe("Start date in YYYY-MM-DD format. Defaults to today"),
+    date_to: z.string().optional().describe("End date in YYYY-MM-DD format. Defaults to today"),
+});
+export async function getEntries(input) {
+    const userId = getUserId();
+    if (!userId) {
+        return "Not configured. Please run setup first.";
+    }
+    const entries = await getHourEntries(input.date_from, input.date_to, userId);
+    const projects = getConfiguredProjects();
+    let tags = [];
+    try {
+        tags = await getTags();
+    }
+    catch {
+        // Continue without tag names
+    }
+    if (entries.length === 0) {
+        const dateRange = input.date_from && input.date_to
+            ? `from ${input.date_from} to ${input.date_to}`
+            : "for today";
+        return `No time entries found ${dateRange}.`;
+    }
+    const formattedEntries = entries
+        .map((entry) => {
+        const project = projects.find((p) => p.id === entry.projectId);
+        const tag = tags.find((t) => t.id === entry.tagId);
+        const hours = entry.totalMinutes / 60;
+        const date = entry.startTime.split("T")[0];
+        return `- **${project?.name || `Project ${entry.projectId}`}** (${hours}h)\n  Date: ${date}\n  Tag: ${tag?.name || entry.tagId}\n  Description: ${entry.description || "(none)"}\n  ID: ${entry.id}`;
+    })
+        .join("\n\n");
+    const totalHours = entries.reduce((sum, e) => sum + e.totalMinutes, 0) / 60;
+    return `## Time Entries\n\n${formattedEntries}\n\n---\n**Total: ${totalHours} hours**`;
+}

package/dist/tools/list-projects.d.ts

@@ -0,0 +1 @@
+export declare function listProjects(): Promise<string>;

package/dist/tools/list-projects.js

@@ -0,0 +1,23 @@
+import { getConfiguredProjects } from "../config.js";
+import { getTags } from "../busy-api.js";
+export async function listProjects() {
+    const projects = getConfiguredProjects();
+    if (projects.length === 0) {
+        return "No projects configured. Please run setup first.";
+    }
+    const projectList = projects
+        .map((p) => {
+        const aliasText = p.aliases.length > 0 ? p.aliases.join(", ") : "none";
+        return `- **${p.name}** (ID: ${p.id})\n  Aliases: ${aliasText}`;
+    })
+        .join("\n");
+    let tagList = "Unable to fetch tags.";
+    try {
+        const tags = await getTags();
+        tagList = tags.map((t) => `- ${t.name} (ID: ${t.id})`).join("\n");
+    }
+    catch {
+        // Keep default message
+    }
+    return `## Your Projects\n\n${projectList}\n\n## Available Tags\n\n${tagList}\n\n---\n**Note:** Recurring time entries cannot be modified via this integration.`;
+}

package/dist/tools/reconfigure.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const reconfigureSchema: z.ZodObject<{
+    confirm: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    confirm: boolean;
+}, {
+    confirm: boolean;
+}>;
+export type ReconfigureInput = z.infer<typeof reconfigureSchema>;
+export declare function reconfigure(input: ReconfigureInput): Promise<string>;

package/dist/tools/reconfigure.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { deleteConfig, getConfigPath } from "../setup/config-store.js";
+export const reconfigureSchema = z.object({
+    confirm: z.boolean().describe("Set to true to confirm you want to reset configuration"),
+});
+export async function reconfigure(input) {
+    if (!input.confirm) {
+        return `This will delete your current configuration at \`${getConfigPath()}\` and restart setup.\n\nTo confirm, call reconfigure with confirm: true`;
+    }
+    deleteConfig();
+    return `Configuration deleted. The setup tools are now available again.\n\nUse setup_start to begin reconfiguration.`;
+}

package/dist/tools/update-entry.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const updateEntrySchema: z.ZodObject<{
+    entry_id: z.ZodString;
+    hours: z.ZodOptional<z.ZodNumber>;
+    description: z.ZodOptional<z.ZodString>;
+    project: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    entry_id: string;
+    description?: string | undefined;
+    project?: string | undefined;
+    hours?: number | undefined;
+    tag?: string | undefined;
+}, {
+    entry_id: string;
+    description?: string | undefined;
+    project?: string | undefined;
+    hours?: number | undefined;
+    tag?: string | undefined;
+}>;
+export type UpdateEntryInput = z.infer<typeof updateEntrySchema>;
+export declare function updateEntry(input: UpdateEntryInput): Promise<string>;

package/dist/tools/update-entry.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { updateHourEntry, getTags } from "../busy-api.js";
+import { findProject, getConfiguredProjects } from "../config.js";
+export const updateEntrySchema = z.object({
+    entry_id: z.string().describe("The ID of the entry to update"),
+    hours: z.number().positive().optional().describe("New number of hours"),
+    description: z.string().optional().describe("New description"),
+    project: z.string().optional().describe("New project name or alias"),
+    tag: z.string().optional().describe("New tag name"),
+});
+export async function updateEntry(input) {
+    const updates = {};
+    if (input.hours !== undefined) {
+        updates.totalMinutes = Math.round(input.hours * 60);
+    }
+    if (input.description !== undefined) {
+        updates.description = input.description;
+    }
+    if (input.project) {
+        const project = findProject(input.project);
+        if (!project) {
+            const projects = getConfiguredProjects();
+            const projectList = projects.map((p) => `- ${p.name}`).join("\n");
+            return `Could not find project matching "${input.project}". Available:\n${projectList}`;
+        }
+        updates.projectId = Number(project.id);
+    }
+    if (input.tag) {
+        try {
+            const tags = await getTags();
+            const tag = tags.find((t) => t.name.toLowerCase().includes(input.tag.toLowerCase()));
+            if (tag) {
+                updates.tagId = Number(tag.id);
+            }
+            else {
+                return `Could not find tag matching "${input.tag}".`;
+            }
+        }
+        catch {
+            return `Error fetching tags.`;
+        }
+    }
+    try {
+        const entry = await updateHourEntry(input.entry_id, updates);
+        return `Updated entry ${input.entry_id}:\n- totalMinutes: ${entry.totalMinutes}`;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        if (message.includes("recurring")) {
+            return `Cannot update entry ${input.entry_id}: This is a recurring entry and cannot be modified via the API. Please edit it in the Busy web app at https://app.busy.no`;
+        }
+        return `Error updating entry: ${message}`;
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "busy-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Busy time tracking - log hours with natural language via Claude",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "busy-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "busy",
+    "time-tracking",
+    "claude",
+    "anthropic",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "env-paths": "^3.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "mcpName": "busy-time-tracker"
+}