feat(mcp): cold-start hints + create_client/create_project tools

Mirror of the hosted MCP server (timebook backend): empty
list_clients/list_projects/list_entries return actionable setup hints,
not-found errors explain the setup path on fresh accounts, and the new
create_client/create_project tools let agents do first-run setup
in-conversation. 16 new tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ktamas77

src/lib/api.ts

@@ -130,6 +130,10 @@ export interface TimeEntry {
 export const api = {
   me: () => request<{ user: User }>('/api/auth/me'),
   listClients: () => request<{ clients: Client[] }>('/api/clients'),
+  createClient: (input: { name: string; email?: string }) =>
+    request<{ client: Client }>('/api/clients', { method: 'POST', body: input }),
+  createProject: (input: { name: string; clientId: string; description?: string }) =>
+    request<{ project: Project }>('/api/projects', { method: 'POST', body: input }),
   listProjects: () => request<{ projects: Project[] }>('/api/projects'),
   listRates: () => request<{ rates: Rate[] }>('/api/rates'),
   activeTimer: () => request<{ entry: TimeEntry | null }>('/api/time-entries/active'),

src/mcp/server.test.ts

@@ -0,0 +1,149 @@
+// Cold-start hints + create tools — mirror of the hosted MCP server's
+// behavior (timebook repo backend/src/mcp/tools-coldstart.test.ts).
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../lib/api.js', () => ({
+  api: {
+    me: vi.fn(),
+    listProjects: vi.fn(),
+    listClients: vi.fn(),
+    listEntries: vi.fn(),
+    listRates: vi.fn(),
+    createClient: vi.fn(),
+    createProject: vi.fn(),
+    activeTimer: vi.fn(),
+    startTimer: vi.fn(),
+    stopTimer: vi.fn(),
+    logTime: vi.fn(),
+  },
+  ApiError: class ApiError extends Error {
+    constructor(
+      public status: number,
+      message: string,
+    ) {
+      super(message);
+    }
+  },
+}));
+vi.mock('../lib/config.js', () => ({
+  readConfig: vi.fn(async () => ({ token: 'tbk_test' })),
+}));
+
+import { handleTool, COLD_START_HINTS } from './server.js';
+import { api } from '../lib/api.js';
+
+const mocked = api as unknown as Record<string, ReturnType<typeof vi.fn>>;
+
+const textOf = (result: any): string =>
+  (result.content ?? []).map((c: any) => c.text ?? '').join('\n');
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('cold-start hints', () => {
+  it('list_clients empty → create_client hint', async () => {
+    mocked.listClients.mockResolvedValue({ clients: [] });
+    const res = await handleTool('list_clients', {});
+    expect(res.isError).not.toBe(true);
+    expect(textOf(res)).toContain(COLD_START_HINTS.noClients);
+  });
+
+  it('list_clients with data → no hint', async () => {
+    mocked.listClients.mockResolvedValue({ clients: [{ id: 'c1', name: 'Acme' }] });
+    const res = await handleTool('list_clients', {});
+    expect(textOf(res)).not.toContain('create_client (just a name');
+  });
+
+  it('list_projects empty + no clients → client-first hint', async () => {
+    mocked.listProjects.mockResolvedValue({ projects: [] });
+    mocked.listClients.mockResolvedValue({ clients: [] });
+    const res = await handleTool('list_projects', {});
+    expect(textOf(res)).toContain(COLD_START_HINTS.noClients);
+  });
+
+  it('list_projects empty + clients exist → project hint', async () => {
+    mocked.listProjects.mockResolvedValue({ projects: [] });
+    mocked.listClients.mockResolvedValue({ clients: [{ id: 'c1', name: 'Acme' }] });
+    const res = await handleTool('list_projects', {});
+    expect(textOf(res)).toContain(COLD_START_HINTS.noProjects);
+  });
+
+  it('list_entries empty on a set-up account → entries hint', async () => {
+    mocked.listEntries.mockResolvedValue({ entries: [] });
+    mocked.listClients.mockResolvedValue({ clients: [{ id: 'c1' }] });
+    mocked.listProjects.mockResolvedValue({ projects: [{ id: 'p1', name: 'X' }] });
+    const res = await handleTool('list_entries', {});
+    expect(textOf(res)).toContain(COLD_START_HINTS.noEntries);
+  });
+
+  it('list_entries empty on an EMPTY account → client-first hint', async () => {
+    mocked.listEntries.mockResolvedValue({ entries: [] });
+    mocked.listClients.mockResolvedValue({ clients: [] });
+    mocked.listProjects.mockResolvedValue({ projects: [] });
+    const res = await handleTool('list_entries', {});
+    expect(textOf(res)).toContain(COLD_START_HINTS.noClients);
+  });
+
+  it('start_timer project-not-found on empty account → setup guidance', async () => {
+    mocked.listProjects.mockResolvedValue({ projects: [] });
+    mocked.listClients.mockResolvedValue({ clients: [] });
+    const res = await handleTool('start_timer', { project: 'Website' });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toContain('Project not found: Website');
+    expect(textOf(res)).toContain(COLD_START_HINTS.noClients);
+  });
+
+  it('project-not-found on a populated account stays a plain error', async () => {
+    mocked.listProjects.mockResolvedValue({ projects: [{ id: 'p1', name: 'Other' }] });
+    mocked.listClients.mockResolvedValue({ clients: [{ id: 'c1', name: 'Acme' }] });
+    const res = await handleTool('start_timer', { project: 'Website' });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).not.toContain('create_client');
+  });
+});
+
+describe('create_client', () => {
+  it('creates and returns the next-step hint', async () => {
+    mocked.createClient.mockResolvedValue({ client: { id: 'c9', name: 'Acme' } });
+    const res = await handleTool('create_client', { name: 'Acme' });
+    expect(res.isError).not.toBe(true);
+    expect(mocked.createClient).toHaveBeenCalledWith({ name: 'Acme' });
+    expect(textOf(res)).toContain('create_project');
+  });
+
+  it('passes the optional email through', async () => {
+    mocked.createClient.mockResolvedValue({ client: { id: 'c9' } });
+    await handleTool('create_client', { name: 'Acme', email: 'a@acme.com' });
+    expect(mocked.createClient).toHaveBeenCalledWith({ name: 'Acme', email: 'a@acme.com' });
+  });
+
+  it('rejects a missing name via zod', async () => {
+    const res = await handleTool('create_client', {});
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toContain('Invalid arguments');
+  });
+});
+
+describe('create_project', () => {
+  it('resolves the client by exact name', async () => {
+    mocked.listClients.mockResolvedValue({ clients: [{ id: 'c1', name: 'Acme' }] });
+    mocked.createProject.mockResolvedValue({ project: { id: 'p9', name: 'Website' } });
+    const res = await handleTool('create_project', { name: 'Website', client: 'Acme' });
+    expect(res.isError).not.toBe(true);
+    expect(mocked.createProject).toHaveBeenCalledWith({ name: 'Website', clientId: 'c1' });
+    expect(textOf(res)).toContain('start_timer');
+  });
+
+  it('unknown client on an empty account → client-first guidance', async () => {
+    mocked.listClients.mockResolvedValue({ clients: [] });
+    const res = await handleTool('create_project', { name: 'Website', client: 'Acme' });
+    expect(res.isError).toBe(true);
+    expect(textOf(res)).toContain(COLD_START_HINTS.noClients);
+  });
+
+  it('rejects missing fields via zod', async () => {
+    expect((await handleTool('create_project', { name: 'X' })).isError).toBe(true);
+    expect((await handleTool('create_project', { client: 'X' })).isError).toBe(true);
+  });
+});

