@opsee/mcp-server 0.9.31 → 0.9.33

package/src/utils/format/blocknote.ts

@@ -0,0 +1,115 @@
+// ---------------------------------------------------------------------------
+// BlockNote JSON → Markdown
+// ---------------------------------------------------------------------------
+
+// `strike` is the key the BlockNote default schema uses, and it is what both Go
+// writers persist (backend/service/task.go parseInlineMarkdown and
+// orchestrator/internal/util/blocknote.go). `strikethrough` is accepted too so a
+// payload using the long spelling is not silently dropped.
+type BNInlineStyle = {
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  strike?: boolean;
+  strikethrough?: boolean;
+  code?: boolean;
+};
+type BNTextContent = { type: "text"; text: string; styles?: BNInlineStyle };
+type BNLinkContent = { type: "link"; href: string; content: BNTextContent[] };
+type BNInlineContent = BNTextContent | BNLinkContent;
+
+interface BNBlock {
+  type: string;
+  props?: Record<string, unknown>;
+  content?: BNInlineContent[];
+  children?: BNBlock[];
+}
+
+function renderInline(content: BNInlineContent[]): string {
+  return content.map((node) => {
+    if (node.type === "link") {
+      const inner = renderInline(node.content ?? []);
+      return `[${inner}](${node.href})`;
+    }
+    // text node
+    const t = node as BNTextContent;
+    let s = t.text ?? "";
+    if (t.styles?.code) s = `\`${s}\``;
+    if (t.styles?.bold) s = `**${s}**`;
+    if (t.styles?.italic) s = `*${s}*`;
+    // Struck-through text usually means "decided against this". Dropping the
+    // markers would present an abandoned plan item as a live one.
+    if (t.styles?.strike || t.styles?.strikethrough) s = `~~${s}~~`;
+    if (t.styles?.underline) s = `<u>${s}</u>`;
+    return s;
+  }).join("");
+}
+
+function renderBlock(block: BNBlock, indent: string): string[] {
+  const lines: string[] = [];
+  const inline = renderInline(block.content ?? []);
+
+  switch (block.type) {
+    case "heading": {
+      const level = (block.props?.level as number) || 1;
+      const prefix = "#".repeat(Math.min(Math.max(level, 1), 3));
+      lines.push(`${indent}${prefix} ${inline}`);
+      break;
+    }
+    case "bulletListItem":
+      lines.push(`${indent}- ${inline}`);
+      break;
+    case "numberedListItem":
+      lines.push(`${indent}1. ${inline}`);
+      break;
+    case "checkListItem": {
+      const checked = block.props?.checked ? "x" : " ";
+      lines.push(`${indent}- [${checked}] ${inline}`);
+      break;
+    }
+    case "codeBlock": {
+      const lang = (block.props?.language as string) || "";
+      lines.push(`${indent}\`\`\`${lang}`);
+      // A code block's text is one node containing newlines. Indent every line,
+      // not just the first, or the rest escapes the list item it is nested in.
+      for (const body of inline.split("\n")) lines.push(`${indent}${body}`);
+      lines.push(`${indent}\`\`\``);
+      break;
+    }
+    case "quote":
+      lines.push(`${indent}> ${inline}`);
+      break;
+    case "paragraph":
+    default:
+      lines.push(`${indent}${inline}`);
+      break;
+  }
+
+  if (block.children?.length) {
+    for (const child of block.children) {
+      lines.push(...renderBlock(child, indent + "  "));
+    }
+  }
+
+  return lines;
+}
+
+export function blockNoteToMarkdown(content: string): string {
+  try {
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed)) return content;
+
+    const mdLines: string[] = [];
+    for (let i = 0; i < parsed.length; i++) {
+      const block = parsed[i] as BNBlock;
+      if (typeof block !== "object" || block === null || !block.type) return content;
+      const blockLines = renderBlock(block, "");
+      mdLines.push(...blockLines);
+      // Separate top-level blocks with a blank line (except last)
+      if (i < parsed.length - 1) mdLines.push("");
+    }
+    return mdLines.join("\n");
+  } catch {
+    return content;
+  }
+}

package/src/utils/format/comment.ts

