@orboto/mcp 0.218.0 → 0.219.0

package/dist/input-schema.js

@@ -56,7 +56,7 @@ function applyAliases(toolName, shape, value) {
         }
     }
     if ('id' in out && !('id' in shape)) {
-        const candidates = ID_LIKE_CANONICALS.filter((c) => c in shape && !(c in out));
+        const candidates = ID_LIKE_CANONICALS.filter((c) => c in shape && !(c in out) && !(toolName === 'orboto_get_ticket' && c === 'commentId'));
         if (candidates.length === 1) {
             const canonical = candidates[0];
             const { id, ...rest } = out;

package/dist/tool-docs.js

@@ -13,7 +13,7 @@ export const SUMMARY_MAX_CHARS = 220;
  */
 const SUMMARY_OVERRIDES = {
     orboto_create_full_backup: 'Start a full-workspace backup job; returns the job id to poll via orboto_list_backups.',
-    orboto_get_ticket: 'Fetch one ticket by key or UUID with description, status, assignees, checklists and comments.',
+    orboto_get_ticket: 'Fetch a ticket by key: fields, checklists, comments.',
     orboto_requirements_spec: 'Generate a structured requirements spec for a project or milestone from its tickets.',
     orboto_update_doc_space: 'Update a doc space\'s name, description, icon, project binding or access mode (open/restricted) by space id.',
     orboto_search_docs: 'Full-text search over doc/wiki pages (query, optional space or project filter); returns matching pages with snippets.',

package/dist/tool-docs.test.js

@@ -26,7 +26,7 @@ describe('summarizeToolDescription', () => {
     });
     it('uses the hand-written override when one exists', () => {
         const s = summarizeToolDescription('orboto_get_ticket', 'A very long first sentence that would otherwise be cut mid-flow because it enumerates every field the response carries and never stops');
-        expect(s).toContain('Fetch one ticket');
+        expect(s).toContain('Fetch a ticket');
         expect(s.length).toBeLessThanOrEqual(SUMMARY_MAX_CHARS);
     });
     it('falls back to a word-boundary cut when the first sentence overruns the cap', () => {

package/dist/tools/comment-thread.js

@@ -0,0 +1,60 @@
+/** ORB-2484 - the comment thread newest first, the newest few in full and older ones shortened. */
+export const COMMENT_FULL_COUNT = 3;
+export const COMMENT_EXCERPT_CHARS = 300;
+const COMMENT_ID_MIN_PREFIX = 8;
+const COMMENT_PAGE_SIZE = 50;
+const COMMENT_MAX_PAGES = 20;
+/** Reads the whole thread, oldest first, across cursor pages. */
+export async function fetchThread(client, ticketId) {
+    const out = [];
+    let cursor = null;
+    for (let page = 0; page < COMMENT_MAX_PAGES; page++) {
+        const query = `limit=${COMMENT_PAGE_SIZE}${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`;
+        const res = await client
+            .get(`/tickets/${ticketId}/comments?${query}`)
+            .catch(() => ({ items: [], nextCursor: null }));
+        out.push(...res.items);
+        cursor = res.nextCursor;
+        if (!cursor)
+            break;
+    }
+    return out;
+}
+/** Cuts at a word boundary within max characters and reports how many characters it left out. */
+export function shortenComment(content, max) {
+    const chars = Array.from(content);
+    if (chars.length <= max)
+        return { excerpt: content, rest: 0 };
+    let end = max;
+    if (!/\s/u.test(chars[max])) {
+        for (let i = max - 1; i > 0; i--) {
+            if (/\s/u.test(chars[i])) {
+                end = i;
+                break;
+            }
+        }
+    }
+    const excerpt = chars.slice(0, end).join('').trimEnd();
+    return { excerpt, rest: chars.length - Array.from(excerpt).length };
+}
+/** Newest first; a commentId (full or an 8-character prefix) selects one comment in full. */
+export function selectComments(thread, opts) {
+    const entry = (row, whole) => {
+        const length = Array.from(row.content).length;
+        if (whole)
+            return { row, excerpt: row.content, length, rest: 0 };
+        return { row, length, ...shortenComment(row.content, COMMENT_EXCERPT_CHARS) };
+    };
+    if (opts.commentId) {
+        const want = opts.commentId.trim().toLowerCase();
+        const exact = thread.filter((c) => c.id.toLowerCase() === want);
+        const hits = exact.length > 0 ? exact : want.length >= COMMENT_ID_MIN_PREFIX ? thread.filter((c) => c.id.toLowerCase().startsWith(want)) : [];
+        if (hits.length === 0)
+            return { shown: [], error: `No comment with id "${opts.commentId}" on this ticket (a prefix needs at least ${COMMENT_ID_MIN_PREFIX} characters).` };
+        if (hits.length > 1)
+            return { shown: [], error: `The id prefix "${opts.commentId}" matches ${hits.length} comments: ${hits.map((c) => c.id).join(', ')}.` };
+        return { shown: [entry(hits[0], true)] };
+    }
+    const newestFirst = [...thread].reverse();
+    return { shown: newestFirst.map((row, n) => entry(row, opts.full === true || n < COMMENT_FULL_COUNT)) };
+}

package/dist/tools/comment-thread.test.js

@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { selectComments, shortenComment } from './comment-thread.js';
+import { makeGetTicketHandler } from './get-ticket.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+const words = (label, n) => Array.from({ length: n }, (_, i) => `${label}${String(i).padStart(2, '0')}`).join(' ');
+function thread(bodies) {
+    return bodies.map((content, i) => ({
+        id: `0000000${i + 1}-aaaa-4000-8000-00000000000${i}`,
+        content,
+        createdAt: `2026-09-${String(i + 1).padStart(2, '0')}`,
+        userName: 'Ada',
+        isInternal: false,
+    }));
+}
+describe('ORB-2484 shortened comment thread', () => {
+    it('lists newest first, the 3 newest in full and older ones shortened', () => {
+        const { shown } = selectComments(thread([words('old', 120), 'b', 'c', 'd', 'e']), {});
+        expect(shown.map((s) => s.row.content.slice(0, 3))).toEqual(['e', 'd', 'c', 'b', 'old']);
+        expect(shown[3].rest).toBe(0);
+        expect(shown[4].rest).toBeGreaterThan(0);
+        expect(Array.from(shown[4].excerpt).length).toBeLessThanOrEqual(300);
+    });
+    it('full keeps every body, commentId selects one by id or 8-character prefix', () => {
+        const t = thread([words('old', 120), 'b', 'c', 'd']);
+        expect(selectComments(t, { full: true }).shown.every((s) => s.rest === 0)).toBe(true);
+        const byPrefix = selectComments(t, { commentId: '00000001' });
+        expect(byPrefix.shown).toHaveLength(1);
+        expect(byPrefix.shown[0].rest).toBe(0);
+        expect(selectComments(t, { commentId: t[1].id }).shown[0].row.content).toBe('b');
+        expect(selectComments(t, { commentId: '99999999' }).error).toMatch(/No comment with id/);
+        expect(selectComments(t, { commentId: '0000' }).error).toMatch(/at least 8/);
+        const twins = [{ ...t[0], id: 'abcdef01-1' }, { ...t[1], id: 'abcdef01-2' }];
+        expect(selectComments(twins, { commentId: 'abcdef01' }).error).toMatch(/matches 2 comments/);
+    });
+    it('cuts at a word boundary and never inside a multi-byte character', () => {
+        const cut = shortenComment(`${'x'.repeat(295)} ${'y'.repeat(40)}`, 300);
+        expect(cut.excerpt).toBe('x'.repeat(295));
+        const umlauts = shortenComment('ä'.repeat(500), 300);
+        expect(Array.from(umlauts.excerpt)).toHaveLength(300);
+        expect(umlauts.rest).toBe(200);
+        expect(shortenComment('short', 300)).toEqual({ excerpt: 'short', rest: 0 });
+    });
+    it('orboto_get_ticket prints the shortened thread with the pointer and honours commentId', async () => {
+        const rows = thread([words('old', 120), 'b', 'c', 'd']);
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+        const route = (url) => {
+            if (url.includes('/comments'))
+                return { items: rows, nextCursor: null };
+            if (url.includes('/tickets?parentTicketId'))
+                return { items: [], nextCursor: null };
+            if (url.endsWith('/attachments'))
+                return [];
+            if (url.includes('/projects/by-key/'))
+                return { id: 'p1', key: 'ACME' };
+            return { id: 't1', projectId: 'p1', ticketKey: 'ACME-6', title: 'X', status: 'TODO', statusName: 'To Do', type: 'task', priority: 'normal', commentCount: 4 };
+        };
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => ({
+            ok: true, status: 200, statusText: 'OK', json: async () => route(url.toString()), text: async () => '',
+        }));
+        const res = await makeGetTicketHandler(client)({ ticketKey: 'ACME-6', include: ['comments'] });
+        const text = res.content[0].text;
+        expect(text).toContain('## Comments (4, newest first; the 3 newest in full, full: true prints all)');
+        expect(text).toContain('more characters: orboto_get_ticket { ticketKey: "ACME-6", commentId: "00000001-aaaa-4000-8000-000000000000" }');
+        expect(text).not.toContain('old119');
+        const one = await makeGetTicketHandler(client)({ ticketKey: 'ACME-6', commentId: '00000001' });
+        expect(one.content[0].text).toContain('old119');
+        const missing = await makeGetTicketHandler(client)({ ticketKey: 'ACME-6', commentId: 'ffffffff' });
+        expect(missing.isError).toBe(true);
+    });
+});

package/dist/tools/get-ticket.js

@@ -6,34 +6,34 @@ import { specReleaseInfo } from './shared.js';
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
+import { COMMENT_FULL_COUNT, fetchThread, selectComments } from './comment-thread.js';
 import { formatDependencySummary, resolveTicketByKey } from './shared.js';
-const COMMENT_PAGE_SIZE = 50;
 export const getTicketToolConfig = {
     title: 'Get ticket details',
-    description: 'Return a ticket\'s decision card: description, status, priority, milestone, assignees, labels, dates, estimate/logged time, checklist progress, parent + sub-ticket count, the OPEN dependency edges in both directions ("Blocked by" / "Blocks", keys + statuses - the full graph stays on orboto_list_ticket_dependencies) - plus COUNTS for everything omitted (commentCount, gitActivityCount, attachmentCount, childCount). Full blocks are opt-in via `include` (ORB-1698): pass e.g. include: ["comments"] to get the comment bodies, ["git","attachments","children","raci","checklistItems"] likewise. Input is the ticket key like "ACME-42".',
+    description: 'A ticket\'s decision card: description, status, priority, milestone, assignees, labels, dates, checklist progress, parent, open dependency edges and COUNTS of what is omitted (`include` opts blocks in). Comments: newest first, 3 newest in full, older shortened; `full` all, `commentId` one. Input: ticket key like "ACME-42".',
     inputSchema: z.object({
-        ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
+        ticketKey: z.string().min(3).describe('Key like "ACME-42".'),
         include: z.array(z.enum(['comments', 'git', 'attachments', 'children', 'raci', 'checklistItems']))
             .optional()
-            .describe('Blocks to inline in full. Default: none (counts only).'),
+            .describe('Blocks to inline.'),
+        full: z.boolean().optional().describe('Comments in full.'),
+        commentId: z.string().optional().describe('One comment (id or prefix).'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
 export function makeGetTicketHandler(client) {
-    return async ({ ticketKey, include }) => {
+    return async ({ ticketKey, include, full: fullComments, commentId }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
-        const inc = new Set(include ?? []);
+        const inc = new Set(commentId ? [...(include ?? []), 'comments'] : (include ?? []));
         const parentId = ticket.parentTicketId ?? null;
-        const [enriched, parent, childrenPage, attachments, commentsPage, checklists, gitActivity] = await Promise.all([
+        const [enriched, parent, childrenPage, attachments, thread, checklists, gitActivity] = await Promise.all([
             client.get(`/projects/${ticket.projectId}/tickets/${ticket.id}`).catch(swallow404(null)),
             parentId
                 ? client.get(`/projects/${ticket.projectId}/tickets/${parentId}`).catch(swallow404(null))
                 : Promise.resolve(null),
             client.get(`/projects/${ticket.projectId}/tickets?parentTicketId=${ticket.id}&limit=50`).catch(swallow404({ items: [], nextCursor: null })),
             client.get(`/tickets/${ticket.id}/attachments`).catch(swallow404([])),
-            inc.has('comments')
-                ? client.get(`/tickets/${ticket.id}/comments?limit=${COMMENT_PAGE_SIZE}`).catch(swallow404({ items: [], nextCursor: null }))
-                : Promise.resolve({ items: [], nextCursor: null }),
+            inc.has('comments') ? fetchThread(client, ticket.id) : Promise.resolve([]),
             inc.has('checklistItems')
                 ? client.get(`/tickets/${ticket.id}/checklists`).catch(swallow404([]))
                 : Promise.resolve([]),
@@ -41,11 +41,14 @@ export function makeGetTicketHandler(client) {
                 ? client.get(`/tickets/${ticket.id}/git-activity`).catch(swallow404([]))
                 : Promise.resolve([]),
         ]);
-        const comments = commentsPage.items;
-        const hasMoreComments = !!commentsPage.nextCursor;
+        const selected = selectComments(thread, { full: fullComments, commentId });
+        if (selected.error)
+            return { isError: true, content: [{ type: 'text', text: selected.error }] };
+        const comments = selected.shown;
+        const commentTotal = thread.length;
         const children = childrenPage.items;
         const full = enriched ?? ticket;
-        const commentCount = full.commentCount ?? (inc.has('comments') ? comments.length : 0);
+        const commentCount = full.commentCount ?? (inc.has('comments') ? commentTotal : 0);
         const gitCount = full.gitActivityCount ?? (inc.has('git') ? gitActivity.length : 0);
         const omitted = [];
         if (!inc.has('comments') && commentCount > 0)
@@ -62,7 +65,7 @@ export function makeGetTicketHandler(client) {
             ? `Omitted blocks: ${omitted.join(', ')}. Re-call orboto_get_ticket with include: ["comments"|"git"|"attachments"|"children"|"raci"|"checklistItems"] for the ones you need.`
             : undefined;
         return {
-            content: [{ type: 'text', text: formatTicket(full, inc, comments, hasMoreComments, checklists, gitActivity, parent, children, attachments, includeHint) }],
+            content: [{ type: 'text', text: formatTicket(full, inc, comments, commentTotal, ticketKey, checklists, gitActivity, parent, children, attachments, includeHint) }],
             structuredContent: {
                 id: full.id,
                 key: full.ticketKey,
@@ -119,15 +122,18 @@ export function makeGetTicketHandler(client) {
                 checklistProgress: full.checklistProgress ?? { done: 0, total: 0 },
                 ...(includeHint ? { includeHint } : {}),
                 ...(inc.has('comments') ? {
-                    comments: comments.map((c) => ({
-                        id: c.id, // ORB-1285 - needed to target a comment for edit/delete
+                    comments: comments.map(({ row: c, excerpt, length, rest }) => ({
+                        id: c.id,
                         author: c.userName ?? null,
-                        body: c.content,
+                        body: excerpt,
+                        bodyLength: length,
+                        ...(rest > 0 ? { bodyTruncated: true } : {}),
                         createdAt: c.createdAt,
                         editedAt: c.editedAt ?? null,
                         isInternal: c.isInternal,
                     })),
-                    commentsHasMore: hasMoreComments,
+                    commentTotal,
+                    commentsHasMore: false,
                 } : {}),
                 ...(inc.has('checklistItems') ? {
                     checklists: checklists.map((cl) => ({
@@ -183,7 +189,7 @@ function dependencyEdge(e) {
         ...(e.external ? { external: true } : {}),
     };
 }
-function formatTicket(ticket, inc, comments, hasMoreComments, checklists, gitActivity, parent, children, attachments, includeHint) {
+function formatTicket(ticket, inc, comments, commentTotal, ticketKey, checklists, gitActivity, parent, children, attachments, includeHint) {
     const header = [
         `[${ticket.ticketKey}] ${ticket.title}`,
         `Status: ${ticket.statusName ?? ticket.status}  Priority: ${ticket.priority}  Type: ${ticket.type}`,
@@ -214,6 +220,7 @@ function formatTicket(ticket, inc, comments, hasMoreComments, checklists, gitAct
         ticket.labels && ticket.labels.length > 0
             ? `Labels: ${ticket.labels.map((l) => l.name).join(', ')}`
             : null,
+        ticket.branchName ? `Branch: ${ticket.branchName}` : null,
         ticket.webUrl ? `Link: ${ticket.webUrl}` : null,
         formatDependencySummary('Blocked by', ticket.blockedByOpenCount, ticket.blockedByOpen),
         formatDependencySummary('Blocks', ticket.blocksOpenCount, ticket.blocksOpen),
@@ -249,12 +256,13 @@ function formatTicket(ticket, inc, comments, hasMoreComments, checklists, gitAct
         commentLines.push('', `Comments: ${ticket.commentCount}`);
     }
     if (inc.has('comments') && comments.length > 0) {
-        const headerLine = hasMoreComments
-            ? `## Comments (${comments.length} shown, more in the UI)`
-            : `## Comments (${comments.length})`;
-        commentLines.push('', headerLine);
-        for (const c of comments) {
-            commentLines.push(`**${c.userName ?? '(unknown author)'}** - ${c.createdAt}${c.isInternal ? ' [internal]' : ''}`, c.content, '');
+        const shortened = comments.some((c) => c.rest > 0);
+        commentLines.push('', `## Comments (${commentTotal}, newest first${shortened ? `; the ${COMMENT_FULL_COUNT} newest in full, full: true prints all` : ''})`);
+        for (const { row: c, excerpt, length, rest } of comments) {
+            commentLines.push(`**${c.userName ?? '(unknown author)'}** - ${c.createdAt}${c.isInternal ? ' [internal]' : ''} - ${length} chars - ${c.id}`, excerpt);
+            if (rest > 0)
+                commentLines.push(`... ${rest} more characters: orboto_get_ticket { ticketKey: "${ticketKey}", commentId: "${c.id}" }`);
+            commentLines.push('');
         }
     }
     const gitLines = [];

package/dist/tools/list-tickets.js

@@ -13,32 +13,36 @@ import { resolveProjectByKey, resolveTicketByKey, ticketLine, agentTicketListRow
 import { resolveMilestoneByNameOrId } from './milestones.js';
 export const listTicketsToolConfig = {
     title: 'List tickets',
-    description: 'List tickets in a project, optionally filtered by status category, milestone name, or assignee email. Set unscheduled=true for the product backlog (everything not planned into a milestone yet). Returns up to 50 tickets per call.',
+    description: 'List tickets in a project, filtered by status category, milestone or assignee email. unscheduled=true = the backlog (no milestone yet). Up to 50 per call.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
         specState: TicketSpecStateSchema.optional(),
         statusCategory: z
             .enum(['todo', 'in_progress', 'in_review', 'done', 'wont_fix'])
             .optional()
-            .describe('Filter to one workflow category. Omit for all.'),
+            .describe('One workflow category. Omit for all.'),
+        open: z
+            .boolean()
+            .optional()
+            .describe('true = only todo, in_progress, in_review. Not with statusCategory.'),
         milestone: z
             .string()
             .optional()
-            .describe('Key (ORB-M3), name, or UUID. Omit for all, backlog included.'),
+            .describe('Key (ORB-M3), name or UUID.'),
         unscheduled: z
             .boolean()
             .optional()
-            .describe('true = only the backlog: tickets with no milestone. Cannot be combined with `milestone`.'),
+            .describe('true = only tickets with no milestone. Not with `milestone`.'),
         assigneeEmail: z
             .string()
             .optional()
-            .describe('Project-member email. Omit for all, unassigned included.'),
+            .describe('Project-member email.'),
         parentTicketKey: z
             .string()
             .optional()
             .describe('Only children of this ticket - walks an epic.'),
         limit: z.number().int().min(1).max(50).default(25).describe('Max rows to return.'),
-        verbose: z.boolean().default(false).describe('true = full rows; default is the decision fields only.'),
+        verbose: z.boolean().default(false).describe('true = full rows.'),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -51,6 +55,11 @@ export function makeListTicketsHandler(client) {
             qs.set('specState', input.specState);
         if (input.statusCategory)
             qs.set('statusCategory', input.statusCategory);
+        if (input.open && input.statusCategory) {
+            throw new Error('Pass either `open` or `statusCategory`, not both.');
+        }
+        if (input.open)
+            qs.set('open', 'true');
         if (input.unscheduled && input.milestone) {
             throw new Error('Pass either `milestone` or `unscheduled: true`, not both.');
         }

package/dist/tools/phase-b-tools.test.js

@@ -256,7 +256,7 @@ describe('orboto_get_ticket', () => {
         expect(size).toBeLessThan(4000);
         expect(res.structuredContent.commentCount).toBe(34);
     });
-    it('include: ["comments"] restores cursor-paged bodies exactly as before', async () => {
+    it('include: ["comments"] returns the thread newest first with the body length', async () => {
         const calls = stub([
             { json: PROJ },
             { json: { id: 't1', projectId: 'p1', ticketKey: 'ACME-6', title: 'X', status: 'TODO', gitActivityCount: 0, parentTicketId: null } },
@@ -266,7 +266,7 @@ describe('orboto_get_ticket', () => {
             {
                 json: {
                     items: [{ id: 'c1', ticketId: 't1', userId: 'u1', content: 'first thought', isInternal: false, createdAt: 'now', userName: 'Ada' }],
-                    nextCursor: 'next-page-token',
+                    nextCursor: null,
                 },
             },
         ]);
@@ -276,12 +276,13 @@ describe('orboto_get_ticket', () => {
         expect(sc.comments[0]).toEqual({
             id: 'c1', // ORB-1285 - comment id is surfaced for edit/delete targeting
             body: 'first thought',
+            bodyLength: 13,
             author: 'Ada',
             createdAt: 'now',
             editedAt: null,
             isInternal: false,
         });
-        expect(sc.commentsHasMore).toBe(true);
+        expect(sc.commentTotal).toBe(1);
         expect(sc.parentTicket).toBeNull();
     });
     it('surfaces waitingForGitIngestion in the header and structured content', async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.218.0",
+  "version": "0.219.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",