@bli-cockpit/mcp 0.1.59 → 0.1.61

package/dist/usage-tools.js

@@ -1,11 +1,22 @@
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
-import { doorFailureText, errorResult, registrarFor, textResult, withSession } from "./tool-result.js";
+import { dataResult, doorFailureText, errorResult, registrarFor, withSession } from "./tool-result.js";
+// Both reads answer with `dataResult`: the text half used to carry only the
+// coverage sentence, so a Claude-family client (which shows the model the text
+// half alone) could say how many sessions were counted and never whose they
+// were or what they cost (BLI-10432).
+const WINDOW_BOUND = "<n>d (1 to 365), <n>h (1 to 8760), or an ISO timestamp";
 export function registerUsageTools(server, deps) {
     registrarFor(server)("usage_people", {
         title: "Read usage by person",
-        description: "Per-person Claude Code and Codex token usage, list-price equivalent, and extraction coverage.",
-        inputSchema: { minConfidence: z.enum(["high", "medium", "low"]).optional(), groupBy: z.enum(["repo", "task_type", "topic", "ticket"]).optional(), since: z.string().optional().describe("<n>d (1 to 365), <n>h (1 to 8760), or an ISO timestamp. Default 30d; invalid values return invalid_usage_window."), until: z.string().optional(), include_automated: z.boolean().optional() },
+        description: "Per-person Claude Code and Codex token usage, list-price equivalent (not actual spend), and extraction coverage, over a window (default the last 30 days). groupBy adds a per-person breakdown; groupBy topic or ticket lists the labels usage_sessions takes as subject or task.",
+        inputSchema: {
+            minConfidence: z.enum(["high", "medium", "low"]).optional().describe("With groupBy task_type or topic: only labels at or above this confidence."),
+            groupBy: z.enum(["repo", "task_type", "topic", "ticket"]).optional().describe("Break each person's usage down by repo, task type, topic or ticket."),
+            since: z.string().min(1).max(40).optional().describe(`${WINDOW_BOUND}. Default 30d; invalid values return invalid_usage_window.`),
+            until: z.string().min(1).max(40).optional().describe(`${WINDOW_BOUND}. Default now.`),
+            include_automated: z.boolean().optional().describe("Count automated (scripted, non-interactive) sessions too. Off by default."),
+        },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams({ since: String(args.since ?? "30d") });
         if (args.until)
@@ -32,15 +43,31 @@ export function registerUsageTools(server, deps) {
         const priceLabel = typeof response.body.api_list_price_equivalent_label === "string"
             ? ` ${response.body.api_list_price_equivalent_label}.`
             : "";
-        return textResult(`${coverage?.sessions_extracted ?? 0} of ${coverage?.sessions_observed ?? 0} sessions extracted.${why} ${coverage?.sessions_counted_at_upload ?? 0} of ${coverage?.sessions_observed ?? 0} sessions counted at upload, ${coverage?.sessions_counted_by_server ?? 0} by server backfill, ${coverage?.sessions_counted_by_ladder ?? 0} by the ladder.${args.groupBy === "task_type" ? ` ${coverage?.sessions_labelled ?? 0} of ${coverage?.sessions_observed ?? 0} sessions labelled by topic.` : ""}${priceLabel}`, response.body);
+        return dataResult(`${coverage?.sessions_extracted ?? 0} of ${coverage?.sessions_observed ?? 0} sessions extracted.${why} ${coverage?.sessions_counted_at_upload ?? 0} of ${coverage?.sessions_observed ?? 0} sessions counted at upload, ${coverage?.sessions_counted_by_server ?? 0} by server backfill, ${coverage?.sessions_counted_by_ladder ?? 0} by the ladder.${args.groupBy === "task_type" ? ` ${coverage?.sessions_labelled ?? 0} of ${coverage?.sessions_observed ?? 0} sessions labelled by topic.` : ""}${priceLabel}`, response.body);
     }));
     registrarFor(server)("usage_sessions", {
         title: "Read task or subject sessions",
-        description: "List task or subject sessions with titles, tokens and work types; read digest windows on demand with session.",
-        inputSchema: { task: z.string().regex(/^BLI-[0-9]+$/).optional(), subject: z.string().optional(), repo: z.string().optional(), since: z.string().optional(), until: z.string().optional(), include_automated: z.boolean().optional(), session: z.string().optional(), fromWindow: z.number().int().positive().optional() },
+        description: "The sessions behind one ticket or one topic: titles, tokens and work types. Name exactly one of task (a BLI-#### id) or subject (a TOPIC label, as usage_people with groupBy topic lists it; not a person). Or pass session (a session id) alone to read that session's digest windows, ten at a time from fromWindow. This read can take 25 seconds.",
+        inputSchema: {
+            task: z.string().regex(/^BLI-[0-9]+$/).optional().describe("A ticket id, e.g. BLI-4258: the sessions labelled with it."),
+            subject: z.string().min(1).max(300).optional().describe("A topic label exactly as usage_people groupBy topic prints it. Not a person or an email."),
+            repo: z.string().min(1).max(200).optional().describe("Only sessions in this repo label."),
+            person: z.string().min(1).max(64).optional().describe("Only this person's sessions, by user id (usage_people user_id)."),
+            subtopic: z.string().min(1).max(300).optional().describe("Only sessions with this subtopic label."),
+            since: z.string().min(1).max(40).optional().describe(`${WINDOW_BOUND}. Default 30d.`),
+            until: z.string().min(1).max(40).optional().describe(`${WINDOW_BOUND}. Default now.`),
+            include_automated: z.boolean().optional().describe("Count automated sessions too. Off by default."),
+            session: z.string().min(1).max(200).optional().describe("A session id: read its digest windows instead of listing sessions."),
+            fromWindow: z.number().int().min(1).optional().describe("With session: the first window number to read. Default 1."),
+        },
     }, async (args) => withSession(deps, async (session) => {
+        // The door answers a bare 400 `subject_and_valid_window_required` when
+        // neither is named; say what to pass instead of "Tower answered 400".
+        if (args.session === undefined && args.task === undefined && (typeof args.subject !== "string" || args.subject.trim() === "")) {
+            return errorResult("usage_sessions needs task (a BLI-#### id), subject (a topic label from usage_people groupBy topic) or session (a session id) (task_or_subject_required). Nothing was read.");
+        }
         const query = new URLSearchParams();
-        for (const key of ["task", "subject", "repo", "since", "until", "session", "fromWindow"])
+        for (const key of ["task", "subject", "repo", "person", "subtopic", "since", "until", "session", "fromWindow"])
             if (args[key] !== undefined)
                 query.set(key, String(args[key]));
         if (args.include_automated)
@@ -48,6 +75,11 @@ export function registerUsageTools(server, deps) {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/usage/sessions?${query}`);
         if (!response.ok)
             return errorResult(doorFailureText("usage_sessions", response));
-        return textResult("Subject sessions and requested digest windows.", response.body);
+        if (args.session !== undefined) {
+            const windows = Array.isArray(response.body.windows) ? response.body.windows.length : 0;
+            return dataResult(`${windows} digest window(s) of session ${String(args.session)}.`, response.body);
+        }
+        const sessions = Array.isArray(response.body.sessions) ? response.body.sessions.length : 0;
+        return dataResult(`${sessions} session(s) for ${args.task ? `task ${String(args.task)}` : `topic "${String(args.subject)}"`}.`, response.body);
     }));
 }

package/dist/work-tools.js

@@ -16,7 +16,7 @@
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
-import { doorFailureText, errorResult, registrarFor, textResult, withSession, } from "./tool-result.js";
+import { DEFAULT_LIST_LIMIT, doorFailureText, errorResult, moreNote, registrarFor, textResult, withSession, } from "./tool-result.js";
 /** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
 export const WORK_ISSUE_STATES = [
     "backlog",
@@ -26,6 +26,27 @@ export const WORK_ISSUE_STATES = [
     "done",
     "canceled",
 ];
+/** `/api/work/issues`' own ceiling, and the most a caller may ask for here. */
+const ISSUE_LIST_MAX = 1000;
+/**
+ * The fields `work_list_issues` promises. The door's row carries the whole
+ * description and a dozen bookkeeping columns; with no limit that was 1,000
+ * issues and 4.2 MB, 3.3 MB of it descriptions the tool said it never
+ * returned (BLI-10432). work_get_issue reads one issue in full.
+ */
+function issueListRow(row) {
+    return {
+        id: row.id,
+        identifier: row.identifier,
+        title: row.title,
+        state: row.state,
+        priority: row.priority ?? null,
+        assignee_id: row.assignee_id ?? null,
+        project_id: row.project_id ?? null,
+        parent_id: row.parent_id ?? null,
+        updated_at: row.updated_at ?? null,
+    };
+}
 /**
  * A row the Linear import could not give state names to says which it is.
  * Printing "(none) -> (none)" is honest and useless; naming the gap keeps
@@ -57,13 +78,15 @@ export function registerWorkTools(server, deps) {
     const register = registrarFor(server);
     register("work_list_issues", {
         title: "List Tower issues",
-        description: "Issues you may see, most recently updated first. Filter by state, assignee (\"me\", \"unassigned\", or a uuid) "
-            + "or project (name or uuid). Never a description — call work_get_issue for one issue's full text.",
+        description: "Issues you may see, most recently updated first: identifier, state, title, priority, assignee, project. "
+            + "Filter by state, assignee (\"me\", \"unassigned\", or a uuid) or project (name or uuid). "
+            + `Default ${DEFAULT_LIST_LIMIT} issues; the answer says when more exist. `
+            + "Never a description — call work_get_issue for one issue's full text.",
         inputSchema: {
-            state: z.enum(WORK_ISSUE_STATES).optional(),
+            state: z.enum(WORK_ISSUE_STATES).optional().describe("Only issues in this state."),
             assignee: z.string().min(1).max(100).optional().describe('"me", "unassigned", or a person\'s uuid.'),
             project: z.string().min(1).max(200).optional().describe("A project name or uuid."),
-            limit: z.number().int().min(1).max(1000).optional(),
+            limit: z.number().int().min(1).max(ISSUE_LIST_MAX).optional().describe(`At most this many issues. Default ${DEFAULT_LIST_LIMIT}.`),
         },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams();
@@ -71,8 +94,9 @@ export function registerWorkTools(server, deps) {
             query.set("state", String(args.state));
         if (args.assignee)
             query.set("assignee_id", String(args.assignee));
-        if (args.limit)
-            query.set("limit", String(args.limit));
+        // No limit named: one page plus one row, so "more exist" is read off
+        // the door rather than guessed from a full page.
+        query.set("limit", String(args.limit ?? DEFAULT_LIST_LIMIT + 1));
         if (args.project) {
             const resolved = await resolveProjectId(deps, session, String(args.project));
             if (resolved.status === "list_failed")
@@ -86,9 +110,14 @@ export function registerWorkTools(server, deps) {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues${suffix ? `?${suffix}` : ""}`);
         if (!response.ok)
             return errorResult(doorFailureText("work_list_issues", response));
-        const issues = (Array.isArray(response.body.issues) ? response.body.issues : []);
-        const lines = issues.map((issue) => `${issue.identifier}  ${issue.state}  ${issue.title}`).join("\n");
-        return textResult(`${issues.length} issue(s).${lines ? `\n${lines}` : ""}`, { issues });
+        const all = (Array.isArray(response.body.issues) ? response.body.issues : []);
+        const more = args.limit === undefined && all.length > DEFAULT_LIST_LIMIT;
+        const issues = more ? all.slice(0, DEFAULT_LIST_LIMIT) : all;
+        const lines = issues
+            .map((issue) => `${issue.identifier}  ${issue.state}  ${issue.title}`
+            + `  [p${issue.priority ?? 0}, assignee ${issue.assignee_id ?? "none"}, project ${issue.project_id ?? "none"}]`)
+            .join("\n");
+        return textResult(`${issues.length} issue(s).${moreNote(more, ISSUE_LIST_MAX)}${lines ? `\n${lines}` : ""}`, { issues: issues.map(issueListRow), more });
     }));
     register("work_get_issue", {
         title: "Read a Tower issue",
@@ -114,8 +143,8 @@ export function registerWorkTools(server, deps) {
         title: "File a Tower issue",
         description: "Files a new issue and returns the BLI-#### identifier it was given. Use this the way you would file a Linear ticket.",
         inputSchema: {
-            title: z.string().min(1).max(300),
-            description: z.string().max(200_000).optional(),
+            title: z.string().min(1).max(300).describe("The issue title."),
+            description: z.string().max(200_000).optional().describe("The issue body, markdown."),
             project: z.string().min(1).max(200).optional().describe("A project name or uuid."),
             priority: z.number().int().min(0).max(4).optional().describe("0 none, 1 urgent, 2 high, 3 medium, 4 low."),
             assignee: z.string().min(1).max(100).optional().describe('"me" or a person\'s uuid.'),
@@ -149,9 +178,9 @@ export function registerWorkTools(server, deps) {
             + "State does NOT move here — call work_move_issue, which records the move.",
         inputSchema: {
             id: ISSUE_REF,
-            title: z.string().min(1).max(300).optional(),
-            description: z.string().max(200_000).nullable().optional(),
-            priority: z.number().int().min(0).max(4).optional(),
+            title: z.string().min(1).max(300).optional().describe("A new title."),
+            description: z.string().max(200_000).nullable().optional().describe("The WHOLE new body, markdown; null clears it."),
+            priority: z.number().int().min(0).max(4).optional().describe("0 none, 1 urgent, 2 high, 3 medium, 4 low."),
             assignee: z.string().min(1).max(100).nullable().optional().describe('"me", a uuid, or null to unassign.'),
             project: z.string().min(1).max(200).optional().describe("A project name or uuid."),
         },
@@ -183,7 +212,7 @@ export function registerWorkTools(server, deps) {
         title: "Move a Tower issue",
         description: "Moves an issue to a new state and records the move in its history. This is how an issue's state changes; "
             + "there is no other door.",
-        inputSchema: { id: ISSUE_REF, state: z.enum(WORK_ISSUE_STATES) },
+        inputSchema: { id: ISSUE_REF, state: z.enum(WORK_ISSUE_STATES).describe("The state to move it to.") },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.id ?? "");
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/work/issues/${encodeURIComponent(ref)}/state`, {
@@ -197,7 +226,7 @@ export function registerWorkTools(server, deps) {
     register("work_comment_issue", {
         title: "Comment on a Tower issue",
         description: "Posts a comment. Comments are append-only — nothing here edits or deletes one.",
-        inputSchema: { id: ISSUE_REF, body_markdown: z.string().min(1).max(50_000) },
+        inputSchema: { id: ISSUE_REF, body_markdown: z.string().min(1).max(50_000).describe("The comment, markdown.") },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.id ?? "");
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/work/issues/${encodeURIComponent(ref)}/comments`, { body_markdown: args.body_markdown });
@@ -213,7 +242,7 @@ export function registerWorkTools(server, deps) {
             + "\"(none) -> (none)\".",
         inputSchema: {
             id: ISSUE_REF,
-            limit: z.number().int().min(1).max(500).optional(),
+            limit: z.number().int().min(1).max(500).optional().describe("At most this many changes."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.id ?? "");
@@ -232,7 +261,7 @@ export function registerWorkTools(server, deps) {
     register("work_list_projects", {
         title: "List Tower projects",
         description: "The projects issues are filed under. Use a project's name with work_list_issues or work_create_issue.",
-        inputSchema: { include_archived: z.boolean().optional() },
+        inputSchema: { include_archived: z.boolean().optional().describe("true: archived projects too.") },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/projects${args.include_archived ? "?include_archived=true" : ""}`);
         if (!response.ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "private": false,
   "description": "bli-tower: an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",