@@ -0,0 +1,19 @@
+import type { Comment } from "../../../gen/api/v1/models_pb.js";
+
+export function formatComment(c: Comment): string {
+  const lines = [];
+  const author = c.user?.fullName || `User #${c.userId}`;
+  const created = c.createdAt
+    ? new Date((typeof c.createdAt.seconds === "bigint" ? Number(c.createdAt.seconds) : c.createdAt.seconds) * 1000).toISOString()
+    : "—";
+  lines.push(`${author} @ ${created}${c.isInternal ? " [internal]" : ""}`);
+  lines.push(`  ${c.content}`);
+  lines.push(`  ID: ${c.id}`);
+  return lines.join("\n");
+}
+
+export function formatCommentList(comments: Comment[]): string {
+  if (comments.length === 0) return "No comments found.";
+  const header = `Found ${comments.length} comment(s):\n`;
+  return header + comments.map((c, i) => `${i + 1}. ${formatComment(c)}`).join("\n\n");
+}

package/src/utils/format/common.ts

@@ -0,0 +1,32 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+
+export function formatTimestamp(ts: { seconds: bigint | number } | undefined): string {
+  if (!ts) return "—";
+  const ms = typeof ts.seconds === "bigint" ? Number(ts.seconds) * 1000 : ts.seconds * 1000;
+  return new Date(ms).toISOString().split("T")[0];
+}
+
+export function formatError(error: unknown): string {
+  // Prefer the structured gRPC/Connect code over substring-matching the
+  // message: a backend error whose text embeds a task title containing "401"
+  // or "ECONNREFUSED" must not be misclassified as auth/network.
+  if (error instanceof ConnectError) {
+    if (error.code === Code.Unauthenticated) {
+      return "Not authenticated. Run `npx opsee-mcp login` to connect your Opsee account.";
+    }
+    if (error.code === Code.Unavailable) {
+      return `Could not reach Opsee API. Check your connection and OPSEE_API_URL. (${error.rawMessage})`;
+    }
+    return `[${Code[error.code]}] ${error.rawMessage}`;
+  }
+  if (error instanceof Error) {
+    // Raw transport errors before a Connect response carry a machine-readable
+    // code property (Node sets err.code); match on that, not the message text.
+    const code = (error as { code?: unknown }).code;
+    if (code === "ECONNREFUSED" || code === "ENOTFOUND") {
+      return `Could not reach Opsee API. Check your connection and OPSEE_API_URL. (${error.message})`;
+    }
+    return error.message;
+  }
+  return String(error);
+}

package/src/utils/format/cycle.ts

@@ -0,0 +1,19 @@
+import type { Cycle } from "../../../gen/api/v1/models_pb.js";
+
+export function formatCycle(c: Cycle): string {
+  const lines = [`${c.name}`];
+  if (c.description) lines.push(`  Description: ${c.description}`);
+  if (c.goal) lines.push(`  Goal: ${c.goal}`);
+  lines.push(`  Start: ${c.startDate} | End: ${c.endDate}`);
+  lines.push(`  Active: ${c.isActive ? "Yes" : "No"}`);
+  lines.push(`  ID: ${c.id}`);
+  return lines.join("\n");
+}
+
+export function formatCycleList(cycles: Cycle[]): string {
+  if (cycles.length === 0) return "No cycles found.";
+  const header = `Found ${cycles.length} cycle(s):\n`;
+  return (
+    header + cycles.map((c, i) => `${i + 1}. ${formatCycle(c)}`).join("\n\n")
+  );
+}

package/src/utils/format/docs.ts

@@ -0,0 +1,49 @@
+import type { DocPage, DocSpace } from "../../../gen/api/v1/models_pb.js";
+
+export function formatDocSpace(s: DocSpace): string {
+  const lines = [`${s.title}`];
+  if (s.description) lines.push(`  Description: ${s.description}`);
+  lines.push(`  Slug: ${s.slug}`);
+  lines.push(`  Default: ${s.isDefault ? "Yes" : "No"}`);
+  lines.push(`  ID: ${s.id}`);
+  return lines.join("\n");
+}
+
+export function formatDocSpaceList(spaces: DocSpace[]): string {
+  if (spaces.length === 0) return "No doc spaces found.";
+  const header = `Found ${spaces.length} doc space(s):\n`;
+  return (
+    header +
+    spaces.map((s, i) => `${i + 1}. ${formatDocSpace(s)}`).join("\n\n")
+  );
+}
+
+export function formatDocPage(p: DocPage): string {
+  const lines = [`${p.title}`];
+  lines.push(`  Slug: ${p.slug}`);
+  if (p.currentContent) {
+    const content =
+      p.currentContent.length > 500
+        ? p.currentContent.substring(0, 500) + "..."
+        : p.currentContent;
+    lines.push(`  Content: ${content}`);
+  }
+  lines.push(`  Version: ${p.currentVersionNumber}`);
+  if (p.createdByUser) lines.push(`  Author: ${p.createdByUser.fullName}`);
+  lines.push(`  ID: ${p.id}`);
+  return lines.join("\n");
+}
+
+export function formatDocPageList(pages: DocPage[]): string {
+  if (pages.length === 0) return "No doc pages found.";
+  const header = `Found ${pages.length} doc page(s):\n`;
+  return (
+    header +
+    pages
+      .map(
+        (p, i) =>
+          `${i + 1}. ${p.title} (slug: ${p.slug}, ID: ${p.id})`
+      )
+      .join("\n")
+  );
+}