src/mcp/server.ts

@@ -10,7 +10,7 @@ import { createRequire } from 'node:module';
 import { z } from 'zod';
 import { api, ApiError } from '../lib/api.js';
 import { readConfig } from '../lib/config.js';
-import { resolveProject } from '../lib/resolve.js';
+import { resolveClient, resolveProject } from '../lib/resolve.js';
 import { parseDuration } from '../lib/format.js';
 
 const pkg = createRequire(import.meta.url)('../../package.json') as { version: string };
@@ -65,6 +65,17 @@ const updateEntryInput = z.object({
   rate: z.string().optional().describe('Switch billable rate (id or name).'),
 });
 
+const createClientInput = z.object({
+  name: z.string().min(1, '`name` is required'),
+  email: z.string().optional(),
+});
+
+const createProjectInput = z.object({
+  name: z.string().min(1, '`name` is required'),
+  client: z.string().min(1, '`client` is required (id or exact name)'),
+  description: z.string().optional(),
+});
+
 const deleteEntryInput = z.object({
   id: z.string().describe('Entry id (uuid) to delete.'),
 });
@@ -261,6 +272,49 @@ const TOOLS: Tool[] = [
       openWorldHint: true,
     },
   },
+  // Cold-start tools: mirror of the hosted MCP server (backend
+  // src/mcp/tools.ts) so agent-first setup works over stdio too.
+  {
+    name: 'create_client',
+    description:
+      'Create a client (the person/company you bill). Needed before any project or time entry can exist. Typical first step on a fresh account.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: "Client name, e.g. 'Acme Corp'." },
+        email: { type: 'string', description: 'Optional billing/contact email.' },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
+  },
+  {
+    name: 'create_project',
+    description:
+      'Create a project under a client. Time entries are always tracked against a project. Typical second step on a fresh account, after create_client.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: "Project name, e.g. 'Website redesign'." },
+        client: { type: 'string', description: 'Client - id or exact name.' },
+        description: { type: 'string', description: 'Optional project description.' },
+      },
+      required: ['name', 'client'],
+      additionalProperties: false,
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
+  },
 ];
 
 type ToolResult = CallToolResult;
