@meetopenbot/linear 0.0.1

package/dist/tools.js

@@ -0,0 +1,290 @@
+/**
+ * Linear tool implementations. Each tool returns structured `data` for the
+ * model plus a human-readable `output` summary, and optionally a UI widget
+ * spec rendered in the OpenBot client.
+ */
+import { ISSUE_FIELDS, LinearApiError, fetchViewer, formatIssue, linearRequest, resolveTeam, } from './api.js';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function resolveIssueId(auth, idOrIdentifier) {
+    if (UUID_RE.test(idOrIdentifier))
+        return idOrIdentifier;
+    const issue = await findIssueByIdentifier(auth, idOrIdentifier);
+    return issue.id;
+}
+async function findIssueByIdentifier(auth, identifier) {
+    const data = await linearRequest(auth, `query($term: String!) { searchIssues(term: $term, first: 10) { nodes { ${ISSUE_FIELDS} } } }`, { term: identifier });
+    const match = data.searchIssues.nodes.find((n) => n.identifier.toLowerCase() === identifier.toLowerCase());
+    if (!match)
+        throw new LinearApiError(`No Linear issue found with identifier "${identifier}".`);
+    return match;
+}
+function issueListWidget(title, issues) {
+    return {
+        kind: 'list',
+        title,
+        items: issues.map((issue) => ({
+            id: issue.id,
+            label: `${issue.identifier} · ${issue.title}`,
+            description: [issue.assignee?.displayName, issue.project?.name].filter(Boolean).join(' · ') || undefined,
+            status: issue.state?.name,
+            statusVariant: issue.state?.type === 'completed'
+                ? 'success'
+                : issue.state?.type === 'started'
+                    ? 'info'
+                    : issue.state?.type === 'canceled'
+                        ? 'danger'
+                        : 'default',
+            metadata: { url: issue.url },
+        })),
+    };
+}
+export const linearTools = {
+    linear_status: {
+        definition: {
+            description: 'Check whether Linear is connected and which user/workspace the credentials belong to.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        run: async (auth) => {
+            const { viewer, organization } = await fetchViewer(auth);
+            return {
+                data: { connected: true, viewer, organization, authKind: auth.kind },
+                output: `Connected to Linear workspace "${organization.name}" as ${viewer.displayName ?? viewer.name} (${viewer.email}) via ${auth.kind === 'apiKey' ? 'API key' : 'OAuth'}.`,
+            };
+        },
+    },
+    list_teams: {
+        definition: {
+            description: 'List Linear teams, including their workflow states (useful for setting issue status).',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        run: async (auth) => {
+            const data = await linearRequest(auth, `query { teams(first: 100) { nodes { id key name states { nodes { id name type } } } } }`);
+            const teams = data.teams.nodes;
+            return {
+                data: teams,
+                output: `Found ${teams.length} team(s): ${teams.map((t) => `${t.key} (${t.name})`).join(', ')}`,
+            };
+        },
+    },
+    list_issues: {
+        definition: {
+            description: 'List Linear issues, optionally filtered by team (key, name, or id), assignee ("me" or a user id), and state type.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    team: { type: 'string', description: 'Team key (e.g. "ENG"), name, or id' },
+                    assignee: { type: 'string', description: '"me" for the connected user, or a Linear user id' },
+                    stateType: {
+                        type: 'string',
+                        enum: ['triage', 'backlog', 'unstarted', 'started', 'completed', 'canceled'],
+                        description: 'Filter by workflow state type',
+                    },
+                    limit: { type: 'number', description: 'Max issues to return (default 25)' },
+                },
+            },
+        },
+        run: async (auth, args) => {
+            const { team, assignee, stateType, limit } = args;
+            const filter = {};
+            if (team)
+                filter.team = { id: { eq: (await resolveTeam(auth, team)).id } };
+            if (stateType)
+                filter.state = { type: { eq: stateType } };
+            if (assignee) {
+                if (assignee === 'me') {
+                    const { viewer } = await fetchViewer(auth);
+                    filter.assignee = { id: { eq: viewer.id } };
+                }
+                else {
+                    filter.assignee = { id: { eq: assignee } };
+                }
+            }
+            const data = await linearRequest(auth, `query($filter: IssueFilter, $first: Int!) { issues(filter: $filter, first: $first, orderBy: updatedAt) { nodes { ${ISSUE_FIELDS} } } }`, { filter, first: Math.min(limit ?? 25, 100) });
+            const issues = data.issues.nodes;
+            return {
+                data: issues.map(formatIssue),
+                output: `Found ${issues.length} issue(s).`,
+                widget: issueListWidget('Linear Issues', issues),
+            };
+        },
+    },
+    search_issues: {
+        definition: {
+            description: 'Full-text search Linear issues by keyword.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search term' },
+                    limit: { type: 'number', description: 'Max results (default 10)' },
+                },
+                required: ['query'],
+            },
+        },
+        run: async (auth, args) => {
+            const { query, limit } = args;
+            const data = await linearRequest(auth, `query($term: String!, $first: Int!) { searchIssues(term: $term, first: $first) { nodes { ${ISSUE_FIELDS} } } }`, { term: query, first: Math.min(limit ?? 10, 50) });
+            const issues = data.searchIssues.nodes;
+            return {
+                data: issues.map(formatIssue),
+                output: `Found ${issues.length} issue(s) matching "${query}".`,
+                widget: issueListWidget(`Search: ${query}`, issues),
+            };
+        },
+    },
+    get_issue: {
+        definition: {
+            description: 'Get full details of a Linear issue by identifier (e.g. "ENG-123") or id, including comments.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    issue: { type: 'string', description: 'Issue identifier (e.g. "ENG-123") or Linear issue id' },
+                },
+                required: ['issue'],
+            },
+        },
+        run: async (auth, args) => {
+            const { issue: issueRef } = args;
+            const issueId = await resolveIssueId(auth, issueRef);
+            const data = await linearRequest(auth, `query($id: String!) { issue(id: $id) { ${ISSUE_FIELDS} comments(first: 25) { nodes { body createdAt user { displayName } } } } }`, { id: issueId });
+            const issue = data.issue;
+            const comments = issue.comments.nodes.map((c) => ({
+                author: c.user?.displayName,
+                createdAt: c.createdAt,
+                body: c.body,
+            }));
+            return {
+                data: { ...formatIssue(issue), comments },
+                output: `Retrieved ${issue.identifier}: ${issue.title} (${issue.state?.name ?? 'unknown state'}).`,
+            };
+        },
+    },
+    create_issue: {
+        definition: {
+            description: 'Create a new Linear issue.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    team: { type: 'string', description: 'Team key (e.g. "ENG"), name, or id' },
+                    title: { type: 'string', description: 'Issue title' },
+                    description: { type: 'string', description: 'Issue description (markdown)' },
+                    priority: { type: 'number', description: '0 none, 1 urgent, 2 high, 3 medium, 4 low' },
+                    assignee: { type: 'string', description: '"me" or a Linear user id' },
+                    stateId: { type: 'string', description: 'Workflow state id (see list_teams)' },
+                },
+                required: ['team', 'title'],
+            },
+        },
+        run: async (auth, args) => {
+            const { team, title, description, priority, assignee, stateId } = args;
+            const teamId = (await resolveTeam(auth, team)).id;
+            let assigneeId = assignee;
+            if (assignee === 'me')
+                assigneeId = (await fetchViewer(auth)).viewer.id;
+            const data = await linearRequest(auth, `mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { ${ISSUE_FIELDS} } } }`, { input: { teamId, title, description, priority, assigneeId, stateId } });
+            const issue = data.issueCreate.issue;
+            return {
+                data: formatIssue(issue),
+                output: `Created ${issue.identifier}: ${issue.title} — ${issue.url}`,
+            };
+        },
+    },
+    update_issue: {
+        definition: {
+            description: 'Update a Linear issue (title, description, priority, state, assignee).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    issue: { type: 'string', description: 'Issue identifier (e.g. "ENG-123") or id' },
+                    title: { type: 'string', description: 'New title' },
+                    description: { type: 'string', description: 'New description (markdown)' },
+                    priority: { type: 'number', description: '0 none, 1 urgent, 2 high, 3 medium, 4 low' },
+                    assignee: { type: 'string', description: '"me", a Linear user id, or "none" to unassign' },
+                    stateId: { type: 'string', description: 'Workflow state id (see list_teams)' },
+                },
+                required: ['issue'],
+            },
+        },
+        run: async (auth, args) => {
+            const { issue: issueRef, title, description, priority, assignee, stateId } = args;
+            const issueId = await resolveIssueId(auth, issueRef);
+            let assigneeId = assignee;
+            if (assignee === 'me')
+                assigneeId = (await fetchViewer(auth)).viewer.id;
+            if (assignee === 'none')
+                assigneeId = null;
+            const data = await linearRequest(auth, `mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { ${ISSUE_FIELDS} } } }`, { id: issueId, input: { title, description, priority, assigneeId, stateId } });
+            const issue = data.issueUpdate.issue;
+            return {
+                data: formatIssue(issue),
+                output: `Updated ${issue.identifier}: ${issue.title} (${issue.state?.name ?? 'unknown state'}).`,
+            };
+        },
+    },
+    create_comment: {
+        definition: {
+            description: 'Add a comment to a Linear issue.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    issue: { type: 'string', description: 'Issue identifier (e.g. "ENG-123") or id' },
+                    body: { type: 'string', description: 'Comment body (markdown)' },
+                },
+                required: ['issue', 'body'],
+            },
+        },
+        run: async (auth, args) => {
+            const { issue: issueRef, body } = args;
+            const issueId = await resolveIssueId(auth, issueRef);
+            await linearRequest(auth, `mutation($input: CommentCreateInput!) { commentCreate(input: $input) { success } }`, { input: { issueId, body } });
+            return {
+                data: { success: true },
+                output: `Comment added to ${issueRef}.`,
+            };
+        },
+    },
+    list_projects: {
+        definition: {
+            description: 'List Linear projects.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    limit: { type: 'number', description: 'Max projects to return (default 25)' },
+                },
+            },
+        },
+        run: async (auth, args) => {
+            const { limit } = args;
+            const data = await linearRequest(auth, `query($first: Int!) { projects(first: $first) { nodes { id name state progress url lead { displayName } } } }`, { first: Math.min(limit ?? 25, 100) });
+            const projects = data.projects.nodes;
+            return {
+                data: projects,
+                output: `Found ${projects.length} project(s): ${projects.map((p) => p.name).join(', ')}`,
+                widget: {
+                    kind: 'list',
+                    title: 'Linear Projects',
+                    items: projects.map((p) => ({
+                        id: p.id,
+                        label: p.name,
+                        description: p.lead?.displayName ? `Lead: ${p.lead.displayName}` : undefined,
+                        status: p.state,
+                        metadata: { url: p.url },
+                    })),
+                },
+            };
+        },
+    },
+    list_users: {
+        definition: {
+            description: 'List members of the Linear workspace (useful for resolving assignee ids).',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        run: async (auth) => {
+            const data = await linearRequest(auth, `query { users(first: 100) { nodes { id name displayName email active } } }`);
+            const users = data.users.nodes.filter((u) => u.active);
+            return {
+                data: users,
+                output: `Found ${users.length} active user(s).`,
+            };
+        },
+    },
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@meetopenbot/linear",
+  "version": "0.0.1",
+  "description": "Linear OAuth connect flow and MCP-backed agent for issues, projects, and comments",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meetopenbot/plugin-linear.git"
+  },
+  "keywords": [
+    "openbot",
+    "plugin",
+    "linear",
+    "oauth"
+  ],
+  "dependencies": {
+    "@ai-sdk/mcp": "^2.0.14",
+    "@ai-sdk/openai": "^4.0.15",
+    "@meetopenbot/plugin-sdk": "^0.1.8",
+    "ai": "^7.0.29",
+    "mcp-server-linear": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  }
+}

