@iloom/cli 0.2.0 → 0.3.1

package/dist/mcp/issue-management-server.js

@@ -0,0 +1,934 @@
+#!/usr/bin/env node
+
+// src/mcp/issue-management-server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/utils/github.ts
+import { execa } from "execa";
+
+// src/utils/logger.ts
+import chalk, { Chalk } from "chalk";
+var stdoutChalk = new Chalk({ level: chalk.level });
+var stderrChalk = new Chalk({ level: chalk.level });
+function formatMessage(message, ...args) {
+  const formattedArgs = args.map(
+    (arg) => typeof arg === "object" ? JSON.stringify(arg, null, 2) : String(arg)
+  );
+  return formattedArgs.length > 0 ? `${message} ${formattedArgs.join(" ")}` : message;
+}
+function formatWithEmoji(message, emoji, colorFn) {
+  if (message.trim()) {
+    return colorFn(`${emoji} ${message}`);
+  } else {
+    return "";
+  }
+}
+var globalDebugEnabled = false;
+var logger = {
+  info: (message, ...args) => {
+    const formatted = formatMessage(message, ...args);
+    const output = formatWithEmoji(formatted, "\u{1F5C2}\uFE0F ", stdoutChalk.blue);
+    console.log(output);
+  },
+  success: (message, ...args) => {
+    const formatted = formatMessage(message, ...args);
+    const output = formatWithEmoji(formatted, "\u2705", stdoutChalk.green);
+    console.log(output);
+  },
+  warn: (message, ...args) => {
+    const formatted = formatMessage(message, ...args);
+    const output = formatWithEmoji(formatted, "\u26A0\uFE0F ", stderrChalk.yellow);
+    console.error(output);
+  },
+  error: (message, ...args) => {
+    const formatted = formatMessage(message, ...args);
+    const output = formatWithEmoji(formatted, "\u274C", stderrChalk.red);
+    console.error(output);
+  },
+  debug: (message, ...args) => {
+    if (globalDebugEnabled) {
+      const formatted = formatMessage(message, ...args);
+      const output = formatWithEmoji(formatted, "\u{1F50D}", stdoutChalk.gray);
+      console.log(output);
+    }
+  },
+  setDebug: (enabled) => {
+    globalDebugEnabled = enabled;
+  },
+  isDebugEnabled: () => {
+    return globalDebugEnabled;
+  }
+};
+
+// src/utils/github.ts
+async function executeGhCommand(args, options) {
+  const result = await execa("gh", args, {
+    cwd: (options == null ? void 0 : options.cwd) ?? process.cwd(),
+    timeout: (options == null ? void 0 : options.timeout) ?? 3e4,
+    encoding: "utf8"
+  });
+  const isJson = args.includes("--json") || args.includes("--jq") || args.includes("--format") && args[args.indexOf("--format") + 1] === "json";
+  const data = isJson ? JSON.parse(result.stdout) : result.stdout;
+  return data;
+}
+async function createIssueComment(issueNumber, body, repo) {
+  logger.debug("Creating issue comment", { issueNumber, repo });
+  const apiPath = repo ? `repos/${repo}/issues/${issueNumber}/comments` : `repos/:owner/:repo/issues/${issueNumber}/comments`;
+  return executeGhCommand([
+    "api",
+    apiPath,
+    "-f",
+    `body=${body}`,
+    "--jq",
+    "{id: .id, url: .html_url, created_at: .created_at}"
+  ]);
+}
+async function updateIssueComment(commentId, body, repo) {
+  logger.debug("Updating issue comment", { commentId, repo });
+  const apiPath = repo ? `repos/${repo}/issues/comments/${commentId}` : `repos/:owner/:repo/issues/comments/${commentId}`;
+  return executeGhCommand([
+    "api",
+    apiPath,
+    "-X",
+    "PATCH",
+    "-f",
+    `body=${body}`,
+    "--jq",
+    "{id: .id, url: .html_url, updated_at: .updated_at}"
+  ]);
+}
+async function createPRComment(prNumber, body, repo) {
+  logger.debug("Creating PR comment", { prNumber, repo });
+  const apiPath = repo ? `repos/${repo}/issues/${prNumber}/comments` : `repos/:owner/:repo/issues/${prNumber}/comments`;
+  return executeGhCommand([
+    "api",
+    apiPath,
+    "-f",
+    `body=${body}`,
+    "--jq",
+    "{id: .id, url: .html_url, created_at: .created_at}"
+  ]);
+}
+
+// src/mcp/GitHubIssueManagementProvider.ts
+function normalizeAuthor(author) {
+  if (!author) return null;
+  return {
+    id: author.id ? String(author.id) : author.login,
+    displayName: author.login,
+    // GitHub uses login as primary identifier
+    login: author.login,
+    // Preserve original GitHub field
+    ...author.avatarUrl && { avatarUrl: author.avatarUrl },
+    ...author.url && { url: author.url }
+  };
+}
+var GitHubIssueManagementProvider = class {
+  constructor() {
+    this.providerName = "github";
+  }
+  /**
+   * Fetch issue details using gh CLI
+   * Normalizes GitHub-specific fields to provider-agnostic format
+   */
+  async getIssue(input) {
+    const { number, includeComments = true } = input;
+    const issueNumber = parseInt(number, 10);
+    if (isNaN(issueNumber)) {
+      throw new Error(`Invalid GitHub issue number: ${number}. GitHub issue IDs must be numeric.`);
+    }
+    const fields = includeComments ? "body,title,comments,labels,assignees,milestone,author,state,number,url" : "body,title,labels,assignees,milestone,author,state,number,url";
+    const raw = await executeGhCommand([
+      "issue",
+      "view",
+      String(issueNumber),
+      "--json",
+      fields
+    ]);
+    const result = {
+      // Core fields
+      id: String(raw.number),
+      title: raw.title,
+      body: raw.body,
+      state: raw.state,
+      url: raw.url,
+      provider: "github",
+      // Normalized author
+      author: normalizeAuthor(raw.author),
+      // Optional flexible fields
+      ...raw.assignees && {
+        assignees: raw.assignees.map((a) => normalizeAuthor(a)).filter((a) => a !== null)
+      },
+      ...raw.labels && {
+        labels: raw.labels
+      },
+      // GitHub-specific passthrough fields
+      ...raw.milestone && {
+        milestone: raw.milestone
+      }
+    };
+    if (raw.comments !== void 0) {
+      result.comments = raw.comments.map((comment) => ({
+        id: String(comment.id),
+        body: comment.body,
+        createdAt: comment.createdAt,
+        author: normalizeAuthor(comment.author),
+        ...comment.updatedAt && { updatedAt: comment.updatedAt }
+      }));
+    }
+    return result;
+  }
+  /**
+   * Fetch a specific comment by ID using gh API
+   * Normalizes author to FlexibleAuthor format
+   */
+  async getComment(input) {
+    const { commentId } = input;
+    const numericCommentId = parseInt(commentId, 10);
+    if (isNaN(numericCommentId)) {
+      throw new Error(`Invalid GitHub comment ID: ${commentId}. GitHub comment IDs must be numeric.`);
+    }
+    const raw = await executeGhCommand([
+      "api",
+      `repos/:owner/:repo/issues/comments/${numericCommentId}`,
+      "--jq",
+      "{id: .id, body: .body, user: .user, created_at: .created_at, updated_at: .updated_at, html_url: .html_url, reactions: .reactions}"
+    ]);
+    return {
+      id: String(raw.id),
+      body: raw.body,
+      author: normalizeAuthor(raw.user),
+      created_at: raw.created_at,
+      ...raw.updated_at && { updated_at: raw.updated_at },
+      // Passthrough GitHub-specific fields
+      ...raw.html_url && { html_url: raw.html_url },
+      ...raw.reactions && { reactions: raw.reactions }
+    };
+  }
+  /**
+   * Create a new comment on an issue or PR
+   */
+  async createComment(input) {
+    const { number, body, type } = input;
+    const numericId = parseInt(number, 10);
+    if (isNaN(numericId)) {
+      throw new Error(`Invalid GitHub ${type} number: ${number}. GitHub IDs must be numeric.`);
+    }
+    const result = type === "issue" ? await createIssueComment(numericId, body) : await createPRComment(numericId, body);
+    return {
+      ...result,
+      id: String(result.id)
+    };
+  }
+  /**
+   * Update an existing comment
+   */
+  async updateComment(input) {
+    const { commentId, body } = input;
+    const numericCommentId = parseInt(commentId, 10);
+    if (isNaN(numericCommentId)) {
+      throw new Error(`Invalid GitHub comment ID: ${commentId}. GitHub comment IDs must be numeric.`);
+    }
+    const result = await updateIssueComment(numericCommentId, body);
+    return {
+      ...result,
+      id: String(result.id)
+    };
+  }
+};
+
+// src/utils/linear.ts
+import { LinearClient } from "@linear/sdk";
+
+// src/types/linear.ts
+var LinearServiceError = class _LinearServiceError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "LinearServiceError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _LinearServiceError);
+    }
+  }
+};
+
+// src/utils/linear.ts
+function getLinearApiToken() {
+  const token = process.env.LINEAR_API_TOKEN;
+  if (!token) {
+    throw new LinearServiceError(
+      "UNAUTHORIZED",
+      "LINEAR_API_TOKEN not set. Configure in settings.local.json or set environment variable."
+    );
+  }
+  return token;
+}
+function createLinearClient() {
+  return new LinearClient({ apiKey: getLinearApiToken() });
+}
+function handleLinearError(error, context) {
+  logger.debug(`${context}: Handling error`, { error });
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  if (errorMessage.includes("not found") || errorMessage.includes("Not found")) {
+    throw new LinearServiceError("NOT_FOUND", "Linear issue or resource not found", { error });
+  }
+  if (errorMessage.includes("unauthorized") || errorMessage.includes("Unauthorized") || errorMessage.includes("Invalid API key")) {
+    throw new LinearServiceError(
+      "UNAUTHORIZED",
+      "Linear authentication failed. Check LINEAR_API_TOKEN.",
+      { error }
+    );
+  }
+  if (errorMessage.includes("rate limit")) {
+    throw new LinearServiceError("RATE_LIMITED", "Linear API rate limit exceeded", { error });
+  }
+  throw new LinearServiceError("CLI_ERROR", `Linear SDK error: ${errorMessage}`, { error });
+}
+async function fetchLinearIssue(identifier) {
+  try {
+    logger.debug(`Fetching Linear issue: ${identifier}`);
+    const client = createLinearClient();
+    const issue = await client.issue(identifier);
+    if (!issue) {
+      throw new LinearServiceError("NOT_FOUND", `Linear issue ${identifier} not found`);
+    }
+    const result = {
+      id: issue.id,
+      identifier: issue.identifier,
+      title: issue.title,
+      url: issue.url,
+      createdAt: issue.createdAt.toISOString(),
+      updatedAt: issue.updatedAt.toISOString()
+    };
+    if (issue.description) {
+      result.description = issue.description;
+    }
+    if (issue.state) {
+      const state = await issue.state;
+      if (state == null ? void 0 : state.name) {
+        result.state = state.name;
+      }
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof LinearServiceError) {
+      throw error;
+    }
+    handleLinearError(error, "fetchLinearIssue");
+  }
+}
+async function createLinearComment(identifier, body) {
+  try {
+    logger.debug(`Creating comment on Linear issue ${identifier}`);
+    const client = createLinearClient();
+    const issue = await client.issue(identifier);
+    if (!issue) {
+      throw new LinearServiceError("NOT_FOUND", `Linear issue ${identifier} not found`);
+    }
+    const payload = await client.createComment({
+      issueId: issue.id,
+      body
+    });
+    const comment = await payload.comment;
+    if (!comment) {
+      throw new LinearServiceError("CLI_ERROR", "Failed to create Linear comment");
+    }
+    return {
+      id: comment.id,
+      body: comment.body,
+      createdAt: comment.createdAt.toISOString(),
+      updatedAt: comment.updatedAt.toISOString(),
+      url: comment.url
+    };
+  } catch (error) {
+    if (error instanceof LinearServiceError) {
+      throw error;
+    }
+    handleLinearError(error, "createLinearComment");
+  }
+}
+async function getLinearComment(commentId) {
+  try {
+    logger.debug(`Fetching Linear comment: ${commentId}`);
+    const client = createLinearClient();
+    const comment = await client.comment({ id: commentId });
+    if (!comment) {
+      throw new LinearServiceError("NOT_FOUND", `Linear comment ${commentId} not found`);
+    }
+    return {
+      id: comment.id,
+      body: comment.body,
+      createdAt: comment.createdAt.toISOString(),
+      updatedAt: comment.updatedAt.toISOString(),
+      url: comment.url
+    };
+  } catch (error) {
+    if (error instanceof LinearServiceError) {
+      throw error;
+    }
+    handleLinearError(error, "getLinearComment");
+  }
+}
+async function updateLinearComment(commentId, body) {
+  try {
+    logger.debug(`Updating Linear comment: ${commentId}`);
+    const client = createLinearClient();
+    const payload = await client.updateComment(commentId, { body });
+    const comment = await payload.comment;
+    if (!comment) {
+      throw new LinearServiceError("CLI_ERROR", "Failed to update Linear comment");
+    }
+    return {
+      id: comment.id,
+      body: comment.body,
+      createdAt: comment.createdAt.toISOString(),
+      updatedAt: comment.updatedAt.toISOString(),
+      url: comment.url
+    };
+  } catch (error) {
+    if (error instanceof LinearServiceError) {
+      throw error;
+    }
+    handleLinearError(error, "updateLinearComment");
+  }
+}
+async function fetchLinearIssueComments(identifier) {
+  try {
+    logger.debug(`Fetching comments for Linear issue: ${identifier}`);
+    const client = createLinearClient();
+    const issue = await client.issue(identifier);
+    if (!issue) {
+      throw new LinearServiceError("NOT_FOUND", `Linear issue ${identifier} not found`);
+    }
+    const comments = await issue.comments({ first: 100 });
+    return comments.nodes.map((comment) => ({
+      id: comment.id,
+      body: comment.body,
+      createdAt: comment.createdAt.toISOString(),
+      updatedAt: comment.updatedAt.toISOString(),
+      url: comment.url
+    }));
+  } catch (error) {
+    if (error instanceof LinearServiceError) {
+      throw error;
+    }
+    handleLinearError(error, "fetchLinearIssueComments");
+  }
+}
+
+// src/utils/linear-markup-converter.ts
+import { appendFileSync } from "fs";
+import { join, dirname, basename, extname } from "path";
+var LinearMarkupConverter = class {
+  /**
+   * Convert HTML details/summary blocks to Linear's collapsible format
+   * Handles nested details blocks recursively
+   *
+   * @param text - Text containing HTML details/summary blocks
+   * @returns Text with details/summary converted to Linear format
+   */
+  static convertDetailsToLinear(text) {
+    if (!text) {
+      return text;
+    }
+    let previousText = "";
+    let currentText = text;
+    while (previousText !== currentText) {
+      previousText = currentText;
+      currentText = this.convertSinglePass(currentText);
+    }
+    return currentText;
+  }
+  /**
+   * Perform a single pass of details block conversion
+   * Converts the innermost details blocks first
+   */
+  static convertSinglePass(text) {
+    const detailsRegex = /<details[^>]*>\s*<summary[^>]*>(.*?)<\/summary>\s*(.*?)\s*<\/details>/gis;
+    return text.replace(detailsRegex, (_match, summary, content) => {
+      const cleanSummary = this.cleanText(summary);
+      const cleanContent = this.cleanContent(content);
+      if (cleanContent) {
+        return `+++ ${cleanSummary}
+
+${cleanContent}
+
++++`;
+      } else {
+        return `+++ ${cleanSummary}
+
++++`;
+      }
+    });
+  }
+  /**
+   * Clean text by trimming whitespace and decoding common HTML entities
+   */
+  static cleanText(text) {
+    return text.trim().replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  }
+  /**
+   * Clean content while preserving internal structure
+   * - Removes leading/trailing whitespace
+   * - Normalizes internal blank lines (max 2 consecutive newlines)
+   * - Preserves code blocks and other formatting
+   */
+  static cleanContent(content) {
+    if (!content) {
+      return "";
+    }
+    let cleaned = content.trim();
+    cleaned = cleaned.replace(/\n{3,}/g, "\n\n");
+    return cleaned;
+  }
+  /**
+   * Check if text contains HTML details/summary blocks
+   * Useful for conditional conversion
+   */
+  static hasDetailsBlocks(text) {
+    if (!text) {
+      return false;
+    }
+    const detailsRegex = /<details[^>]*>.*?<summary[^>]*>.*?<\/summary>.*?<\/details>/is;
+    return detailsRegex.test(text);
+  }
+  /**
+   * Remove wrapper tags from code sample details blocks
+   * Identifies details blocks where summary contains "X lines" pattern
+   * and removes the details/summary tags while preserving the content
+   *
+   * @param text - Text containing potential code sample details blocks
+   * @returns Text with code sample wrappers removed
+   */
+  static removeCodeSampleWrappers(text) {
+    if (!text) {
+      return text;
+    }
+    const codeSampleRegex = /<details[^>]*>\s*<summary[^>]*>([^<]*\d+\s+lines[^<]*)<\/summary>\s*([\s\S]*?)<\/details>/gi;
+    return text.replace(codeSampleRegex, (_match, _summary, content) => {
+      return content.trim();
+    });
+  }
+  /**
+   * Convert text for Linear - applies all necessary conversions
+   * Currently only converts details/summary blocks, but can be extended
+   * for other HTML to Linear markdown conversions
+   */
+  static convertToLinear(text) {
+    if (!text) {
+      return text;
+    }
+    this.logConversion("INPUT", text);
+    let converted = text;
+    converted = this.removeCodeSampleWrappers(converted);
+    converted = this.convertDetailsToLinear(converted);
+    this.logConversion("OUTPUT", converted);
+    return converted;
+  }
+  /**
+   * Log conversion input/output if LINEAR_MARKDOWN_LOG_FILE is set
+   */
+  static logConversion(label, content) {
+    const logFilePath = process.env.LINEAR_MARKDOWN_LOG_FILE;
+    if (!logFilePath) {
+      return;
+    }
+    try {
+      const timestampedPath = this.getTimestampedLogPath(logFilePath);
+      const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+      const separator = "================================";
+      const logEntry = `${separator}
+[${timestamp}] CONVERSION ${label}
+${separator}
+${label}:
+${content}
+
+`;
+      appendFileSync(timestampedPath, logEntry, "utf-8");
+    } catch {
+    }
+  }
+  /**
+   * Generate timestamped log file path
+   * Example: debug.log -> debug-20231202-161234.log
+   */
+  static getTimestampedLogPath(logFilePath) {
+    const dir = dirname(logFilePath);
+    const ext = extname(logFilePath);
+    const base = basename(logFilePath, ext);
+    const now = /* @__PURE__ */ new Date();
+    const timestamp = [
+      now.getFullYear(),
+      String(now.getMonth() + 1).padStart(2, "0"),
+      String(now.getDate()).padStart(2, "0")
+    ].join("") + "-" + [
+      String(now.getHours()).padStart(2, "0"),
+      String(now.getMinutes()).padStart(2, "0"),
+      String(now.getSeconds()).padStart(2, "0")
+    ].join("");
+    return join(dir, `${base}-${timestamp}${ext}`);
+  }
+};
+
+// src/mcp/LinearIssueManagementProvider.ts
+var LinearIssueManagementProvider = class {
+  constructor() {
+    this.providerName = "linear";
+  }
+  /**
+   * Fetch issue details using Linear SDK
+   */
+  async getIssue(input) {
+    const { number, includeComments = true } = input;
+    const raw = await fetchLinearIssue(number);
+    const state = raw.state && (raw.state.toLowerCase().includes("done") || raw.state.toLowerCase().includes("completed") || raw.state.toLowerCase().includes("canceled")) ? "closed" : "open";
+    const result = {
+      id: raw.identifier,
+      title: raw.title,
+      body: raw.description ?? "",
+      state,
+      url: raw.url,
+      provider: "linear",
+      author: null,
+      // Linear SDK doesn't return author in basic fetch
+      // Linear-specific fields
+      linearState: raw.state,
+      createdAt: raw.createdAt,
+      updatedAt: raw.updatedAt
+    };
+    if (includeComments) {
+      try {
+        const comments = await this.fetchIssueComments(number);
+        if (comments) {
+          result.comments = comments;
+        }
+      } catch {
+      }
+    }
+    return result;
+  }
+  /**
+   * Fetch comments for an issue
+   */
+  async fetchIssueComments(identifier) {
+    try {
+      const comments = await fetchLinearIssueComments(identifier);
+      return comments.map((comment) => ({
+        id: comment.id,
+        body: comment.body,
+        createdAt: comment.createdAt,
+        author: null,
+        // Linear SDK doesn't return comment author info in basic fetch
+        ...comment.updatedAt && { updatedAt: comment.updatedAt }
+      }));
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Fetch a specific comment by ID
+   */
+  async getComment(input) {
+    const { commentId } = input;
+    const raw = await getLinearComment(commentId);
+    return {
+      id: raw.id,
+      body: raw.body,
+      author: null,
+      // Linear SDK doesn't return comment author info in basic fetch
+      created_at: raw.createdAt
+    };
+  }
+  /**
+   * Create a new comment on an issue
+   */
+  async createComment(input) {
+    const { number, body } = input;
+    const convertedBody = LinearMarkupConverter.convertToLinear(body);
+    const result = await createLinearComment(number, convertedBody);
+    return {
+      id: result.id,
+      url: result.url,
+      created_at: result.createdAt
+    };
+  }
+  /**
+   * Update an existing comment
+   */
+  async updateComment(input) {
+    const { commentId, body } = input;
+    const convertedBody = LinearMarkupConverter.convertToLinear(body);
+    const result = await updateLinearComment(commentId, convertedBody);
+    return {
+      id: result.id,
+      url: result.url,
+      updated_at: result.updatedAt
+    };
+  }
+};
+
+// src/mcp/IssueManagementProviderFactory.ts
+var IssueManagementProviderFactory = class {
+  /**
+   * Create an issue management provider based on the provider type
+   */
+  static create(provider) {
+    switch (provider) {
+      case "github":
+        return new GitHubIssueManagementProvider();
+      case "linear":
+        return new LinearIssueManagementProvider();
+      default:
+        throw new Error(`Unsupported issue management provider: ${provider}`);
+    }
+  }
+};
+
+// src/mcp/issue-management-server.ts
+function validateEnvironment() {
+  const provider = process.env.ISSUE_PROVIDER;
+  if (!provider) {
+    console.error("Missing required environment variable: ISSUE_PROVIDER");
+    process.exit(1);
+  }
+  if (provider !== "github" && provider !== "linear") {
+    console.error(`Invalid ISSUE_PROVIDER: ${provider}. Must be 'github' or 'linear'`);
+    process.exit(1);
+  }
+  if (provider === "github") {
+    const required = ["REPO_OWNER", "REPO_NAME"];
+    const missing = required.filter((key) => !process.env[key]);
+    if (missing.length > 0) {
+      console.error(
+        `Missing required environment variables for GitHub provider: ${missing.join(", ")}`
+      );
+      process.exit(1);
+    }
+  }
+  if (provider === "linear") {
+    if (!process.env.LINEAR_API_TOKEN) {
+      console.error("Missing required environment variable for Linear provider: LINEAR_API_TOKEN");
+      process.exit(1);
+    }
+  }
+  return provider;
+}
+var server = new McpServer({
+  name: "issue-management-broker",
+  version: "0.1.0"
+});
+var flexibleAuthorSchema = z.object({
+  id: z.string(),
+  displayName: z.string()
+}).passthrough();
+server.registerTool(
+  "get_issue",
+  {
+    title: "Get Issue",
+    description: "Fetch issue details including body, title, comments, labels, assignees, and other metadata. Author fields vary by provider: GitHub uses { login }, Linear uses { name, displayName }, Jira uses { displayName, accountId }. All authors have normalized core fields: { id, displayName } plus provider-specific fields.",
+    inputSchema: {
+      number: z.string().describe("The issue identifier"),
+      includeComments: z.boolean().optional().describe("Whether to include comments (default: true)")
+    },
+    outputSchema: {
+      // Core validated fields
+      id: z.string().describe("Issue identifier"),
+      title: z.string().describe("Issue title"),
+      body: z.string().describe("Issue body/description"),
+      state: z.string().describe("Issue state (open, closed, etc.)"),
+      url: z.string().describe("Issue URL"),
+      provider: z.enum(["github", "linear"]).describe("Issue management provider"),
+      // Flexible author - core fields + passthrough
+      author: flexibleAuthorSchema.nullable().describe(
+        "Issue author with normalized { id, displayName } plus provider-specific fields"
+      ),
+      // Optional flexible arrays
+      assignees: z.array(flexibleAuthorSchema).optional().describe(
+        "Issue assignees with normalized { id, displayName } plus provider-specific fields"
+      ),
+      labels: z.array(
+        z.object({ name: z.string() }).passthrough()
+      ).optional().describe("Issue labels"),
+      // Comments with flexible author
+      comments: z.array(
+        z.object({
+          id: z.string(),
+          body: z.string(),
+          author: flexibleAuthorSchema.nullable(),
+          createdAt: z.string()
+        }).passthrough()
+      ).optional().describe("Issue comments with flexible author structure")
+    }
+  },
+  async ({ number, includeComments }) => {
+    console.error(`Fetching issue ${number}`);
+    try {
+      const provider = IssueManagementProviderFactory.create(
+        process.env.ISSUE_PROVIDER
+      );
+      const result = await provider.getIssue({ number, includeComments });
+      console.error(`Issue fetched successfully: ${result.number} - ${result.title}`);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result)
+          }
+        ],
+        structuredContent: result
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      console.error(`Failed to fetch issue: ${errorMessage}`);
+      throw new Error(`Failed to fetch issue: ${errorMessage}`);
+    }
+  }
+);
+server.registerTool(
+  "get_comment",
+  {
+    title: "Get Comment",
+    description: "Fetch a specific comment by ID. Author has normalized core fields { id, displayName } plus provider-specific fields.",
+    inputSchema: {
+      commentId: z.string().describe("The comment identifier to fetch"),
+      number: z.string().describe("The issue or PR identifier (context for providers that need it)")
+    },
+    outputSchema: {
+      id: z.string().describe("Comment identifier"),
+      body: z.string().describe("Comment body content"),
+      author: flexibleAuthorSchema.nullable().describe(
+        "Comment author with normalized { id, displayName } plus provider-specific fields"
+      ),
+      created_at: z.string().describe("Comment creation timestamp"),
+      updated_at: z.string().optional().describe("Comment last updated timestamp")
+    }
+  },
+  async ({ commentId, number }) => {
+    console.error(`Fetching comment ${commentId} from issue ${number}`);
+    try {
+      const provider = IssueManagementProviderFactory.create(
+        process.env.ISSUE_PROVIDER
+      );
+      const result = await provider.getComment({ commentId, number });
+      console.error(`Comment fetched successfully: ${result.id}`);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result)
+          }
+        ],
+        structuredContent: result
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      console.error(`Failed to fetch comment: ${errorMessage}`);
+      throw new Error(`Failed to fetch comment: ${errorMessage}`);
+    }
+  }
+);
+server.registerTool(
+  "create_comment",
+  {
+    title: "Create Comment",
+    description: "Create a new comment on an issue or pull request. Use this to start tracking a workflow phase.",
+    inputSchema: {
+      number: z.string().describe("The issue or PR identifier"),
+      body: z.string().describe("The comment body (markdown supported)"),
+      type: z.enum(["issue", "pr"]).describe("Type of entity to comment on (issue or pr)")
+    },
+    outputSchema: {
+      id: z.string(),
+      url: z.string(),
+      created_at: z.string().optional()
+    }
+  },
+  async ({ number, body, type }) => {
+    console.error(`Creating ${type} comment on ${number}`);
+    try {
+      const provider = IssueManagementProviderFactory.create(
+        process.env.ISSUE_PROVIDER
+      );
+      const result = await provider.createComment({ number, body, type });
+      console.error(
+        `Comment created successfully: ${result.id} at ${result.url}`
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result)
+          }
+        ],
+        structuredContent: result
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      console.error(`Failed to create comment: ${errorMessage}`);
+      throw new Error(`Failed to create ${type} comment: ${errorMessage}`);
+    }
+  }
+);
+server.registerTool(
+  "update_comment",
+  {
+    title: "Update Comment",
+    description: "Update an existing comment. Use this to update progress during a workflow phase.",
+    inputSchema: {
+      commentId: z.string().describe("The comment identifier to update"),
+      number: z.string().describe("The issue or PR identifier (context for providers that need it)"),
+      body: z.string().describe("The updated comment body (markdown supported)")
+    },
+    outputSchema: {
+      id: z.string(),
+      url: z.string(),
+      updated_at: z.string().optional()
+    }
+  },
+  async ({ commentId, number, body }) => {
+    console.error(`Updating comment ${commentId} on issue ${number}`);
+    try {
+      const provider = IssueManagementProviderFactory.create(
+        process.env.ISSUE_PROVIDER
+      );
+      const result = await provider.updateComment({ commentId, number, body });
+      console.error(
+        `Comment updated successfully: ${result.id} at ${result.url}`
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result)
+          }
+        ],
+        structuredContent: result
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      console.error(`Failed to update comment: ${errorMessage}`);
+      throw new Error(`Failed to update comment: ${errorMessage}`);
+    }
+  }
+);
+async function main() {
+  console.error("Starting Issue Management MCP Server...");
+  const provider = validateEnvironment();
+  console.error("Environment validated");
+  console.error(`Issue management provider: ${provider}`);
+  if (provider === "github") {
+    console.error(`Repository: ${process.env.REPO_OWNER}/${process.env.REPO_NAME}`);
+    console.error(`Event type: ${process.env.GITHUB_EVENT_NAME ?? "not specified"}`);
+  }
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Issue Management MCP Server running on stdio transport");
+}
+main().catch((error) => {
+  console.error("Fatal error starting MCP server:", error);
+  process.exit(1);
+});
+//# sourceMappingURL=issue-management-server.js.map