@@ -274,6 +328,36 @@ const err = (message: string): ToolResult => ({
   isError: true,
 });
 
+// Like ok(), plus a guidance line the agent can act on (mirrors the hosted
+// MCP server's cold-start behavior — keep the wording in sync with
+// backend/src/mcp/tools.ts in the timebook repo).
+const okWithHint = (data: unknown, hint: string): ToolResult => ({
+  content: [
+    { type: 'text', text: JSON.stringify(data, null, 2) },
+    { type: 'text', text: hint },
+  ],
+});
+
+export const COLD_START_HINTS = {
+  noClients:
+    'This account has no clients yet. Create one with create_client (just a name is enough), then add a project with create_project — after that you can start timers and log time.',
+  noProjects:
+    'There are clients but no projects yet. Create one with create_project (name + client), then you can start timers and log time against it.',
+  noEntries:
+    'No time entries yet. Start a timer with start_timer or log past work with log_time (both need a project).',
+} as const;
+
+async function coldStartHintFor(emptyWhat: 'projects' | 'entries'): Promise<string> {
+  try {
+    const [{ clients }, { projects }] = await Promise.all([api.listClients(), api.listProjects()]);
+    if (clients.length === 0) return COLD_START_HINTS.noClients;
+    if (projects.length === 0) return COLD_START_HINTS.noProjects;
+  } catch {
+    // Counting failed — fall through to the generic hint for the surface.
+  }
+  return emptyWhat === 'entries' ? COLD_START_HINTS.noEntries : COLD_START_HINTS.noProjects;
+}
+
 async function ensureLoggedIn(): Promise<void> {
   const config = await readConfig();
   if (!config.token) {
@@ -283,7 +367,7 @@ async function ensureLoggedIn(): Promise<void> {
   }
 }
 
-async function handleTool(name: string, args: unknown): Promise<ToolResult> {
+export async function handleTool(name: string, args: unknown): Promise<ToolResult> {
   try {
     await ensureLoggedIn();
 
@@ -294,10 +378,12 @@ async function handleTool(name: string, args: unknown): Promise<ToolResult> {
       }
       case 'list_projects': {
         const { projects } = await api.listProjects();
+        if (projects.length === 0) return okWithHint(projects, await coldStartHintFor('projects'));
         return ok(projects);
       }
       case 'list_clients': {
         const { clients } = await api.listClients();
+        if (clients.length === 0) return okWithHint(clients, COLD_START_HINTS.noClients);
         return ok(clients);
       }
       case 'get_active_timer': {
@@ -374,6 +460,7 @@ async function handleTool(name: string, args: unknown): Promise<ToolResult> {
           endDate: input.endDate,
         });
         const limit = input.limit ?? DEFAULT_ENTRY_LIMIT;
+        if (entries.length === 0) return okWithHint(entries, await coldStartHintFor('entries'));
         return ok(entries.slice(0, limit));
       }
       case 'update_entry': {
@@ -406,6 +493,30 @@ async function handleTool(name: string, args: unknown): Promise<ToolResult> {
         const result = await api.deleteEntry(input.id);
         return ok(result);
       }
+      case 'create_client': {
+        const input = createClientInput.parse(args ?? {});
+        const { client } = await api.createClient({
+          name: input.name,
+          ...(input.email ? { email: input.email } : {}),
+        });
+        return okWithHint(
+          client,
+          'Client created. Next: create_project (name + this client), then start_timer or log_time.',
+        );
+      }
+      case 'create_project': {
+        const input = createProjectInput.parse(args ?? {});
+        const client = await resolveClient(input.client);
+        const { project } = await api.createProject({
+          name: input.name,
+          clientId: client.id,
+          ...(input.description ? { description: input.description } : {}),
+        });
+        return okWithHint(
+          project,
+          'Project created. You can now start_timer or log_time against it.',
+        );
+      }
       default:
         return err(`Unknown tool: ${name}`);
     }
@@ -416,7 +527,23 @@ async function handleTool(name: string, args: unknown): Promise<ToolResult> {
     if (e instanceof ApiError) {
       return err(`API error (${e.status}): ${e.message}`);
     }
-    return err(e instanceof Error ? e.message : String(e));
+    const message = e instanceof Error ? e.message : String(e);
+    // Cold-start enrichment: "not found" on a fresh account usually means
+    // nothing exists yet — tell the agent how to fix that instead of
+    // leaving it to guess.
+    if (/^Project not found:/.test(message) || /^Client not found:/.test(message)) {
+      try {
+        const { clients } = await api.listClients();
+        if (clients.length === 0) return err(`${message}. ${COLD_START_HINTS.noClients}`);
+        if (/^Project not found:/.test(message)) {
+          const { projects } = await api.listProjects();
+          if (projects.length === 0) return err(`${message}. ${COLD_START_HINTS.noProjects}`);
+        }
+      } catch {
+        // fall through to the plain error
+      }
+    }
+    return err(message);
   }
 }