@yannelli/paseo-linear-plugin 1.0.1 → 1.1.0-beta.1

package/server/links.ts

@@ -0,0 +1,153 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import {
+  aliasesFrom,
+  type FileLink,
+  fileReferences,
+  GO_PACKAGE,
+  joinPath,
+  type LinkContext,
+  type LinkKind,
+  parseLooseJson,
+  type Reference,
+} from "../shared/links";
+
+// Reads the files on the Linear Live graph and resolves the links between them. Every path is
+// checked against the agent's folder after symlinks resolve, so a link cannot reach outside it.
+
+const MAX_BYTES = 512 * 1024;
+const MAX_LINKS = 3000;
+const MAX_PACKAGES = 100;
+const CONTEXT_TTL_MS = 60_000;
+const STRENGTH: Record<LinkKind, number> = { import: 3, link: 2, mention: 1 };
+
+const contexts = new Map<string, { at: number; context: Promise<LinkContext> }>();
+const parsed = new Map<string, Reference[]>();
+
+function inside(root: string, resolved: string): boolean {
+  return resolved === root || resolved.startsWith(`${root}${path.sep}`);
+}
+
+async function resolveInside(root: string, relative: string): Promise<string | null> {
+  const resolved = await realpath(path.resolve(root, relative)).catch(() => null);
+  return resolved && inside(root, resolved) ? resolved : null;
+}
+
+async function readText(root: string, relative: string): Promise<string | null> {
+  const resolved = await resolveInside(root, relative);
+  if (!resolved) return null;
+  const info = await stat(resolved).catch(() => null);
+  if (!info?.isFile() || info.size > MAX_BYTES) return null;
+  const text = await readFile(resolved, "utf8").catch(() => null);
+  return text && !text.slice(0, 1024).includes("\u0000") ? text : null;
+}
+
+async function readJson(root: string, relative: string): Promise<unknown> {
+  const text = await readText(root, relative);
+  return text === null ? null : parseLooseJson(text);
+}
+
+// Workspace packages from package.json or pnpm-workspace.yaml, as "dir/*" or exact folders.
+async function workspacePackages(root: string): Promise<LinkContext["packages"]> {
+  const manifest = (await readJson(root, "package.json")) as { workspaces?: string[] | { packages?: string[] } } | null;
+  const patterns = Array.isArray(manifest?.workspaces) ? manifest.workspaces : (manifest?.workspaces?.packages ?? []);
+  const pnpm = await readText(root, "pnpm-workspace.yaml");
+  if (pnpm) patterns.push(...[...pnpm.matchAll(/^\s*-\s*["']?([^"'\n#]+?)["']?\s*$/gm)].map((match) => match[1] ?? ""));
+  const dirs: string[] = [];
+  for (const pattern of patterns) {
+    const clean = pattern.replace(/\/+$/, "");
+    if (clean.startsWith("!") || clean.includes("**")) continue;
+    if (!clean.endsWith("/*")) {
+      dirs.push(clean);
+      continue;
+    }
+    const parent = clean.slice(0, -2);
+    const resolved = await resolveInside(root, parent);
+    const entries = resolved ? await readdir(resolved, { withFileTypes: true }).catch(() => []) : [];
+    for (const entry of entries) if (entry.isDirectory()) dirs.push(`${parent}/${entry.name}`);
+  }
+  const packages = new Map<string, { dir: string; entry: string | null }>();
+  for (const dir of dirs.slice(0, MAX_PACKAGES)) {
+    const pkg = (await readJson(root, `${dir}/package.json`)) as Record<string, unknown> | null;
+    if (!pkg || typeof pkg.name !== "string") continue;
+    const exported = pkg.exports as unknown;
+    const dot = typeof exported === "string" ? exported : (exported as Record<string, unknown> | undefined)?.["."];
+    const entry = [pkg.source, pkg.module, pkg.main, typeof dot === "string" ? dot : null].find((value) => typeof value === "string");
+    packages.set(pkg.name, { dir, entry: typeof entry === "string" ? joinPath(dir, entry) : null });
+  }
+  return packages;
+}
+
+async function buildContext(root: string): Promise<LinkContext> {
+  const aliases = [];
+  for (const file of ["tsconfig.json", "jsconfig.json"]) aliases.push(...aliasesFrom(await readJson(root, file)));
+  const goMod = await readText(root, "go.mod");
+  const goModule = goMod ? (/^module\s+(\S+)/m.exec(goMod)?.[1] ?? null) : null;
+  return { aliases, packages: await workspacePackages(root), goModule };
+}
+
+function linkContext(root: string): Promise<LinkContext> {
+  const cached = contexts.get(root);
+  if (cached && Date.now() - cached.at < CONTEXT_TTL_MS) return cached.context;
+  const context = buildContext(root);
+  contexts.set(root, { at: Date.now(), context });
+  return context;
+}
+
+async function references(root: string, relative: string, context: LinkContext): Promise<Reference[]> {
+  const resolved = await resolveInside(root, relative);
+  const info = resolved ? await stat(resolved).catch(() => null) : null;
+  if (!info?.isFile()) return [];
+  const key = `${root}\u0000${relative}\u0000${info.mtimeMs}\u0000${info.size}`;
+  const known = parsed.get(key);
+  if (known) return known;
+  const text = await readText(root, relative);
+  const found = text === null ? [] : fileReferences(relative, text, context);
+  if (parsed.size > 5000) parsed.clear();
+  parsed.set(key, found);
+  return found;
+}
+
+/** Links from each of the files to other files in the agent's folder. */
+export async function fileLinks(cwd: string, files: readonly string[]): Promise<FileLink[]> {
+  const root = await realpath(cwd);
+  const context = await linkContext(root);
+  const exists = new Map<string, Promise<boolean>>();
+  const isFile = (relative: string) => {
+    let known = exists.get(relative);
+    if (!known) {
+      known = resolveInside(root, relative).then(async (resolved) => Boolean(resolved && (await stat(resolved)).isFile())).catch(() => false);
+      exists.set(relative, known);
+    }
+    return known;
+  };
+  const goFiles = async (dir: string) => {
+    const resolved = await resolveInside(root, dir);
+    const entries = resolved ? await readdir(resolved, { withFileTypes: true }).catch(() => []) : [];
+    return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".go")).map((entry) => `${dir}/${entry.name}`);
+  };
+  const best = new Map<string, FileLink>();
+  for (const from of new Set(files)) {
+    for (const reference of await references(root, from, context)) {
+      let targets: string[] = [];
+      for (const candidate of reference.candidates) {
+        if (candidate.endsWith(GO_PACKAGE)) {
+          targets = await goFiles(candidate.slice(0, -GO_PACKAGE.length));
+          break;
+        }
+        if (await isFile(candidate)) {
+          targets = [candidate];
+          break;
+        }
+      }
+      for (const to of targets) {
+        if (to === from) continue;
+        const id = `${from}>${to}`;
+        const known = best.get(id);
+        if (!known || STRENGTH[reference.kind] > STRENGTH[known.kind]) best.set(id, { from, to, kind: reference.kind });
+      }
+      if (best.size >= MAX_LINKS) return [...best.values()];
+    }
+  }
+  return [...best.values()];
+}