package/src/utils/format/index.ts

@@ -0,0 +1,30 @@
+// Barrel for the per-entity formatters. Named re-exports rather than
+// `export *` so that helpers shared between the modules (formatTimestamp)
+// stay internal and the public surface only grows deliberately.
+
+export { formatError } from "./common.js";
+export { formatProject, formatProjectList } from "./project.js";
+export { formatTask, formatTaskList } from "./task.js";
+export { formatTaskDependency, formatTaskDependencyList } from "./task-dependency.js";
+export { formatCycle, formatCycleList } from "./cycle.js";
+export { formatDocSpace, formatDocSpaceList, formatDocPage, formatDocPageList } from "./docs.js";
+export {
+  formatMilestone,
+  formatMilestoneList,
+  formatMilestoneTask,
+  formatMilestoneTaskList,
+} from "./milestone.js";
+export { formatUser, formatUserList } from "./user.js";
+export { formatLabel, formatLabelList, formatTaskLabelList } from "./label.js";
+export { formatComment, formatCommentList } from "./comment.js";
+export { blockNoteToMarkdown } from "./blocknote.js";
+export {
+  WORKING_AGREEMENT,
+  formatInitiative,
+  formatInitiativeList,
+  formatInitiativeMemoryEntry,
+  formatInitiativeMemoryList,
+  formatInitiativeGraph,
+  formatInitiativeContext,
+  formatReconcileChangeset,
+} from "./initiative.js";

package/src/utils/format/initiative.ts

