viviscape-mcp 2.0.2 → 2.2.0

package/dist/index.js

@@ -6,6 +6,8 @@ import { config } from 'dotenv';
 import { ViviScapeClient } from './api-client.js';
 import { AuthService } from './auth/auth-service.js';
 import { describe } from './auth/credentials.js';
+import { PRIORITIES, PROJECT_STATUSES, PROSPECT_STATUSES, TASK_STATUSES, enumReference, } from './enums.js';
+import { FILE_FIELDS, NOTE_FIELDS, PROJECT_FIELDS, TASK_FIELDS, filterTasks, shape, } from './projection.js';
 import { baseUrl } from './config.js';
 // quiet: dotenv's banner goes to stdout, which is the MCP protocol channel.
 config({ quiet: true });
@@ -37,6 +39,39 @@ const server = new McpServer({
 function json(data) {
     return JSON.stringify(data, null, 2);
 }
+/**
+ * Phase 2 (docs/AGENT-CAPABILITY-SPEC.md): list rows carry ~90 columns, so every
+ * list tool takes a page window and an optional field list. Defaults keep the
+ * response inside a tool-result budget; fields:["all"] opts out.
+ */
+const pageArgs = {
+    fields: z.array(z.string()).optional()
+        .describe('Columns to return. Omit for a PM-relevant default; ["all"] for every column.'),
+    limit: z.number().optional().describe('Max rows to return (default 50)'),
+    offset: z.number().optional().describe('Rows to skip, for paging (default 0)'),
+};
+const taskFilterArgs = {
+    company_id: z.number().optional().describe('Only tasks for this company'),
+    project_id: z.number().optional().describe('Only tasks in this project (group_id)'),
+    assignee_id: z.number().optional().describe('Only tasks assigned to this user id'),
+    status: z.string().optional().describe('Exact status match, e.g. new, inprogress'),
+    priority: z.string().optional().describe('Exact priority match, e.g. low, moderate, important, critical'),
+    due_before: z.string().optional().describe('Only tasks due on or before this date (ISO 8601)'),
+    due_after: z.string().optional().describe('Only tasks due on or after this date (ISO 8601)'),
+    search: z.string().optional().describe('Case-insensitive substring match on title, description, notes'),
+};
+// Variants that drop the key a given tool already takes as a required arg,
+// so the spread cannot overwrite it with an optional one.
+const { project_id: _omitProject, ...taskFilterArgsNoProject } = taskFilterArgs;
+const { company_id: _omitCompany, ...taskFilterArgsNoCompany } = taskFilterArgs;
+/** Split a tool's params into page options and everything else. */
+function paging(p) {
+    return {
+        fields: p.fields,
+        limit: p.limit,
+        offset: p.offset,
+    };
+}
 // ============================================================
 // AUTH
 // ============================================================
@@ -112,7 +147,7 @@ server.tool('prospect_add', 'Add a new prospect/lead to the ViviScape CRM', {
     source: z.string().optional().describe('Lead source (e.g., "Website", "ROI Calculator")'),
     source_url: z.string().optional().describe('URL where the lead came from'),
     referred_by: z.string().optional().describe('Referral source'),
-    status: z.string().optional().describe('Status: new, firstcontact, negotiation, pending, won, lost, spam'),
+    status: z.enum(PROSPECT_STATUSES).optional().describe('Pipeline stage (platform values)'),
 }, async (params) => {
     const result = await requireClient().addProspect(params);
     return { content: [{ type: 'text', text: json(result) }] };
@@ -127,7 +162,7 @@ server.tool('prospect_update', 'Update an existing prospect in the CRM', {
     org: z.string().optional(),
     note: z.string().optional(),
     source: z.string().optional(),
-    status: z.string().optional().describe('Status: new, firstcontact, negotiation, pending, won, lost, spam'),
+    status: z.enum(PROSPECT_STATUSES).optional().describe('Pipeline stage (platform values)'),
     priority: z.number().optional().describe('Priority level'),
 }, async (params) => {
     const result = await requireClient().updateProspect(params);
@@ -272,13 +307,17 @@ server.tool('clients_by_company', 'Get all clients for a company', { company_id:
 // ============================================================
 // PROJECTS & TASKS
 // ============================================================
-server.tool('project_list', 'Get all projects for current user', {}, async () => {
+server.tool('project_list', 'Get all projects for current user. Returns a page of trimmed rows; see fields/limit/offset.', {
+    ...pageArgs,
+}, async (params) => {
     const result = await requireClient().getMyProjects();
-    return { content: [{ type: 'text', text: json(result) }] };
+    return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
 });
-server.tool('project_list_active', 'Get active projects for current user', {}, async () => {
+server.tool('project_list_active', 'Get active projects for current user. Returns a page of trimmed rows; see fields/limit/offset.', {
+    ...pageArgs,
+}, async (params) => {
     const result = await requireClient().getActiveProjects();
-    return { content: [{ type: 'text', text: json(result) }] };
+    return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
 });
 server.tool('project_get', 'Get a project by ID', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
     const result = await requireClient().getProjectById(project_id);
@@ -288,23 +327,43 @@ server.tool('project_staff', 'Get staff members assigned to a project', { projec
     const result = await requireClient().getProjectStaff(project_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('project_tasks', 'Get all tasks for a project', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
-    const result = await requireClient().getProjectTasks(project_id);
-    return { content: [{ type: 'text', text: json(result) }] };
-});
-server.tool('tasks_open', 'Get all open tasks across projects', {}, async () => {
-    const result = await requireClient().getOpenTasks();
-    return { content: [{ type: 'text', text: json(result) }] };
+server.tool('project_tasks', 'Get all tasks for a project. Returns a page of trimmed rows; see fields/limit/offset.', {
+    project_id: z.number().describe('Project ID'),
+    ...pageArgs,
+    ...taskFilterArgsNoProject,
+}, async (params) => {
+    const result = await requireClient().getProjectTasks(params.project_id);
+    // project_id is the query, not a filter -- re-filtering on it would drop
+    // every row if the response names the column differently.
+    const rows = Array.isArray(result)
+        ? filterTasks(result, { ...params, project_id: undefined })
+        : result;
+    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+});
+server.tool('tasks_open', 'Get open tasks across projects. company_id and only_mine filter server-side; the rest filter in-process. Returns a page of trimmed rows.', {
+    only_mine: z.boolean().optional().describe('Only tasks assigned to the signed-in user (server-side)'),
+    team: z.string().optional().describe('Team filter passed through to the API'),
+    ...taskFilterArgs,
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getOpenTasks({
+        company_id: params.company_id,
+        only_mine: params.only_mine,
+        team: params.team,
+    });
+    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
 server.tool('task_add', 'Add a task to a project. The API requires a full Group_Task payload; this tool builds it from simplified params.', {
     project_id: z.number().describe('Project ID (group_id)'),
     title: z.string().describe('Task title'),
     description: z.string().optional().describe('Task description'),
     notes: z.string().optional().describe('Task notes'),
-    assigned_to: z.number().optional().describe('User ID to assign to (also sets creator). Defaults to Art Hicks (210)'),
+    assigned_to: z.number().optional().describe('User ID to assign the task to. The signed-in user is always recorded as creator.'),
     company_id: z.number().optional().describe('Company ID associated with the project'),
     service_id: z.number().optional().describe('Service ID classifying the work type'),
-    priority: z.string().optional().describe('Priority: low, medium, high, critical'),
+    priority: z.enum(PRIORITIES).optional().describe('Priority (platform values)'),
+    status: z.enum(TASK_STATUSES).optional().describe('Task status (platform values)'),
     estimated_hours: z.string().optional().describe('Estimated time in shorthand (e.g., 6h, 2h30m)'),
     start_date: z.string().optional().describe('Start date (ISO 8601)'),
     due_date: z.string().optional().describe('Due date (ISO 8601)'),
@@ -318,8 +377,8 @@ server.tool('task_update', 'Update a task. Fetches existing task first and merge
     title: z.string().optional().describe('Task title'),
     description: z.string().optional(),
     assigned_to: z.number().optional().describe('User ID to assign to'),
-    priority: z.string().optional().describe('Priority: low, medium, high, critical'),
-    status: z.string().optional().describe('Status: new, inprogress, complete, onhold'),
+    priority: z.enum(PRIORITIES).optional().describe('Priority (platform values)'),
+    status: z.enum(TASK_STATUSES).optional().describe('Task status (platform values)'),
     due_date: z.string().optional().describe('Due date (ISO 8601)'),
 }, async (params) => {
     const result = await requireClient().updateTask(params);
@@ -329,34 +388,404 @@ server.tool('task_get', 'Get a single task by ID', { task_id: z.number().describ
     const result = await requireClient().getTask(task_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('tasks_pending', 'Get pending tasks for a user', { user_id: z.number().describe('User ID') }, async ({ user_id }) => {
-    const result = await requireClient().getPendingTasks(user_id);
+server.tool('tasks_pending', 'Get pending tasks for a user. Returns a page of trimmed rows; see fields/limit/offset.', {
+    user_id: z.number().describe('User ID'),
+    ...pageArgs,
+    ...taskFilterArgs,
+}, async (params) => {
+    const result = await requireClient().getPendingTasks(params.user_id);
+    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+});
+server.tool('tasks_by_milestone', 'Get tasks for a milestone. Returns a page of trimmed rows; see fields/limit/offset.', {
+    milestone_id: z.number().describe('Milestone ID'),
+    ...pageArgs,
+    ...taskFilterArgs,
+}, async (params) => {
+    const result = await requireClient().getTasksByMilestone(params.milestone_id);
+    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+});
+server.tool('tasks_by_group_user', 'Get tasks by project group and user. Returns a page of trimmed rows; see fields/limit/offset.', {
+    group_id: z.number().describe('Project group ID'),
+    user_id: z.number().describe('User ID'),
+    ...pageArgs,
+    ...taskFilterArgs,
+}, async (params) => {
+    const result = await requireClient().getTasksByGroupAndUser(params.group_id, params.user_id);
+    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+});
+server.tool('tasks_by_company', 'Get tasks for a company. Returns a page of trimmed rows; see fields/limit/offset.', {
+    company_id: z.number().describe('Company ID'),
+    ...pageArgs,
+    ...taskFilterArgsNoCompany,
+}, async (params) => {
+    const result = await requireClient().getCompanyTasks(params.company_id);
+    const rows = Array.isArray(result)
+        ? filterTasks(result, { ...params, company_id: undefined })
+        : result;
+    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+});
+server.tool('projects_by_company', 'Get user projects filtered by company. Returns a page of trimmed rows; see fields/limit/offset.', {
+    user_id: z.number().describe('User ID'),
+    company_id: z.number().describe('Company ID'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getProjectsByCompany(params.user_id, params.company_id);
+    return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
+});
+server.tool('projects_active_by_user', 'Get active projects for a specific user. Returns a page of trimmed rows; see fields/limit/offset.', {
+    user_id: z.number().describe('User ID'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getActiveProjectsByUser(params.user_id);
+    return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
+});
+// ============================================================
+// DOCUMENTATION: NOTE RELATIONS, TAGS, REVISIONS, ATTACHMENTS
+// ============================================================
+//
+// These tools take an `action` rather than splitting every verb into its own
+// tool: the server already registers ~90 tools, and past roughly 100 the tool
+// list itself starts costing more than it returns. Each action names exactly
+// which arguments it needs, and a missing one is reported by name.
+/** Fail with a message that names the action and the argument it wanted. */
+function need(action, name, value) {
+    if (value === undefined || value === null || value === '') {
+        throw new Error(`action "${action}" requires ${name}`);
+    }
+    return value;
+}
+server.tool('notes_account', 'List notes across the account, newest-first as the API returns them. Bodies are omitted by default (hundreds of rows); pass fields:["note_id","title","note"] to read content.', {
+    company_id: z.number().optional().describe('Restrict to notes linked to this company'),
+    user_id: z.number().optional().describe('Restrict to notes for this user'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getAccountNotes(params.company_id ?? 0, params.user_id ?? 0);
+    return { content: [{ type: 'text', text: json(shape(result, NOTE_FIELDS, paging(params))) }] };
+});
+server.tool('note_revisions', 'Get the edit history of a note. Use before rewriting a shared note so human edits are not silently clobbered.', { note_id: z.string().describe('Note ID (GUID)') }, async ({ note_id }) => {
+    const result = await requireClient().getNoteRevisions(note_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_companies', 'Link a note to a company, list its links, or remove one. This is how a generated document gets filed against a client. NOTE: add returns an echo with zeroed ids, so call list afterward to get the assignment_id you need for remove.', {
+    action: z.enum(['list', 'add', 'remove']).describe('What to do'),
+    note_id: z.string().optional().describe('Note ID (list, add)'),
+    company_id: z.number().optional().describe('Company ID (add)'),
+    assignment_id: z.string().optional().describe('Link ID from list (remove)'),
+}, async ({ action, note_id, company_id, assignment_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNoteCompanies(need(action, 'note_id', note_id))
+        : action === 'add' ? await c.addNoteCompany(need(action, 'note_id', note_id), need(action, 'company_id', company_id))
+            : await c.removeNoteCompany(need(action, 'assignment_id', assignment_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_users', 'Share a note with a user, list who it is shared with, change a permission, or unshare. NOTE: add returns an echo with zeroed ids; call list to get the assignment_id.', {
+    action: z.enum(['list', 'add', 'update', 'remove']).describe('What to do'),
+    note_id: z.string().optional().describe('Note ID (list, add, update)'),
+    user_id: z.number().optional().describe('User ID (add, update)'),
+    permission: z.string().optional().describe('Permission, e.g. read or write (add, update)'),
+    assignment_id: z.string().optional().describe('Share ID from list (update, remove)'),
+}, async ({ action, note_id, user_id, permission, assignment_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNoteUsers(need(action, 'note_id', note_id))
+        : action === 'add' ? await c.addNoteUser(need(action, 'note_id', note_id), need(action, 'user_id', user_id), permission || 'read')
+            : action === 'update' ? await c.updateNoteUser(need(action, 'assignment_id', assignment_id), need(action, 'note_id', note_id), need(action, 'user_id', user_id), need(action, 'permission', permission))
+                : await c.removeNoteUser(need(action, 'assignment_id', assignment_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_tags', 'List, add, or remove tags on a note -- the only way to categorise notes for later retrieval. NOTE: remove answers false even when it succeeds; re-list to confirm.', {
+    action: z.enum(['list', 'add', 'remove']).describe('What to do'),
+    note_id: z.string().optional().describe('Note ID (list, add)'),
+    tag: z.string().optional().describe('Tag text (add)'),
+    tag_id: z.string().optional().describe('Tag ID from list (remove)'),
+}, async ({ action, note_id, tag, tag_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNoteTags(need(action, 'note_id', note_id))
+        : action === 'add' ? await c.addNoteTag(need(action, 'note_id', note_id), need(action, 'tag', tag))
+            : await c.removeNoteTag(need(action, 'tag_id', tag_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_attachments', 'List, upload, or remove note attachments, or flag one as knowledge-base material. upload takes a path to a local file.', {
+    action: z.enum(['list', 'upload', 'remove', 'set_knowledge']).describe('What to do'),
+    note_id: z.string().optional().describe('Note ID (list, upload)'),
+    file_path: z.string().optional().describe('Local file to upload (upload)'),
+    knowledge: z.boolean().optional().describe('Mark for text extraction (upload, set_knowledge)'),
+    attachment_id: z.string().optional().describe('Attachment ID from list (remove, set_knowledge)'),
+}, async ({ action, note_id, file_path, knowledge, attachment_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNoteAttachments(need(action, 'note_id', note_id))
+        : action === 'upload' ? await c.uploadNoteAttachment(need(action, 'note_id', note_id), need(action, 'file_path', file_path), knowledge ?? false)
+            : action === 'remove' ? await c.removeNoteAttachment(need(action, 'attachment_id', attachment_id))
+                : await c.setNoteAttachmentKnowledge({
+                    attachment_id: need(action, 'attachment_id', attachment_id),
+                    note_id: note_id ?? undefined,
+                    knowledge: knowledge ?? true,
+                });
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('notebook', 'Notebooks group notes into a per-client or per-project documentation space. Actions: list, add, update, remove, notes (list a book contents), assign / unassign notes. WARNING: remove is broken server-side (400 even for an empty book) -- delete notebooks in the ViviScape Work UI.', {
+    action: z.enum(['list', 'add', 'update', 'remove', 'notes', 'assign', 'unassign']).describe('What to do'),
+    book_id: z.string().optional().describe('Notebook ID (update, remove, notes, assign, unassign)'),
+    name: z.string().optional().describe('Notebook name (add, update)'),
+    description: z.string().optional().describe('Notebook description (add, update)'),
+    note_ids: z.array(z.string()).optional().describe('Note IDs (assign, unassign)'),
+    user_id: z.number().optional().describe('Owner to list for (list; defaults to signed-in user)'),
+}, async ({ action, book_id, name, description, note_ids, user_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNotebooks(user_id ?? 0)
+        : action === 'add' ? await c.addNotebook(need(action, 'name', name), description || '')
+            : action === 'update' ? await c.updateNotebook(need(action, 'book_id', book_id), {
+                ...(name ? { name } : {}),
+                ...(description !== undefined ? { description } : {}),
+            })
+                : action === 'remove' ? await c.removeNotebook(need(action, 'book_id', book_id))
+                    : action === 'notes' ? await c.getNotebookNotes(need(action, 'book_id', book_id))
+                        : await c.assignNotesToBook(need(action, 'book_id', book_id), need(action, 'note_ids', note_ids), action === 'assign');
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('notebook_users', 'List, add, update, or remove the users a notebook is shared with', {
+    action: z.enum(['list', 'add', 'update', 'remove']).describe('What to do'),
+    book_id: z.string().optional().describe('Notebook ID (list, add, update)'),
+    user_id: z.number().optional().describe('User ID (add, update)'),
+    permission: z.string().optional().describe('Permission, e.g. read, write, owner (add, update)'),
+    assignment_id: z.string().optional().describe('Share ID from list (update, remove)'),
+}, async ({ action, book_id, user_id, permission, assignment_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNotebookUsers(need(action, 'book_id', book_id))
+        : action === 'add' ? await c.addNotebookUser(need(action, 'book_id', book_id), need(action, 'user_id', user_id), permission || 'read')
+            : action === 'update' ? await c.updateNotebookUser(need(action, 'assignment_id', assignment_id), need(action, 'book_id', book_id), need(action, 'user_id', user_id), need(action, 'permission', permission))
+                : await c.removeNotebookUser(need(action, 'assignment_id', assignment_id));
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('tasks_by_milestone', 'Get tasks for a milestone', { milestone_id: z.number().describe('Milestone ID') }, async ({ milestone_id }) => {
-    const result = await requireClient().getTasksByMilestone(milestone_id);
+// ============================================================
+// PROJECT AND TASK FILES
+// ============================================================
+server.tool('project_files', 'List, upload, update, delete, or resolve the download URL of files attached to a project. upload takes a path to a local file; delete is by file_id from list.', {
+    action: z.enum(['list', 'upload', 'update', 'delete', 'download']).describe('What to do'),
+    project_id: z.number().optional().describe('Project ID (list, upload)'),
+    file_path: z.string().optional().describe('Local file to upload (upload)'),
+    title: z.string().optional().describe('Title for the uploaded file (upload; defaults to the filename)'),
+    task_id: z.number().optional().describe('Attach the upload to a task as well (upload)'),
+    notify: z.boolean().optional().describe('Notify project members (upload; default false)'),
+    file_id: z.number().optional().describe('File ID from list (delete, download)'),
+    file: z.record(z.string(), z.unknown()).optional().describe('Full file record with changes applied (update)'),
+    ...pageArgs,
+}, async (params) => {
+    const c = requireClient();
+    const { action } = params;
+    if (action === 'list') {
+        const result = await c.getProjectFiles(need(action, 'project_id', params.project_id));
+        return { content: [{ type: 'text', text: json(shape(result, FILE_FIELDS, paging(params))) }] };
+    }
+    const result = action === 'upload' ? await c.uploadProjectFile({
+        project_id: need(action, 'project_id', params.project_id),
+        file_path: need(action, 'file_path', params.file_path),
+        title: params.title,
+        task_id: params.task_id,
+        notify: params.notify,
+    })
+        : action === 'update' ? await c.updateProjectFile(need(action, 'file', params.file))
+            : action === 'delete' ? await c.deleteProjectFile(need(action, 'file_id', params.file_id))
+                : await c.downloadProjectFile(need(action, 'file_id', params.file_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_files', 'List files attached to a task. Use this to read context humans already attached before generating anything new.', {
+    task_id: z.number().describe('Task ID'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getTaskFiles(params.task_id);
+    return { content: [{ type: 'text', text: json(shape(result, FILE_FIELDS, paging(params))) }] };
+});
+// ============================================================
+// REFERENCE
+// ============================================================
+server.tool('enums', 'List the status, priority, and group-type values the platform actually accepts. Read this before setting a status or priority; tasks complete as "completed" while projects complete as "complete", and priority is low/moderate/important/urgent/critical.', {}, async () => ({ content: [{ type: 'text', text: json(enumReference()) }] }));
+// ============================================================
+// PROJECT WRITES
+// ============================================================
+server.tool('project_add', 'Create a project for a company. NOTE: the API has no project-delete route, so a project created here can only be archived or renamed afterward.', {
+    company_id: z.number().describe('Company ID the project belongs to'),
+    name: z.string().describe('Project name'),
+    short_description: z.string().optional().describe('One-line summary'),
+    description: z.string().optional().describe('Full description'),
+    status: z.enum(PROJECT_STATUSES).optional().describe('Initial status (default new)'),
+    is_public: z.boolean().optional().describe('Visible to clients (default false)'),
+    staff: z.array(z.number()).optional().describe('User ids to staff; defaults to the signed-in user'),
+}, async (params) => {
+    const result = await requireClient().addProject(params);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('tasks_by_group_user', 'Get tasks by project group and user', {
-    group_id: z.number().describe('Project group ID'),
-    user_id: z.number().describe('User ID'),
-}, async ({ group_id, user_id }) => {
-    const result = await requireClient().getTasksByGroupAndUser(group_id, user_id);
+server.tool('project_update', 'Update a project. Reads the current row and merges your changes onto it, so only pass what changes. Field names are the raw GEN_Group ones (strGroupName, strGroupDescription, bitPublic, target_date, ...).', {
+    project_id: z.number().describe('Project ID (intGroupId)'),
+    changes: z.record(z.string(), z.unknown()).describe('Fields to overwrite, e.g. {"strGroupName":"New name"}'),
+}, async ({ project_id, changes }) => {
+    const result = await requireClient().updateProject(project_id, changes);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('project_set_status', 'Set a project status without touching its budget or approved time. Project status values are new, inprogress, complete -- note "complete", not "completed".', {
+    project_id: z.number().describe('Project ID'),
+    status: z.enum(PROJECT_STATUSES).describe('New status'),
+    billable: z.boolean().optional().describe('Billable flag (default true)'),
+}, async ({ project_id, status, billable }) => {
+    const result = await requireClient().setProjectStatus(project_id, status, billable ?? true);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('project_user_add', 'Add a staff member to a project, optionally as lead or client contact', {
+    project_id: z.number().describe('Project ID'),
+    user_id: z.number().describe('User ID to add'),
+    is_lead: z.boolean().optional().describe('Make this user the project lead'),
+    is_contact: z.boolean().optional().describe('Mark as the client contact'),
+}, async ({ project_id, user_id, is_lead, is_contact }) => {
+    const result = await requireClient().addProjectUser(project_id, user_id, { is_lead, is_contact });
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('tasks_by_company', 'Get tasks for a company', { company_id: z.number().describe('Company ID') }, async ({ company_id }) => {
-    const result = await requireClient().getCompanyTasks(company_id);
+server.tool('project_user_remove', 'Remove a staff member from a project', {
+    project_id: z.number().describe('Project ID'),
+    user_id: z.number().describe('User ID to remove'),
+}, async ({ project_id, user_id }) => {
+    const result = await requireClient().removeProjectUser(project_id, user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// MILESTONES
+// ============================================================
+server.tool('milestone_list', 'List milestones for a project', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
+    const result = await requireClient().getMilestones(project_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestones_active', 'List active milestones across the account', {}, async () => {
+    const result = await requireClient().getActiveMilestones();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestones_by_company', 'List milestones for a company', { company_id: z.number().describe('Company ID') }, async ({ company_id }) => {
+    const result = await requireClient().getMilestonesByCompany(company_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestones_by_user', 'List active milestones for a user (defaults to the signed-in user)', { user_id: z.number().optional().describe('User ID') }, async ({ user_id }) => {
+    const result = await requireClient().getMilestonesByUser(user_id ?? 0);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestone_get', 'Get a milestone by ID', { milestone_id: z.number().describe('Milestone ID') }, async ({ milestone_id }) => {
+    const result = await requireClient().getMilestone(milestone_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestone_add', 'Create a milestone in a project. Use this to give tasks a phase to hang off; tasks reference it via milestone_id.', {
+    project_id: z.number().describe('Project ID the milestone belongs to'),
+    title: z.string().describe('Milestone name'),
+    sequence: z.number().optional().describe('Order within the project'),
+    start_date: z.string().optional().describe('Start date (ISO 8601)'),
+    due_date: z.string().optional().describe('Due date (ISO 8601)'),
+    estimated_hours: z.string().optional().describe('Estimate in shorthand (e.g., 40h, 2h30m)'),
+}, async (params) => {
+    const result = await requireClient().addMilestone(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestone_update', 'Update a milestone. Reads the current record and merges your changes onto it.', {
+    milestone_id: z.number().describe('Milestone ID'),
+    title: z.string().optional().describe('New name'),
+    sequence: z.number().optional().describe('Order within the project'),
+    start_date: z.string().optional().describe('Start date (ISO 8601)'),
+    due_date: z.string().optional().describe('Due date (ISO 8601)'),
+    estimated_hours: z.string().optional().describe('Estimate in shorthand'),
+    progress: z.number().optional().describe('Percent complete (0-100)'),
+    complete: z.boolean().optional().describe('Mark complete'),
+}, async (params) => {
+    const result = await requireClient().updateMilestone(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestone_clone', 'Copy an existing milestone into a project. Useful for repeatable delivery templates.', {
+    milestone_id: z.number().describe('Milestone ID to copy'),
+    project_id: z.number().describe('Project ID to copy it into'),
+    title: z.string().optional().describe('Name for the copy (defaults to the original name)'),
+}, async ({ milestone_id, project_id, title }) => {
+    const result = await requireClient().cloneMilestone(milestone_id, project_id, title);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('projects_by_company', 'Get user projects filtered by company', {
+server.tool('milestone_remove', 'Delete a milestone', { milestone_id: z.number().describe('Milestone ID') }, async ({ milestone_id }) => {
+    const result = await requireClient().removeMilestone(milestone_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// TASK ASSIGNMENT AND LIFECYCLE
+// ============================================================
+server.tool('task_assignee_add', 'Assign a user to a task', {
+    task_id: z.number().describe('Task ID'),
+    user_id: z.number().describe('User ID to assign'),
+    leader: z.boolean().optional().describe('Make this user the task leader'),
+    attention: z.boolean().optional().describe('Flag the task for this user\'s attention'),
+    notify: z.boolean().optional().describe('Notify the user (default true)'),
+}, async (params) => {
+    const result = await requireClient().addTaskAssignee(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_assignee_remove', 'Unassign a user from a task. Takes the assignee_id from the task staff_assignees list, NOT a user_id.', { assignee_id: z.number().describe('Assignee record ID (from staff_assignees)') }, async ({ assignee_id }) => {
+    const result = await requireClient().removeTaskAssignee(assignee_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_set_leader', 'Make a user the leader on a task', {
+    task_id: z.number().describe('Task ID'),
+    user_id: z.number().describe('User ID to make leader'),
+}, async ({ task_id, user_id }) => {
+    const result = await requireClient().setTaskLeader(task_id, user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_set_attention', 'Set or clear the attention flag for a user on a task', {
+    task_id: z.number().describe('Task ID'),
     user_id: z.number().describe('User ID'),
-    company_id: z.number().describe('Company ID'),
-}, async ({ user_id, company_id }) => {
-    const result = await requireClient().getProjectsByCompany(user_id, company_id);
+    flag: z.boolean().describe('true to flag, false to clear'),
+}, async ({ task_id, user_id, flag }) => {
+    const result = await requireClient().setTaskAttention(task_id, user_id, flag);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_delete', 'Delete a task permanently. There is no undo; prefer setting status to cancelled unless the task was created in error.', { task_id: z.number().describe('Task ID') }, async ({ task_id }) => {
+    const result = await requireClient().deleteTask(task_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_merge', 'Merge one task into another. The source task is consumed by the target; use this to clean up duplicates.', {
+    from_task_id: z.number().describe('Task to merge from (consumed)'),
+    to_task_id: z.number().describe('Task to merge into (kept)'),
+}, async ({ from_task_id, to_task_id }) => {
+    const result = await requireClient().mergeTasks(from_task_id, to_task_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// TASK COMMENTS
+// ============================================================
+server.tool('task_comments', 'Get all comments on a task. Task rows report total_comments and unread_for_me; this reads the thread itself.', { task_id: z.number().describe('Task ID') }, async ({ task_id }) => {
+    const result = await requireClient().getTaskComments(task_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_comment_get', 'Get a single task comment by ID', { comment_id: z.string().describe('Comment ID (GUID)') }, async ({ comment_id }) => {
+    const result = await requireClient().getTaskComment(comment_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_comment_add', 'Add a comment to a task. WARNING: on this platform account the backend fires a client-notification webhook for comments on tasks whose client_id > 0, so a comment can reach the customer. Check the task client_id first if that matters.', {
+    task_id: z.number().describe('Task ID'),
+    comment: z.string().describe('Comment text'),
+    client_id: z.number().optional().describe('Client ID to attribute the comment to (default 0 = staff comment)'),
+}, async (params) => {
+    const result = await requireClient().addTaskComment(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_comment_update', 'Update the text of an existing task comment', {
+    comment_id: z.string().describe('Comment ID (GUID)'),
+    task_id: z.number().describe('Task ID the comment belongs to'),
+    comment: z.string().describe('Replacement comment text'),
+}, async (params) => {
+    const result = await requireClient().updateTaskComment(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_comment_remove', 'Remove a task comment by ID. Pass task_id: the backend answers 500 even when the delete succeeds, and task_id lets the removal be verified instead of reported as a failure.', {
+    comment_id: z.string().describe('Comment ID (GUID)'),
+    task_id: z.number().optional().describe('Task the comment belongs to, used to verify removal'),
+}, async ({ comment_id, task_id }) => {
+    const result = await requireClient().removeTaskComment(comment_id, task_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('projects_active_by_user', 'Get active projects for a specific user', { user_id: z.number().describe('User ID') }, async ({ user_id }) => {
-    const result = await requireClient().getActiveProjectsByUser(user_id);
+server.tool('task_mark_read', 'Mark a task read for the signed-in user, clearing unread_for_me', { task_id: z.number().describe('Task ID') }, async ({ task_id }) => {
+    const result = await requireClient().markTaskRead(task_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
 // ============================================================

package/dist/projection.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Response shaping for list tools -- phase 2 of docs/AGENT-CAPABILITY-SPEC.md.
+ *
+ * The core API returns every column it has: a task row carries ~90 fields
+ * (including fleet columns like vin and unit_class) and a project row carries 87
+ * (including video-conference config and welcome messages). Six open tasks came
+ * back as 102 KB; 211 active projects as 487 KB, which no caller can afford to
+ * read. These helpers trim to a PM-relevant default, page the result, and tell
+ * the caller what was left out so it can ask for more deliberately.
+ */
+/** Task fields worth returning by default, of roughly 90 available. */
+export declare const TASK_FIELDS: string[];
+/** Project (group) fields worth returning by default, of 87 available. */
+export declare const PROJECT_FIELDS: string[];
+/**
+ * Note fields worth returning by default. Excludes `note` (the full body) and
+ * `firefly_transcript_id`: the account list runs to hundreds of rows and the
+ * bodies dominate the payload. Ask for fields:["note"] to read one.
+ */
+export declare const NOTE_FIELDS: string[];
+/** Project/task file fields worth returning by default. */
+export declare const FILE_FIELDS: string[];
+export declare const DEFAULT_LIMIT = 50;
+export interface ShapeOpts {
+    fields?: string[];
+    limit?: number;
+    offset?: number;
+}
+export interface TaskFilters {
+    company_id?: number;
+    project_id?: number;
+    assignee_id?: number;
+    status?: string;
+    priority?: string;
+    due_before?: string;
+    due_after?: string;
+    search?: string;
+}
+/** Apply the filters the backend does not support, in-process. */
+export declare function filterTasks(rows: unknown[], f: TaskFilters): unknown[];
+/**
+ * Trim, page, and annotate a list response. Non-array payloads (a single record,
+ * or an error object) pass through untouched.
+ *
+ * Pass fields: ['all'] to opt out of projection and get every column.
+ */
+export declare function shape(payload: unknown, defaults: string[], opts?: ShapeOpts): unknown;