package/server/live.ts

@@ -0,0 +1,360 @@
+import { readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { z } from "zod";
+import { relativePath } from "../shared/activity";
+import { type IssueDetail, ISSUE_CARD_KIND } from "../shared/linear";
+import {
+  ExploreResultSchema,
+  exploreRpc,
+  type IssueMap,
+  type Job,
+  type LaunchInput,
+  launchAfterExploreRpc,
+  clearMapRpc,
+  linksRpc,
+  listFilesRpc,
+  subagentLogsRpc,
+  liveMapRpc,
+  MAX_DIR_ENTRIES,
+  MAX_EXPLORE_FILES,
+} from "../shared/live";
+import { AGENT_LABELS, issueSnapshot } from "../shared/prompts";
+import { type LinearSettings, projectEnabled } from "../shared/settings";
+import {
+  createJobStore,
+  finishInternalRun,
+  type Paseo,
+  READ_ONLY_RULES,
+  startInternalRun,
+} from "./agent-runs";
+import type { LinearAccess } from "./handlers";
+import { fileLinks } from "./links";
+import { subagentLogs } from "./subagent-logs";
+import type { LaunchQueue, MapStore } from "./stores";
+
+const EXPLORE_TIMEOUT_MS = 20 * 60_000;
+const RECOVER_INTERVAL_MS = 30_000;
+const EXPLORE_TITLE = /^Explore ([A-Za-z][A-Za-z0-9]*-\d+)$/;
+const SKIPPED_ENTRIES = new Set([".git", "node_modules", ".DS_Store"]);
+
+export interface AgentInfo {
+  id: string;
+  cwd: string;
+  workspaceId: string | null;
+  /** Paseo project of the agent's workspace, when the workspace is known. */
+  projectId: string | null;
+  provider: string;
+  /** The provider's session, such as Claude's session id. */
+  sessionId: string | null;
+  labels: Record<string, string>;
+}
+
+export async function agentInfo(paseo: Paseo, agentId: string): Promise<AgentInfo> {
+  const handle = paseo.agents.ref(agentId);
+  await handle.refresh();
+  const agent = handle.current();
+  if (!agent) throw new Error("The agent was not found");
+  const workspaceId = agent.workspaceId ?? null;
+  const workspace = workspaceId
+    ? await paseo.workspaces
+        .ref(workspaceId)
+        .refresh()
+        .catch(() => null)
+    : null;
+  return {
+    id: agent.id,
+    cwd: agent.cwd,
+    workspaceId,
+    projectId: workspace?.projectId ?? null,
+    provider: agent.provider,
+    sessionId: agent.runtimeInfo?.sessionId ?? null,
+    labels: agent.labels ?? {},
+  };
+}
+
+// The client names directories, never a root: the root is the agent's own folder, and a
+// directory that resolves outside it, through ".." or a symlink, is skipped.
+export async function listDirectories(cwd: string, dirs: readonly string[]) {
+  const root = await realpath(cwd);
+  const results: { dir: string; files: string[]; truncated: boolean }[] = [];
+  for (const dir of new Set(dirs)) {
+    const relative = dir === "" ? "" : relativePath(dir, root);
+    if (relative === null) continue;
+    const resolved = await realpath(path.resolve(root, relative)).catch(() => null);
+    if (!resolved || (resolved !== root && !resolved.startsWith(`${root}${path.sep}`))) continue;
+    const entries = await readdir(resolved, { withFileTypes: true }).catch(() => []);
+    const files = entries
+      .filter((entry) => entry.isFile() && !SKIPPED_ENTRIES.has(entry.name))
+      .map((entry) => entry.name)
+      .sort((a, b) => a.localeCompare(b));
+    results.push({
+      dir,
+      files: files.slice(0, MAX_DIR_ENTRIES),
+      truncated: files.length > MAX_DIR_ENTRIES,
+    });
+  }
+  return results;
+}
+
+export function explorePrompt(issue: IssueDetail): string {
+  const keys = [issue.identifier, ...issue.children.map((child) => child.identifier)];
+  return [
+    `Map this repository for Linear issue ${issue.identifier}: ${issue.title}`,
+    "",
+    ...READ_ONLY_RULES,
+    "",
+    issueSnapshot(issue, { includeComments: false }),
+    "",
+    "List the files an engineer will most likely read or change for this issue and each sub-issue.",
+    `Include files that will probably be created, at their expected path. List at most ${MAX_EXPLORE_FILES} files.`,
+    `Set "issue" to the sub-issue key the file belongs to, or ${issue.identifier} for the whole issue.`,
+    `Valid keys: ${keys.join(", ")}.`,
+    "Reply with only a JSON object in a ```json block, with repo-relative paths:",
+    `{"files":[{"path":"src/example.ts","issue":"${keys[1] ?? keys[0]}"}]}`,
+  ].join("\n");
+}
+
+export function toIssueMap(
+  issue: IssueDetail,
+  cwd: string,
+  result: z.infer<typeof ExploreResultSchema>,
+  now = new Date(),
+): IssueMap {
+  const keys = new Set([issue.identifier, ...issue.children.map((child) => child.identifier)]);
+  const seen = new Set<string>();
+  const files: IssueMap["files"] = [];
+  for (const entry of result.files) {
+    const filePath = relativePath(entry.path, cwd);
+    if (!filePath || seen.has(filePath)) continue;
+    seen.add(filePath);
+    const key = entry.issue.trim().toUpperCase();
+    files.push({ path: filePath, issue: keys.has(key) ? key : issue.identifier });
+  }
+  return { identifier: issue.identifier, source: "explore", files, createdAt: now.toISOString() };
+}
+
+export interface LiveDependencies {
+  access: LinearAccess;
+  maps: MapStore;
+  launches: LaunchQueue;
+  readSettings(): Promise<LinearSettings | null>;
+}
+
+type WorkspaceHandle = Awaited<ReturnType<Paseo["workspaces"]["open"]>>;
+
+/** Starts the implementing agent and attaches the issue card to its timeline. */
+export async function startLaunch(workspace: WorkspaceHandle, launch: LaunchInput) {
+  const agent = await workspace.agents.create(launch.agent);
+  await agent.timeline
+    .append({
+      type: "plugin",
+      id: `linear-issue-${launch.card.identifier}`,
+      kind: ISSUE_CARD_KIND,
+      version: 1,
+      data: launch.card,
+    })
+    .catch((error: unknown) => console.error("Linear issue card was not attached", error));
+  return agent.id;
+}
+
+export function registerLive(server: PluginServerContext, dependencies: LiveDependencies) {
+  const { access, maps, launches, readSettings } = dependencies;
+  const jobs = createJobStore<IssueMap>();
+  const recovering = new Map<string, Promise<Job | null>>();
+  const recoveredAt = new Map<string, number>();
+
+  // Called whenever an explore run ends, by any path. Claiming first means a launch that two
+  // paths see still starts one agent.
+  async function startWaiting(paseo: Paseo, identifier: string) {
+    for (const launch of await launches.claim(identifier)) {
+      await startLaunch(paseo.workspaces.ref(launch.workspaceId), launch).catch((error: unknown) =>
+        console.error(`Linear agent for ${identifier} did not start after exploring`, error),
+      );
+    }
+  }
+
+  function track(paseo: Paseo, job: Job) {
+    void jobs.wait(job.id).then(() => startWaiting(paseo, job.id));
+    return job;
+  }
+
+  function saveMap(issue: IssueDetail, cwd: string) {
+    return async (value: z.infer<typeof ExploreResultSchema>) => {
+      const map = toIssueMap(issue, cwd, value);
+      await maps.set(map);
+      return map;
+    };
+  }
+
+  // A plugin reload or daemon restart drops the job but not the explore agent. Finds that
+  // agent by its label and finishes the run, or starts waiting launches when there is none.
+  async function adopt(paseo: Paseo, identifier: string): Promise<Job | null> {
+    const { entries } = await paseo.agents.list({
+      filter: { labels: { [AGENT_LABELS.explore]: identifier } },
+      page: { limit: 10 },
+    });
+    const orphan = entries.map((entry) => entry.agent).find((agent) => !agent.archivedAt);
+    if (!orphan) {
+      await startWaiting(paseo, identifier);
+      return null;
+    }
+    const job = await jobs.start(identifier, async () => {
+      const { linear } = await access.connect(orphan.labels?.[AGENT_LABELS.project] ?? null);
+      const issue = await linear.getIssue(identifier);
+      const handle = paseo.agents.ref(orphan.id);
+      const result = finishInternalRun(handle, orphan.cwd, ExploreResultSchema, EXPLORE_TIMEOUT_MS);
+      return { agentId: orphan.id, result: result.then(saveMap(issue, orphan.cwd)) };
+    });
+    return track(paseo, job);
+  }
+
+  function recover(paseo: Paseo, identifier: string): Promise<Job | null> {
+    const existing = jobs.get(identifier)?.job;
+    if (existing?.status === "running") return Promise.resolve(existing);
+    const inFlight = recovering.get(identifier);
+    if (inFlight) return inFlight;
+    recoveredAt.set(identifier, Date.now());
+    const run = adopt(paseo, identifier).finally(() => recovering.delete(identifier));
+    recovering.set(identifier, run);
+    return run;
+  }
+
+  server.handle(listFilesRpc, async ({ agentId, dirs }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    return { dirs: await listDirectories(agent.cwd, dirs) };
+  });
+
+  server.handle(linksRpc, async ({ agentId, files }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    return { links: await fileLinks(agent.cwd, files) };
+  });
+
+  server.handle(clearMapRpc, async ({ agentId }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    const identifier = agent.labels[AGENT_LABELS.issue];
+    if (!identifier) throw new Error("This agent is not linked to a Linear issue");
+    if (jobs.get(identifier)?.job.status === "running") throw new Error("The explore agent is still mapping this issue");
+    await maps.delete(identifier);
+    jobs.forget(identifier);
+    return { cleared: true };
+  });
+  server.handle(subagentLogsRpc, async ({ agentId }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    // Only Claude keeps subagent transcripts this plugin can read.
+    if (agent.provider.split("/")[0] !== "claude" || !agent.sessionId) return { runs: [] };
+    return { runs: await subagentLogs(agent.sessionId, agent.cwd) };
+  });
+  server.handle(liveMapRpc, async ({ identifier }, { paseo }) => {
+    const map = await maps.get(identifier);
+    let job = jobs.get(identifier)?.job ?? null;
+    const checked = recoveredAt.get(identifier) ?? 0;
+    if (!map && !job && Date.now() - checked > RECOVER_INTERVAL_MS) {
+      job = await recover(paseo, identifier).catch(() => null);
+    }
+    return { map: map ?? (await maps.get(identifier)), job };
+  });
+
+  // Finishes runs whose job a reload dropped, as soon as the agent's turn ends.
+  server.on("agent.turn_ended", async (event, { paseo }) => {
+    const identifier = EXPLORE_TITLE.exec(event.agent.title ?? "")?.[1];
+    if (!identifier || jobs.get(identifier)?.job.status === "running") return;
+    await recover(paseo, identifier).catch((error: unknown) =>
+      console.error(`Linear explore run for ${identifier} was not recovered`, error),
+    );
+  });
+
+  interface ExploreTarget {
+    identifier: string;
+    keyScope: string | null;
+    cwd: string;
+    /** Opened only when a new run starts. */
+    workspace: () => Promise<WorkspaceHandle>;
+    provider: string;
+    effort: string;
+    force: boolean;
+  }
+
+  // One explore run per issue: a running job is shared, and a saved map is reused.
+  async function ensureExplore(paseo: Paseo, target: ExploreTarget): Promise<Job> {
+    const { identifier } = target;
+    const existing = jobs.get(identifier)?.job;
+    if (existing?.status === "running" || (existing?.status === "done" && !target.force)) {
+      return existing;
+    }
+    const stored = target.force ? null : await maps.get(identifier);
+    if (stored) {
+      return { id: identifier, status: "done", agentId: null, error: null, startedAt: stored.createdAt };
+    }
+    const adopted = target.force ? null : await recover(paseo, identifier).catch(() => null);
+    if (adopted?.status === "running") return adopted;
+    const job = await jobs.start(identifier, async () => {
+      const { linear } = await access.connect(target.keyScope);
+      const issue = await linear.getIssue(identifier);
+      const labels: Record<string, string> = { [AGENT_LABELS.explore]: identifier };
+      if (target.keyScope) labels[AGENT_LABELS.project] = target.keyScope;
+      const run = await startInternalRun({
+        paseo,
+        workspace: await target.workspace(),
+        cwd: target.cwd,
+        provider: target.provider,
+        effort: target.effort,
+        title: `Explore ${identifier}`,
+        prompt: explorePrompt(issue),
+        labels,
+        schema: ExploreResultSchema,
+        timeoutMs: EXPLORE_TIMEOUT_MS,
+      });
+      return { agentId: run.agentId, result: run.result.then(saveMap(issue, target.cwd)) };
+    });
+    return track(paseo, job);
+  }
+  async function requireEnabled(projectId: string | null) {
+    const settings = await readSettings();
+    if (settings && !projectEnabled(settings.access, projectId)) {
+      throw new Error("Linear is off for this project");
+    }
+    return settings;
+  }
+
+  server.handle(exploreRpc, async ({ agentId, force }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    const identifier = agent.labels[AGENT_LABELS.issue];
+    if (!identifier) throw new Error("This agent is not linked to a Linear issue");
+    const settings = await requireEnabled(agent.projectId);
+    const { workspaceId, cwd } = agent;
+    const job = await ensureExplore(paseo, {
+      identifier,
+      keyScope: agent.labels[AGENT_LABELS.project] ?? null,
+      cwd,
+      workspace: async () =>
+        workspaceId ? paseo.workspaces.ref(workspaceId) : paseo.workspaces.open(cwd),
+      provider: settings?.live.exploreProvider || agent.provider,
+      effort: settings?.live.exploreEffort ?? "",
+      force,
+    });
+    return { job };
+  });
+
+  server.handle(launchAfterExploreRpc, async (input, { paseo }) => {
+    const workspace = paseo.workspaces.ref(input.workspaceId);
+    const info = await workspace.refresh();
+    if (!info) throw new Error("The workspace was not found");
+    const settings = await requireEnabled(info.projectId);
+    const job = await ensureExplore(paseo, {
+      identifier: input.identifier,
+      keyScope: input.keyScope,
+      cwd: info.workspaceDirectory ?? info.projectRootPath,
+      workspace: async () => workspace,
+      provider: settings?.live.exploreProvider || input.agent.config.provider,
+      effort: settings?.live.exploreEffort ?? "",
+      force: false,
+    });
+    // A failed or timed-out explore run still starts the agent; the map falls back to ticket text.
+    if (job.status !== "running") return { agentId: await startLaunch(workspace, input), job };
+    await launches.add(input);
+    // The run may have ended while the launch was saved; claiming makes a second start a no-op.
+    if (jobs.get(job.id)?.job.status !== "running") await startWaiting(paseo, input.identifier);
+    return { agentId: null, job };
+  });
+}

package/server/mcp-http.ts

@@ -0,0 +1,152 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { type ZodType, z } from "zod";
+
+// A small MCP server over HTTP for agents on this host. It sends plain JSON responses, which the
+// streamable HTTP transport allows, so it needs no sessions and no event streams.
+
+export interface McpTool<C> {
+  name: string;
+  description: string;
+  input: ZodType;
+  /** Callers that may list and call the tool; all callers when absent. */
+  allowed?(caller: C): boolean;
+  run(input: unknown, caller: C): Promise<string>;
+}
+
+/** A tool whose run gets its parsed input. */
+export function tool<S extends ZodType, C>(
+  definition: Omit<McpTool<C>, "input" | "run"> & { input: S; run(input: z.output<S>, caller: C): Promise<string> },
+): McpTool<C> {
+  return definition as unknown as McpTool<C>;
+}
+
+export interface McpOptions<C> {
+  name: string;
+  version: string;
+  tools: readonly McpTool<C>[];
+  /** The caller for a bearer token, or null to refuse the request. */
+  authorize(token: string): Promise<C | null>;
+}
+
+const VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const MAX_BODY = 1_000_000;
+
+type Message = { jsonrpc?: unknown; id?: unknown; method?: unknown; params?: unknown };
+
+const failure = (id: unknown, code: number, message: string) => ({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+const success = (id: unknown, result: unknown) => ({ jsonrpc: "2.0", id, result });
+const text = (value: string, isError = false) => ({ content: [{ type: "text", text: value }], ...(isError ? { isError } : {}) });
+
+function errorText(error: unknown): string {
+  if (error instanceof z.ZodError) return error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** The answer to one JSON-RPC message, or null for a notification. */
+export async function answer<C>(options: McpOptions<C>, message: Message, caller: C): Promise<object | null> {
+  if (typeof message !== "object" || message === null || message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+    return failure(message?.id, -32600, "Invalid request");
+  }
+  if (message.id === undefined || message.id === null) return null;
+  const params = (typeof message.params === "object" && message.params !== null ? message.params : {}) as Record<string, unknown>;
+  const tools = options.tools.filter((tool) => tool.allowed?.(caller) ?? true);
+  switch (message.method) {
+    case "initialize": {
+      const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : "";
+      return success(message.id, {
+        protocolVersion: VERSIONS.includes(asked) ? asked : VERSIONS[0],
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: options.name, version: options.version },
+      });
+    }
+    case "ping":
+      return success(message.id, {});
+    case "tools/list":
+      return success(message.id, {
+        tools: tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: z.toJSONSchema(tool.input, { io: "input" }),
+        })),
+      });
+    case "tools/call": {
+      const tool = tools.find((entry) => entry.name === params.name);
+      if (!tool) return failure(message.id, -32602, `Unknown tool: ${String(params.name)}`);
+      try {
+        return success(message.id, text(await tool.run(tool.input.parse(params.arguments ?? {}), caller)));
+      } catch (error) {
+        return success(message.id, text(errorText(error), true));
+      }
+    }
+    default:
+      return failure(message.id, -32601, `Unknown method: ${message.method}`);
+  }
+}
+
+function readBody(request: IncomingMessage): Promise<string | null> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    request.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_BODY) {
+        resolve(null);
+        request.destroy();
+      } else chunks.push(chunk);
+    });
+    request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    request.on("error", reject);
+  });
+}
+
+function send(response: ServerResponse, status: number, body?: unknown) {
+  response.writeHead(status, body === undefined ? {} : { "content-type": "application/json" });
+  response.end(body === undefined ? undefined : JSON.stringify(body));
+}
+
+// Browsers send an Origin header and agents do not, so a web page can never reach the tools.
+export function createMcpServer<C>(options: McpOptions<C>): Server {
+  return createServer(async (request, response) => {
+    try {
+      if (new URL(request.url ?? "/", "http://localhost").pathname !== "/mcp") return send(response, 404);
+      if (request.headers.origin) return send(response, 403);
+      if (request.method !== "POST") {
+        response.setHeader("allow", "POST");
+        return send(response, 405);
+      }
+      const token = /^Bearer (\S+)$/.exec(request.headers.authorization ?? "")?.[1];
+      const caller = token ? await options.authorize(token) : null;
+      if (caller === null) return send(response, 401, failure(null, -32001, "Unknown token"));
+      const raw = await readBody(request);
+      if (raw === null) return send(response, 413);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        return send(response, 400, failure(null, -32700, "Parse error"));
+      }
+      const messages = (Array.isArray(parsed) ? parsed : [parsed]) as Message[];
+      const answers = (await Promise.all(messages.map((message) => answer(options, message, caller)))).filter(Boolean);
+      if (answers.length === 0) return send(response, 202);
+      send(response, 200, Array.isArray(parsed) ? answers : answers[0]);
+    } catch (error) {
+      console.error("Linear MCP request failed", error);
+      if (!response.headersSent) send(response, 500);
+    }
+  });
+}
+
+/** Listens on 127.0.0.1, on the preferred port when it is free. Returns the port. */
+export function listenLocal(server: Server, preferred: number | null): Promise<number> {
+  const attempt = (port: number) =>
+    new Promise<number>((resolve, reject) => {
+      const fail = (error: Error) => reject(error);
+      server.once("error", fail);
+      server.listen(port, "127.0.0.1", () => {
+        server.off("error", fail);
+        resolve((server.address() as AddressInfo).port);
+      });
+    });
+  return preferred ? attempt(preferred).catch(() => attempt(0)) : attempt(0);
+}