@@ -0,0 +1,210 @@
+import type { Comment, Initiative, InitiativeMemoryEntry, Task, TaskPullRequest } from "../../../gen/api/v1/models_pb.js";
+import type { InitiativeGraph, InitiativeSlice, ReconcileChangeset } from "../../../gen/api/v1/initiative_pb.js";
+import { blockNoteToMarkdown } from "./blocknote.js";
+import { formatComment } from "./comment.js";
+
+export function formatInitiative(ini: Initiative): string {
+  const lines = [`${ini.title}`];
+  if (ini.summary) lines.push(`  Summary: ${ini.summary}`);
+  lines.push(`  Status: ${ini.status}`);
+  lines.push(`  Anchor: ${ini.anchorType}${ini.anchorId ? ` #${ini.anchorId}` : ""}`);
+  if (ini.coreIdea) {
+    const md = blockNoteToMarkdown(ini.coreIdea);
+    const preview = md.length > 120 ? md.substring(0, 120) + "..." : md;
+    lines.push(`  Core Idea: ${preview}`);
+  }
+  const creator = ini.createdByUser?.fullName || `User #${ini.createdByUserId}`;
+  lines.push(`  Created by: ${creator}`);
+  lines.push(`  Project ID: ${ini.projectId}`);
+  lines.push(`  ID: ${ini.id} | UUID: ${ini.uuid}`);
+  return lines.join("\n");
+}
+
+export function formatInitiativeList(initiatives: Initiative[]): string {
+  if (initiatives.length === 0) return "No initiatives found.";
+  const header = `Found ${initiatives.length} initiative(s):\n`;
+  return header + initiatives.map((ini, i) => `${i + 1}. ${formatInitiative(ini)}`).join("\n\n");
+}
+
+export function formatInitiativeMemoryEntry(e: InitiativeMemoryEntry): string {
+  const lines = [];
+  const who = e.isSystem ? "system" : e.isAgent ? "agent" : (e.authorUser?.fullName || `User #${e.authorUserId}`);
+  const created = e.createdAt
+    ? new Date((typeof e.createdAt.seconds === "bigint" ? Number(e.createdAt.seconds) : e.createdAt.seconds) * 1000).toISOString()
+    : "—";
+  lines.push(`[${e.kind.toUpperCase()}] ${who} @ ${created}`);
+  lines.push(`  ${e.body}`);
+  if (e.sourceType && e.sourceType !== "none") {
+    const src = e.sourceId ? `${e.sourceType} #${e.sourceId}` : e.sourceType;
+    lines.push(`  Source: ${src}${e.sourceUrl ? ` (${e.sourceUrl})` : ""}`);
+  }
+  lines.push(`  ID: ${e.id}`);
+  return lines.join("\n");
+}
+
+export function formatInitiativeMemoryList(entries: InitiativeMemoryEntry[]): string {
+  if (entries.length === 0) return "No memory entries found.";
+  const header = `Found ${entries.length} memory entry(ies) (newest first):\n`;
+  return header + entries.map((e, i) => `${i + 1}. ${formatInitiativeMemoryEntry(e)}`).join("\n\n");
+}
+
+export function formatInitiativeGraph(graph: InitiativeGraph, taskMap?: Map<number, Task>): string {
+  const lines: string[] = [];
+
+  if (graph.tasks.length === 0) {
+    lines.push("No tasks in this initiative yet.");
+  } else {
+    lines.push(`Tasks (${graph.tasks.length}):`);
+    graph.tasks.forEach((t, i) => {
+      const status = t.boardColumn?.name || "Unknown";
+      const priority = t.taskPriority?.name || "None";
+      lines.push(`  ${i + 1}. [${t.identifier || `#${t.id}`}] ${t.title}`);
+      lines.push(`     Status: ${status} | Priority: ${priority} | ID: ${t.id}`);
+    });
+  }
+
+  if (graph.edges.length > 0) {
+    lines.push(`\nDependency Edges (${graph.edges.length}):`);
+    graph.edges.forEach((e) => {
+      const localMap = taskMap || new Map(graph.tasks.map(t => [t.id, t]));
+      const fromTask = localMap.get(e.fromTaskId);
+      const toTask = localMap.get(e.toTaskId);
+      const from = fromTask ? (fromTask.identifier || `#${e.fromTaskId}`) : `#${e.fromTaskId}`;
+      const to = toTask ? (toTask.identifier || `#${e.toTaskId}`) : `#${e.toTaskId}`;
+      lines.push(`  ${from} ${e.type.toUpperCase()} ${to}`);
+    });
+  }
+
+  if (graph.slices.length > 0) {
+    lines.push(`\nParallel Execution Batches:`);
+    const localMap = taskMap || new Map(graph.tasks.map(t => [t.id, t]));
+    const sorted = [...graph.slices].sort((a, b) => a.layer - b.layer);
+    sorted.forEach((slice: InitiativeSlice) => {
+      const taskLabels = slice.taskIds.map((id) => {
+        const t = localMap.get(id);
+        return t ? `[${t.identifier || `#${id}`}] ${t.title}` : `#${id}`;
+      });
+      lines.push(`  Parallel batch ${slice.layer}: ${taskLabels.join(", ")}`);
+    });
+  }
+
+  return lines.join("\n");
+}
+
+export const WORKING_AGREEMENT = [
+  "— Working agreement —",
+  "This Initiative is a shared brain that outlives this session. To keep it useful:",
+  "1. This context (core idea · task tree · memory · PRs) is the source of truth — read it before acting.",
+  "2. Log each decision / blocker / learning as it happens with opsee_add_initiative_memory (cite the task or PR).",
+  "3. When you finish a unit of work, call opsee_checkpoint to record what changed and what's next.",
+  "4. Link PRs to their tasks so they roll up here.",
+].join("\n");
+
+export function formatInitiativeContext(
+  initiative: Initiative,
+  graph: InitiativeGraph | undefined,
+  memoryEntries: InitiativeMemoryEntry[],
+  pullRequests: TaskPullRequest[],
+  comments: Comment[],
+): string {
+  const sections: string[] = [];
+
+  sections.push("=== INITIATIVE ===");
+  sections.push(formatInitiative(initiative));
+
+  if (initiative.coreIdea) {
+    sections.push("\n=== CORE IDEA ===");
+    const md = blockNoteToMarkdown(initiative.coreIdea);
+    const body = md.length > 2000
+      ? md.substring(0, 2000) + "\n... [truncated]"
+      : md;
+    sections.push(body);
+  }
+
+  if (graph) {
+    sections.push("\n=== EXECUTION GRAPH ===");
+    sections.push(formatInitiativeGraph(graph));
+  }
+
+  if (memoryEntries.length > 0) {
+    sections.push("\n=== MEMORY LOG (newest first) ===");
+    memoryEntries.forEach((e, i) => {
+      sections.push(`${i + 1}. ${formatInitiativeMemoryEntry(e)}`);
+    });
+  } else {
+    sections.push("\n=== MEMORY LOG ===");
+    sections.push("No memory entries yet.");
+  }
+
+  if (pullRequests.length > 0) {
+    sections.push("\n=== PULL REQUESTS ===");
+    pullRequests.forEach((pr, i) => {
+      const repo = pr.projectRepository?.repositoryFullName || `repo #${pr.projectRepositoryId}`;
+      sections.push(`  ${i + 1}. [${pr.state.toUpperCase()}] #${pr.prNumber} ${pr.title} (${repo})`);
+      sections.push(`     ${pr.url}`);
+    });
+  }
+
+  if (comments.length > 0) {
+    sections.push("\n=== DISCUSSION ===");
+    comments.forEach((c, i) => {
+      sections.push(`${i + 1}. ${formatComment(c)}`);
+    });
+  }
+
+  sections.push("\n" + WORKING_AGREEMENT);
+  return sections.join("\n");
+}
+
+export function formatReconcileChangeset(changeset: ReconcileChangeset): string {
+  const lines: string[] = [];
+
+  if (changeset.added.length > 0) {
+    lines.push(`Added (${changeset.added.length}):`);
+    changeset.added.forEach((t) => {
+      const id = t.identifier || (t.taskId ? `#${t.taskId}` : "(new)");
+      lines.push(`  + [${id}] ${t.title}`);
+    });
+  }
+
+  if (changeset.removed.length > 0) {
+    lines.push(`Removed — pristine, no work detected (${changeset.removed.length}):`);
+    changeset.removed.forEach((t) => {
+      const id = t.identifier || `#${t.taskId}`;
+      lines.push(`  − [${id}] ${t.title}`);
+    });
+  }
+
+  if (changeset.flagged.length > 0) {
+    lines.push(`Flagged — NOT removed, carries execution state (${changeset.flagged.length}):`);
+    lines.push("  These tasks have real work in progress and were left untouched.");
+    changeset.flagged.forEach((t) => {
+      const id = t.identifier || `#${t.taskId}`;
+      lines.push(`  ! [${id}] ${t.title} — flagged: ${t.reason}`);
+    });
+  }
+
+  if (changeset.edgesAdded.length > 0) {
+    lines.push(`Edges + (${changeset.edgesAdded.length}):`);
+    changeset.edgesAdded.forEach((e) => {
+      lines.push(`  + #${e.fromTaskId} ${e.type.toUpperCase()} #${e.toTaskId}`);
+    });
+  }
+
+  if (changeset.edgesRemoved.length > 0) {
+    lines.push(`Edges − (${changeset.edgesRemoved.length}):`);
+    changeset.edgesRemoved.forEach((e) => {
+      lines.push(`  − #${e.fromTaskId} ${e.type.toUpperCase()} #${e.toTaskId}`);
+    });
+  }
+
+  if (lines.length === 0) {
+    lines.push("No changes — the proposed plan matches the existing task tree.");
+  }
+
+  if (changeset.graph) {
+    lines.push("\n" + formatInitiativeGraph(changeset.graph));
+  }
+
+  return lines.join("\n");
+}

package/src/utils/format/label.ts

@@ -0,0 +1,26 @@
+import type { Label, TaskLabel } from "../../../gen/api/v1/models_pb.js";
+
+export function formatLabel(l: Label): string {
+  const lines = [`${l.name}`];
+  lines.push(`  Color: ${l.color}`);
+  if (l.description) lines.push(`  Description: ${l.description}`);
+  lines.push(`  Active: ${l.isActive ? "Yes" : "No"}`);
+  lines.push(`  Project ID: ${l.projectId}`);
+  lines.push(`  ID: ${l.id}`);
+  return lines.join("\n");
+}
+
+export function formatLabelList(labels: Label[]): string {
+  if (labels.length === 0) return "No labels found.";
+  const header = `Found ${labels.length} label(s):\n`;
+  return header + labels.map((l, i) => `${i + 1}. ${formatLabel(l)}`).join("\n\n");
+}
+
+export function formatTaskLabelList(taskLabels: TaskLabel[]): string {
+  if (taskLabels.length === 0) return "No labels attached to this task.";
+  const header = `Found ${taskLabels.length} label attachment(s):\n`;
+  return header + taskLabels.map((tl, i) => {
+    const labelName = tl.label?.name || `Label #${tl.labelId}`;
+    return `${i + 1}. ${labelName} (Label ID: ${tl.labelId} | TaskLabel ID: ${tl.id})`;
+  }).join("\n");
+}

package/src/utils/format/milestone.ts

@@ -0,0 +1,34 @@
+import type { Milestone, MilestoneTask } from "../../../gen/api/v1/models_pb.js";
+import { formatTimestamp } from "./common.js";
+
+export function formatMilestone(m: Milestone): string {
+  const lines = [`${m.name}`];
+  if (m.description) lines.push(`  Description: ${m.description}`);
+  lines.push(`  Status: ${m.status}`);
+  lines.push(`  Start: ${formatTimestamp(m.startDate)} | End: ${formatTimestamp(m.endDate)}`);
+  lines.push(`  Project ID: ${m.projectId}`);
+  lines.push(`  ID: ${m.id} | UUID: ${m.uuid}`);
+  return lines.join("\n");
+}
+
+export function formatMilestoneList(milestones: Milestone[]): string {
+  if (milestones.length === 0) return "No milestones found.";
+  const header = `Found ${milestones.length} milestone(s):\n`;
+  return header + milestones.map((m, i) => `${i + 1}. ${formatMilestone(m)}`).join("\n\n");
+}
+
+export function formatMilestoneTask(mt: MilestoneTask): string {
+  const t = mt.task;
+  if (!t) return `  Task ID: ${mt.taskId} (MilestoneTask ID: ${mt.id})`;
+  const parts = [`${t.identifier ? `${t.identifier} ` : ""}${t.title || `Task #${mt.taskId}`}`];
+  if (t.boardColumn?.name) parts.push(`  Status: ${t.boardColumn.name}`);
+  if (t.taskPriority?.name) parts.push(`  Priority: ${t.taskPriority.name}`);
+  parts.push(`  Task ID: ${mt.taskId} | MilestoneTask ID: ${mt.id}`);
+  return parts.join("\n");
+}
+
+export function formatMilestoneTaskList(milestoneTasks: MilestoneTask[]): string {
+  if (milestoneTasks.length === 0) return "No tasks attached to this milestone.";
+  const header = `Found ${milestoneTasks.length} task(s):\n`;
+  return header + milestoneTasks.map((mt, i) => `${i + 1}. ${formatMilestoneTask(mt)}`).join("\n\n");
+}

package/src/utils/format/project.ts

@@ -0,0 +1,21 @@
+import type { Project } from "../../../gen/api/v1/models_pb.js";
+
+export function formatProject(p: Project): string {
+  const lines = [
+    `${p.name} (${p.shortName})`,
+    `  Slug: ${p.slug}`,
+  ];
+  if (p.description) lines.push(`  Description: ${p.description}`);
+  lines.push(`  Active: ${p.isActive ? "Yes" : "No"}`);
+  lines.push(`  ID: ${p.id}`);
+  return lines.join("\n");
+}
+
+export function formatProjectList(projects: Project[]): string {
+  if (projects.length === 0) return "No projects found.";
+  const header = `Found ${projects.length} project(s):\n`;
+  return (
+    header +
+    projects.map((p, i) => `${i + 1}. ${formatProject(p)}`).join("\n\n")
+  );
+}

package/src/utils/format/task-dependency.ts

@@ -0,0 +1,25 @@
+import type { TaskDependency } from "../../../gen/api/v1/models_pb.js";
+import { TaskDependencyType } from "../../../gen/api/v1/models_pb.js";
+
+function taskDependencyTypeToString(t: TaskDependencyType): string {
+  switch (t) {
+    case TaskDependencyType.BLOCKS: return "BLOCKS";
+    case TaskDependencyType.BLOCKED_BY: return "BLOCKED_BY";
+    case TaskDependencyType.DUPLICATES: return "DUPLICATES";
+    case TaskDependencyType.RELATES_TO: return "RELATES_TO";
+    default: return "UNSPECIFIED";
+  }
+}
+
+export function formatTaskDependency(d: TaskDependency): string {
+  const typeStr = taskDependencyTypeToString(d.type);
+  const from = d.fromTask?.identifier || `Task #${d.fromTaskId}`;
+  const to = d.toTask?.identifier || `Task #${d.toTaskId}`;
+  return `${from} ${typeStr} ${to}\n  ID: ${d.id}`;
+}
+
+export function formatTaskDependencyList(deps: TaskDependency[]): string {
+  if (deps.length === 0) return "No task dependencies found.";
+  return `Found ${deps.length} dependency(ies):\n` +
+    deps.map((d, i) => `${i + 1}. ${formatTaskDependency(d)}`).join("\n\n");
+}

package/src/utils/format/task.ts

@@ -0,0 +1,81 @@
+import type { Task } from "../../../gen/api/v1/models_pb.js";
+
+export function formatTask(t: Task, opts: { full?: boolean } = {}): string {
+  const lines = [`[${t.identifier}] ${t.title}`];
+
+  const status = t.boardColumn?.name || "Unknown";
+  const priority = t.taskPriority?.name || "None";
+  const type = t.taskType?.name || "Unknown";
+  lines.push(`  Status: ${status} | Priority: ${priority} | Type: ${type}`);
+
+  const assignee = t.assignedUser?.fullName || "Unassigned";
+  const cycle = t.cycle?.name || "None";
+  const milestone = t.milestone?.name || "None";
+  lines.push(`  Assignee: ${assignee} | Cycle: ${cycle} | Milestone: ${milestone}`);
+
+  const parent = t.parentTaskId ? `#${t.parentTaskId}` : "—";
+  lines.push(`  Parent: ${parent}`);
+
+  if (t.storyPoints) lines.push(`  Story Points: ${t.storyPoints}`);
+  if (t.estimatedHours) lines.push(`  Estimated Hours: ${t.estimatedHours}`);
+
+  if (t.description) {
+    const desc =
+      !opts.full && t.description.length > 200
+        ? t.description.substring(0, 200) + "..."
+        : t.description;
+    lines.push(`  Description: ${desc}`);
+  }
+
+  if (t.dueDate) {
+    lines.push(`  Due: ${new Date(Number(t.dueDate.seconds) * 1000).toISOString().split("T")[0]}`);
+  }
+
+  lines.push(`  ID: ${t.id}`);
+  return lines.join("\n");
+}
+
+interface TaskListMeta {
+  totalCount?: number;
+  page?: number;
+  hasMore?: boolean;
+  nextPage?: number;
+}
+
+export function formatTaskList(tasks: Task[], projectNameOrMeta?: string | TaskListMeta): string {
+  if (tasks.length === 0) return "No tasks found.";
+
+  // Support both old signature (projectName: string) and new signature (meta: TaskListMeta)
+  const isMetaObject = projectNameOrMeta && typeof projectNameOrMeta === 'object';
+  const meta = isMetaObject ? projectNameOrMeta as TaskListMeta : undefined;
+  const projectName = !isMetaObject ? projectNameOrMeta as string | undefined : undefined;
+
+  const lines: string[] = [];
+
+  // Pagination metadata header
+  if (meta?.totalCount !== undefined) {
+    const pageInfo = meta.page ? `page ${meta.page}` : '';
+    const totalInfo = `${meta.totalCount} total`;
+    const header = [pageInfo, totalInfo].filter(Boolean).join(', ');
+    lines.push(`Tasks (${header}):`);
+    if (meta.hasMore && meta.nextPage) {
+      lines.push(`(Use page: ${meta.nextPage} to fetch the next 50 tasks)`);
+    }
+    lines.push('');
+  } else {
+    // Original header format
+    const header = projectName
+      ? `Found ${tasks.length} task(s) in project "${projectName}":\n`
+      : `Found ${tasks.length} task(s):\n`;
+    lines.push(header.trimEnd());
+    lines.push('');
+  }
+
+  // Task list
+  tasks.forEach((t, i) => {
+    lines.push(`${i + 1}. ${formatTask(t)}`);
+    lines.push('');
+  });
+
+  return lines.join('\n').trimEnd();
+}