@bli-cockpit/mcp 0.1.0 → 0.1.1

package/dist/server.js

@@ -7,6 +7,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { registerDocsMsgTools } from "./docs-msg-tools.js";
+import { registerWorkTools } from "./work-tools.js";
 export const PACKAGE_NAME = "@bli-cockpit/mcp";
 export const PACKAGE_VERSION = "0.1.0";
 // ---- input schemas (Zod raw shapes) -----------------------------------------
@@ -370,5 +371,9 @@ export function createServer(deps) {
     // no `cockpit login` pairing yet still serves the three event tools; only a
     // docs/msg call on that machine fails, by name.
     registerDocsMsgTools(server, { fetchImpl: deps.fetchImpl });
+    // BLI-3716: `work_*` — the issue tracker, on the same device-token path as
+    // the docs/msg tools above, for the same reason: a coding session should
+    // file and move a Tower issue the way it files and moves a Linear one.
+    registerWorkTools(server, { fetchImpl: deps.fetchImpl });
     return server;
 }

package/dist/work-tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `work_*` MCP tools (BLI-3716) — Tower's issue tracker on the `bli-tower`
+ * server, over the same `/api/work/**` doors `cockpit issue` and the browser
+ * call, authenticated with this machine's collector device token.
+ *
+ * The point of this file, in one sentence: a Claude Code or Codex session
+ * should be able to file and move a TOWER issue exactly the way it files and
+ * moves a Linear one — no browser, no uuid archaeology, no second vocabulary.
+ * So every tool takes `BLI-####` wherever an issue is named (the SERVER
+ * resolves it, `lib/work/issue-ref.ts`), and `work_create_issue` answers with
+ * the identifier it minted.
+ *
+ * Same session discipline as `docs-msg-tools.ts`: the session is loaded fresh
+ * per call, so a machine with no `cockpit login` pairing still serves this
+ * server's other tools and only a `work_` call fails, by name.
+ */
+import { loadAgentDoorSession } from "./agent-door-session.js";
+import { type FetchImpl } from "./agent-door.js";
+export interface WorkDeps {
+    fetchImpl: FetchImpl;
+    /** Injectable for tests; defaults to reading `~/.config/bli-cockpit/session.json`. */
+    loadSession?: typeof loadAgentDoorSession;
+}
+/** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
+export declare const WORK_ISSUE_STATES: readonly ["backlog", "todo", "in_progress", "in_review", "done", "canceled"];
+export declare function registerWorkTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: WorkDeps): void;

package/dist/work-tools.js

@@ -0,0 +1,233 @@
+/**
+ * `work_*` MCP tools (BLI-3716) — Tower's issue tracker on the `bli-tower`
+ * server, over the same `/api/work/**` doors `cockpit issue` and the browser
+ * call, authenticated with this machine's collector device token.
+ *
+ * The point of this file, in one sentence: a Claude Code or Codex session
+ * should be able to file and move a TOWER issue exactly the way it files and
+ * moves a Linear one — no browser, no uuid archaeology, no second vocabulary.
+ * So every tool takes `BLI-####` wherever an issue is named (the SERVER
+ * resolves it, `lib/work/issue-ref.ts`), and `work_create_issue` answers with
+ * the identifier it minted.
+ *
+ * Same session discipline as `docs-msg-tools.ts`: the session is loaded fresh
+ * per call, so a machine with no `cockpit login` pairing still serves this
+ * server's other tools and only a `work_` call fails, by name.
+ */
+import { z } from "zod";
+import { loadAgentDoorSession } from "./agent-door-session.js";
+import { callAgentDoor } from "./agent-door.js";
+/** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
+export const WORK_ISSUE_STATES = [
+    "backlog",
+    "todo",
+    "in_progress",
+    "in_review",
+    "done",
+    "canceled",
+];
+function textResult(text, structured) {
+    return { content: [{ type: "text", text }], ...(structured ? { structuredContent: structured } : {}) };
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+async function withSession(deps, run) {
+    const loadSession = deps.loadSession ?? loadAgentDoorSession;
+    const loaded = loadSession();
+    if (!loaded.ok)
+        return errorResult(`This machine is not paired with Tower (${loaded.reason}). ${loaded.message}`);
+    return run(loaded.session);
+}
+function doorFailureText(door, response) {
+    if (response.transportError) {
+        return `Tower could not be reached for ${door} (${response.transportError}). Nothing was read or written.`;
+    }
+    const reason = typeof response.body.reason === "string"
+        ? response.body.reason
+        : typeof response.body.error === "string"
+            ? response.body.error
+            : "unknown_error";
+    const message = typeof response.body.message === "string" ? response.body.message : `Tower answered ${response.status}.`;
+    return `Tower refused ${door} (${reason}): ${message}`;
+}
+/** A project id from a project NAME or a uuid — exact after case-folding, never fuzzy. */
+async function resolveProjectId(deps, session, ref) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/work/projects?include_archived=true");
+    if (!response.ok)
+        return { status: "list_failed", text: doorFailureText("work_list_projects", response) };
+    const projects = (Array.isArray(response.body.projects) ? response.body.projects : []);
+    const wanted = ref.toLowerCase();
+    const match = projects.find((project) => project.id === ref || project.name.toLowerCase() === wanted);
+    return match ? { status: "ok", id: match.id } : { status: "not_found" };
+}
+const ISSUE_REF = z
+    .string()
+    .min(1)
+    .max(200)
+    .describe("A BLI-#### identifier (e.g. BLI-3654) or an issue's uuid. Both work.");
+export function registerWorkTools(server, deps) {
+    const register = server.registerTool.bind(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.",
+        inputSchema: {
+            state: z.enum(WORK_ISSUE_STATES).optional(),
+            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(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const query = new URLSearchParams();
+        if (args.state)
+            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));
+        if (args.project) {
+            const resolved = await resolveProjectId(deps, session, String(args.project));
+            if (resolved.status === "list_failed")
+                return errorResult(resolved.text);
+            if (resolved.status === "not_found") {
+                return errorResult(`No project matches "${String(args.project)}" — call work_list_projects for the names.`);
+            }
+            query.set("project_id", resolved.id);
+        }
+        const suffix = query.toString();
+        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 });
+    }));
+    register("work_get_issue", {
+        title: "Read a Tower issue",
+        description: "One issue's title, state, priority, assignee, description and every comment on it.",
+        inputSchema: { id: ISSUE_REF },
+    }, async (args) => withSession(deps, async (session) => {
+        const ref = String(args.id ?? "");
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues/${encodeURIComponent(ref)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("work_get_issue", response));
+        const issue = response.body.issue;
+        // A comment read that fails does not lose the issue already in hand.
+        const commentsResponse = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/work/issues/${encodeURIComponent(issue?.id ?? ref)}/comments`);
+        const comments = commentsResponse.ok ? (commentsResponse.body.comments ?? []) : [];
+        const commentText = comments
+            .map((comment) => `[${comment.created_at ?? ""}] ${comment.body_markdown ?? ""}`)
+            .join("\n\n");
+        return textResult(`${issue?.identifier ?? ref} ${issue?.title ?? ""} (${issue?.state ?? "?"})\n\n${issue?.description ?? "(no description)"}`
+            + (commentText ? `\n\n--- comments ---\n${commentText}` : "")
+            + (commentsResponse.ok ? "" : "\n\n(comments could not be read on this call)"), { issue, comments, ...(commentsResponse.ok ? {} : { comments_unread: true }) });
+    }));
+    register("work_create_issue", {
+        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(),
+            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.'),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        let projectId;
+        if (args.project) {
+            const resolved = await resolveProjectId(deps, session, String(args.project));
+            if (resolved.status === "list_failed")
+                return errorResult(resolved.text);
+            if (resolved.status === "not_found") {
+                return errorResult(`No project matches "${String(args.project)}" — call work_list_projects for the names.`);
+            }
+            projectId = resolved.id;
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/work/issues", {
+            title: args.title,
+            ...(args.description === undefined ? {} : { description: args.description }),
+            ...(projectId ? { project_id: projectId } : {}),
+            ...(args.priority === undefined ? {} : { priority: args.priority }),
+            ...(args.assignee ? { assignee_id: args.assignee } : {}),
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("work_create_issue", response));
+        const issue = response.body.issue;
+        return textResult(`Filed ${issue?.identifier ?? ""} — ${issue?.title ?? ""} (${issue?.id ?? ""}).`, { issue });
+    }));
+    register("work_update_issue", {
+        title: "Update a Tower issue",
+        description: "Changes an issue's title, description, priority, assignee or project. Only the fields you pass change. "
+            + "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(),
+            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."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const ref = String(args.id ?? "");
+        let projectId;
+        if (args.project) {
+            const resolved = await resolveProjectId(deps, session, String(args.project));
+            if (resolved.status === "list_failed")
+                return errorResult(resolved.text);
+            if (resolved.status === "not_found") {
+                return errorResult(`No project matches "${String(args.project)}" — call work_list_projects for the names.`);
+            }
+            projectId = resolved.id;
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "PATCH", `/api/work/issues/${encodeURIComponent(ref)}`, {
+            ...(args.title !== undefined ? { title: args.title } : {}),
+            ...(args.description !== undefined ? { description: args.description } : {}),
+            ...(args.priority !== undefined ? { priority: args.priority } : {}),
+            ...(args.assignee !== undefined ? { assignee_id: args.assignee } : {}),
+            ...(projectId ? { project_id: projectId } : {}),
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("work_update_issue", response));
+        const issue = response.body.issue;
+        return textResult(`Updated ${issue?.identifier ?? ref} — ${issue?.title ?? ""}.`, { issue });
+    }));
+    register("work_move_issue", {
+        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) },
+    }, 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`, {
+            state: args.state,
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("work_move_issue", response));
+        const issue = response.body.issue;
+        return textResult(`${issue?.identifier ?? ref} is now ${issue?.state ?? String(args.state)}.`, { issue });
+    }));
+    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) },
+    }, 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 });
+        if (!response.ok)
+            return errorResult(doorFailureText("work_comment_issue", response));
+        const comment = response.body.comment;
+        return textResult(`Commented on ${ref} (${comment?.id ?? "?"}).`, { comment });
+    }));
+    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() },
+    }, 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)
+            return errorResult(doorFailureText("work_list_projects", response));
+        const projects = (Array.isArray(response.body.projects) ? response.body.projects : []);
+        return textResult(`${projects.length} project(s).${projects.length ? `\n${projects.map((p) => `${p.name}  (${p.id})`).join("\n")}` : ""}`, { projects });
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "bli-tower — an MCP server over BLI Cockpit's docs/msg agent doors (docs_*, msg_*), plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",