package/src/config.ts

@@ -0,0 +1,228 @@
+import type { Storage } from "@meetopenbot/plugin-sdk";
+import { refreshAccessToken, type OAuthTokens } from "./oauth.js";
+
+export const VAR_API_KEY = "LINEAR_API_KEY";
+export const VAR_ACCESS_TOKEN = "LINEAR_ACCESS_TOKEN";
+export const VAR_REFRESH_TOKEN = "LINEAR_REFRESH_TOKEN";
+export const VAR_TOKEN_EXPIRES_AT = "LINEAR_TOKEN_EXPIRES_AT";
+export const VAR_CLIENT_ID = "LINEAR_CLIENT_ID";
+
+const REFRESH_MARGIN_MS = 5 * 60 * 1000;
+
+export type LinearPluginConfig = {
+  clientId?: string;
+  clientSecret?: string;
+  apiKey?: string;
+  oauthPort?: number;
+  scopes?: string;
+  openaiApiKey?: string;
+  model?: string;
+  /** Public runtime base URL, e.g. https://my-host.com (used for OAuth webhook callback). */
+  webhookBaseUrl?: string;
+};
+
+export type LinearCredentials = {
+  accessToken: string;
+  openaiApiKey: string;
+  model: string;
+  clientId?: string;
+  clientSecret?: string;
+};
+
+type VariableValue = string | { value: string; secret: boolean } | undefined;
+
+function variableValue(
+  variables: Record<string, VariableValue>,
+  key: string,
+): string | undefined {
+  const entry = variables[key];
+  if (typeof entry === "string") return entry || undefined;
+  return entry?.value || undefined;
+}
+
+export function readLinearConfig(
+  config: Record<string, unknown>,
+): LinearPluginConfig {
+  return {
+    clientId:
+      typeof config.clientId === "string" && config.clientId.trim()
+        ? config.clientId.trim()
+        : undefined,
+    clientSecret:
+      typeof config.clientSecret === "string" && config.clientSecret.trim()
+        ? config.clientSecret.trim()
+        : undefined,
+    apiKey:
+      typeof config.apiKey === "string" && config.apiKey.trim()
+        ? config.apiKey.trim()
+        : undefined,
+    oauthPort: typeof config.oauthPort === "number" ? config.oauthPort : 4137,
+    scopes:
+      typeof config.scopes === "string" && config.scopes.trim()
+        ? config.scopes.trim()
+        : "read,write,issues:create,comments:create",
+    openaiApiKey:
+      typeof config.openaiApiKey === "string" && config.openaiApiKey.trim()
+        ? config.openaiApiKey.trim()
+        : undefined,
+    model:
+      typeof config.model === "string" && config.model.trim()
+        ? config.model.trim()
+        : undefined,
+    webhookBaseUrl:
+      typeof config.webhookBaseUrl === "string" && config.webhookBaseUrl.trim()
+        ? config.webhookBaseUrl.trim()
+        : undefined,
+  };
+}
+
+export function resolveWebhookBaseUrl(
+  config: LinearPluginConfig,
+  publicBaseUrl?: string,
+): string | undefined {
+  const explicit = config.webhookBaseUrl?.replace(/\/$/, "");
+  if (explicit) return explicit;
+  const host = publicBaseUrl?.trim().replace(/\/$/, "");
+  if (host) return host;
+  return undefined;
+}
+
+export async function saveTokens(
+  storage: Storage,
+  tokens: OAuthTokens,
+): Promise<void> {
+  await storage.createVariable({
+    key: VAR_ACCESS_TOKEN,
+    value: tokens.accessToken,
+    secret: true,
+  });
+  if (tokens.refreshToken) {
+    await storage.createVariable({
+      key: VAR_REFRESH_TOKEN,
+      value: tokens.refreshToken,
+      secret: true,
+    });
+  }
+  if (tokens.expiresAt) {
+    await storage.createVariable({
+      key: VAR_TOKEN_EXPIRES_AT,
+      value: String(tokens.expiresAt),
+      secret: false,
+    });
+  }
+}
+
+export async function clearTokens(storage: Storage): Promise<void> {
+  for (const key of [VAR_ACCESS_TOKEN, VAR_REFRESH_TOKEN, VAR_TOKEN_EXPIRES_AT]) {
+    await storage.deleteVariable({ key }).catch(() => {});
+  }
+}
+
+export function formatMissingCredentials(
+  missing: Array<"accessToken" | "openaiApiKey">,
+): string {
+  const lines = [
+    "Linear agent setup is incomplete. Configure the following in plugin config or environment variables:",
+  ];
+
+  if (missing.includes("accessToken")) {
+    lines.push(
+      "- Connect Linear with `linear_connect`, or set `apiKey` / `LINEAR_API_KEY`",
+    );
+  }
+  if (missing.includes("openaiApiKey")) {
+    lines.push(
+      "- `openaiApiKey` / `OPENAI_API_KEY` — OpenAI API key for the agent loop",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export async function resolveLinearCredentials(
+  config: LinearPluginConfig,
+  storage: Storage,
+  options?: { requireOpenAi?: boolean },
+): Promise<
+  | { ok: true; credentials: LinearCredentials }
+  | { ok: false; missing: Array<"accessToken" | "openaiApiKey"> }
+> {
+  const requireOpenAi = options?.requireOpenAi ?? true;
+  const variables = (await storage.getVariables().catch(() => ({}))) as Record<
+    string,
+    VariableValue
+  >;
+
+  const resolve = (configKey: keyof LinearPluginConfig, envKey: string) => {
+    const fromConfig = config[configKey];
+    if (typeof fromConfig === "string" && fromConfig.trim()) {
+      return fromConfig.trim();
+    }
+    if (process.env[envKey]?.trim()) return process.env[envKey]!.trim();
+    return variableValue(variables, envKey)?.trim();
+  };
+
+  const openaiApiKey = resolve("openaiApiKey", "OPENAI_API_KEY");
+  const model = resolve("model", "OPENAI_MODEL") ?? "gpt-4o-mini";
+
+  let accessToken =
+    config.apiKey ??
+    variableValue(variables, VAR_API_KEY) ??
+    process.env[VAR_API_KEY] ??
+    variableValue(variables, VAR_ACCESS_TOKEN) ??
+    process.env[VAR_ACCESS_TOKEN];
+
+  const clientId =
+    config.clientId ??
+    variableValue(variables, VAR_CLIENT_ID) ??
+    process.env[VAR_CLIENT_ID];
+  const clientSecret = config.clientSecret;
+
+  if (accessToken && !config.apiKey) {
+    const expiresAtRaw =
+      variableValue(variables, VAR_TOKEN_EXPIRES_AT) ??
+      process.env[VAR_TOKEN_EXPIRES_AT];
+    const expiresAt = expiresAtRaw ? Number(expiresAtRaw) : undefined;
+    const refreshToken =
+      variableValue(variables, VAR_REFRESH_TOKEN) ??
+      process.env[VAR_REFRESH_TOKEN];
+
+    const needsRefresh =
+      expiresAt !== undefined &&
+      Number.isFinite(expiresAt) &&
+      Date.now() > expiresAt - REFRESH_MARGIN_MS;
+
+    if (needsRefresh && refreshToken && clientId) {
+      try {
+        const tokens = await refreshAccessToken({
+          refreshToken,
+          clientId,
+          clientSecret,
+        });
+        await saveTokens(storage, tokens);
+        accessToken = tokens.accessToken;
+      } catch {
+        // Fall through; a 401 from Linear will prompt reconnect.
+      }
+    }
+  }
+
+  const missing: Array<"accessToken" | "openaiApiKey"> = [];
+  if (!accessToken) missing.push("accessToken");
+  if (requireOpenAi && !openaiApiKey) missing.push("openaiApiKey");
+
+  if (missing.length > 0) {
+    return { ok: false, missing };
+  }
+
+  return {
+    ok: true,
+    credentials: {
+      accessToken: accessToken!,
+      openaiApiKey: openaiApiKey ?? "",
+      model,
+      clientId,
+      clientSecret,
+    },
+  };
+}