@nimbus-dev/connectors 0.1.0

package/connectors/linear/src/server.ts

@@ -0,0 +1,467 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+  requireProcessEnv,
+} from "../../../shared/mcp-tool-kit.ts";
+
+const LINEAR_GQL = "https://api.linear.app/graphql";
+
+type LinearGqlResponse<T> = {
+  data?: T;
+  errors?: ReadonlyArray<{ message: string }>;
+};
+
+async function linearGraphql<T>(
+  apiKey: string,
+  query: string,
+  variables?: Record<string, unknown>,
+): Promise<{ ok: true; data: T; text: string } | { ok: false; status: number; text: string }> {
+  const res = await fetch(LINEAR_GQL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: apiKey,
+    },
+    body: JSON.stringify({ query, variables }),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    return { ok: false, status: res.status, text };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text) as unknown;
+  } catch {
+    return { ok: false, status: res.status, text: "invalid JSON" };
+  }
+  const body = parsed as LinearGqlResponse<T>;
+  if (body.errors !== undefined && body.errors.length > 0) {
+    const msg = body.errors.map((e) => e.message).join("; ");
+    throw new Error(`Linear GraphQL: ${msg.slice(0, 400)}`);
+  }
+  if (body.data === undefined) {
+    throw new Error("Linear GraphQL: missing data");
+  }
+  return { ok: true, data: body.data, text };
+}
+
+function linearGqlData<T>(
+  res: { ok: true; data: T; text: string } | { ok: false; status: number; text: string },
+): T {
+  if (!res.ok) {
+    throw new Error(`Linear ${String(res.status)}: ${res.text.slice(0, 300)}`);
+  }
+  return res.data;
+}
+
+const server = new McpServer({ name: "nimbus-linear", version: "0.1.0" });
+
+const registerSimpleTool = createRegisterSimpleTool(server);
+
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+const reg = createZodToolRegistrar(registerSimpleTool);
+
+/**
+ * Every MUTATING linear tool goes through here. Outside the gateway this adds the
+ * consent gate, the write-scope allow-list, the mutation budget and the audit record; inside
+ * the gateway it is a pass-through, because executor.ts (I2) is the gate there.
+ */
+const registerWriteTool = createWriteToolRegistrar(server, {
+  connector: "linear",
+  scopeEnv: "NIMBUS_MCP_LINEAR_WRITE_SCOPE",
+  scopeKinds: ["team", "issue"],
+});
+
+const linearIssueListSchema = z.object({
+  first: z.number().int().min(1).max(100).optional(),
+  teamId: z.string().min(1).optional(),
+  stateName: z.string().min(1).optional(),
+  assigneeId: z.string().min(1).optional(),
+});
+
+reg(
+  "linear_issue_list",
+  "List Linear issues with optional filters (team id, state name, assignee id).",
+  linearIssueListSchema,
+  async (parsed) => {
+    const apiKey = requireProcessEnv("LINEAR_API_KEY");
+    const filter: Record<string, unknown> = {};
+    if (parsed.teamId !== undefined) {
+      filter["team"] = { id: { eq: parsed.teamId } };
+    }
+    if (parsed.stateName !== undefined) {
+      filter["state"] = { name: { eq: parsed.stateName } };
+    }
+    if (parsed.assigneeId !== undefined) {
+      filter["assignee"] = { id: { eq: parsed.assigneeId } };
+    }
+    const hasFilter = Object.keys(filter).length > 0;
+    const q = hasFilter
+      ? `
+      query IssueList($first: Int!, $filter: IssueFilter!) {
+        issues(first: $first, filter: $filter, orderBy: updatedAt) {
+          nodes {
+            id
+            identifier
+            title
+            updatedAt
+            url
+            state { id name type }
+            team { id name key }
+          }
+        }
+      }
+    `
+      : `
+      query IssueList($first: Int!) {
+        issues(first: $first, orderBy: updatedAt) {
+          nodes {
+            id
+            identifier
+            title
+            updatedAt
+            url
+            state { id name type }
+            team { id name key }
+          }
+        }
+      }
+    `;
+    type Out = {
+      issues: {
+        nodes: ReadonlyArray<Record<string, unknown>>;
+      };
+    };
+    const vars: Record<string, unknown> = { first: parsed.first ?? 50 };
+    if (hasFilter) {
+      vars["filter"] = filter;
+    }
+    const res = await linearGraphql<Out>(apiKey, q, vars);
+    return jsonResult(linearGqlData(res));
+  },
+);
+
+const linearIssueIdSchema = z.object({ issueId: z.string().min(1) });
+
+reg(
+  "linear_issue_get",
+  "Get a single Linear issue by UUID id.",
+  linearIssueIdSchema,
+  async (parsed) => {
+    const apiKey = requireProcessEnv("LINEAR_API_KEY");
+    const q = `
+      query IssueGet($id: String!) {
+        issue(id: $id) {
+          id
+          identifier
+          title
+          description
+          updatedAt
+          createdAt
+          url
+          priority
+          state { id name type }
+          team { id name key }
+          assignee { id name displayName }
+        }
+      }
+    `;
+    type Out = { issue: Record<string, unknown> | null };
+    const res = await linearGraphql<Out>(apiKey, q, { id: parsed.issueId });
+    return jsonResult(linearGqlData(res));
+  },
+);
+
+const linearIssueCreateSchema = z.object({
+  teamId: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string().optional(),
+  priority: z.number().int().min(0).max(4).optional(),
+  stateId: z.string().min(1).optional(),
+  assigneeId: z.string().min(1).optional(),
+});
+
+registerWriteTool(
+  "linear_issue_create",
+  {
+    mutates: "linear.issue.create",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "team", value: p.teamId }),
+  },
+  "Create a Linear issue (requires teamId and title).",
+  linearIssueCreateSchema,
+  async (parsed) => {
+    const apiKey = requireProcessEnv("LINEAR_API_KEY");
+    const input: Record<string, unknown> = {
+      teamId: parsed.teamId,
+      title: parsed.title,
+    };
+    if (parsed.description !== undefined) {
+      input["description"] = parsed.description;
+    }
+    if (parsed.priority !== undefined) {
+      input["priority"] = parsed.priority;
+    }
+    if (parsed.stateId !== undefined) {
+      input["stateId"] = parsed.stateId;
+    }
+    if (parsed.assigneeId !== undefined) {
+      input["assigneeId"] = parsed.assigneeId;
+    }
+    const q = `
+      mutation IssueCreate($input: IssueCreateInput!) {
+        issueCreate(input: $input) {
+          success
+          issue { id identifier url title }
+        }
+      }
+    `;
+    type Out = { issueCreate: { success: boolean; issue: Record<string, unknown> | null } };
+    const res = await linearGraphql<Out>(apiKey, q, { input });
+    return jsonResult(linearGqlData(res));
+  },
+);
+
+const linearIssueUpdateSchema = z.object({
+  issueId: z.string().min(1),
+  title: z.string().min(1).optional(),
+  description: z.string().optional(),
+  stateId: z.string().min(1).optional(),
+  priority: z.number().int().min(0).max(4).optional(),
+  assigneeId: z.string().min(1).optional(),
+});
+
+registerWriteTool(
+  "linear_issue_update",
+  {
+    mutates: "linear.issue.update",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "issue", value: p.issueId }),
+  },
+  "Update a Linear issue by id.",
+  linearIssueUpdateSchema,
+  async (parsed) => {
+    const apiKey = requireProcessEnv("LINEAR_API_KEY");
+    const input: Record<string, unknown> = {};
+    if (parsed.title !== undefined) {
+      input["title"] = parsed.title;
+    }
+    if (parsed.description !== undefined) {
+      input["description"] = parsed.description;
+    }
+    if (parsed.stateId !== undefined) {
+      input["stateId"] = parsed.stateId;
+    }
+    if (parsed.priority !== undefined) {
+      input["priority"] = parsed.priority;
+    }
+    if (parsed.assigneeId !== undefined) {
+      input["assigneeId"] = parsed.assigneeId;
+    }
+    const q = `
+      mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) {
+        issueUpdate(id: $id, input: $input) {
+          success
+          issue { id identifier url title updatedAt }
+        }
+      }
+    `;
+    type Out = {
+      issueUpdate: { success: boolean; issue: Record<string, unknown> | null };
+    };
+    const res = await linearGraphql<Out>(apiKey, q, {
+      id: parsed.issueId,
+      input,
+    });
+    return jsonResult(linearGqlData(res));
+  },
+);
+
+const linearCommentCreateSchema = z.object({
+  issueId: z.string().min(1),
+  body: z.string().min(1),
+});
+
+registerWriteTool(
+  "linear_comment_create",
+  {
+    mutates: "linear.comment.create",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "issue", value: p.issueId }),
+  },
+  "Add a comment to a Linear issue.",
+  linearCommentCreateSchema,
+  async (parsed) => {
+    const apiKey = requireProcessEnv("LINEAR_API_KEY");
+    const q = `
+      mutation CommentCreate($input: CommentCreateInput!) {
+        commentCreate(input: $input) {
+          success
+          comment { id body createdAt }
+        }
+      }
+    `;
+    type Out = {
+      commentCreate: { success: boolean; comment: Record<string, unknown> | null };
+    };
+    const res = await linearGraphql<Out>(apiKey, q, {
+      input: { issueId: parsed.issueId, body: parsed.body },
+    });
+    return jsonResult(linearGqlData(res));
+  },
+);
+
+const linearFirstOptionalSchema = z.object({
+  first: z.number().int().min(1).max(100).optional(),
+});
+
+reg("linear_project_list", "List Linear projects.", linearFirstOptionalSchema, async (parsed) => {
+  const apiKey = requireProcessEnv("LINEAR_API_KEY");
+  const q = `
+      query ProjectList($first: Int!) {
+        projects(first: $first) {
+          nodes {
+            id
+            name
+            description
+            slugId
+            url
+            updatedAt
+            state
+          }
+        }
+      }
+    `;
+  type Out = { projects: { nodes: ReadonlyArray<Record<string, unknown>> } };
+  const res = await linearGraphql<Out>(apiKey, q, { first: parsed.first ?? 50 });
+  return jsonResult(linearGqlData(res));
+});
+
+const linearProjectIdSchema = z.object({ projectId: z.string().min(1) });
+
+reg("linear_project_get", "Get a Linear project by id.", linearProjectIdSchema, async (parsed) => {
+  const apiKey = requireProcessEnv("LINEAR_API_KEY");
+  const q = `
+      query ProjectGet($id: String!) {
+        project(id: $id) {
+          id
+          name
+          description
+          slugId
+          url
+          updatedAt
+          state
+          lead { id displayName }
+        }
+      }
+    `;
+  type Out = { project: Record<string, unknown> | null };
+  const res = await linearGraphql<Out>(apiKey, q, { id: parsed.projectId });
+  return jsonResult(linearGqlData(res));
+});
+
+const linearCycleListSchema = z.object({
+  teamId: z.string().min(1),
+  first: z.number().int().min(1).max(50).optional(),
+});
+
+reg(
+  "linear_cycle_list",
+  "List Linear cycles for a team.",
+  linearCycleListSchema,
+  async (parsed) => {
+    const apiKey = requireProcessEnv("LINEAR_API_KEY");
+    const q = `
+      query CycleList($teamId: ID!, $first: Int!) {
+        team(id: $teamId) {
+          id
+          cycles(first: $first) {
+            nodes {
+              id
+              name
+              number
+              startsAt
+              endsAt
+              completedAt
+            }
+          }
+        }
+      }
+    `;
+    type Out = {
+      team: {
+        id: string;
+        cycles: { nodes: ReadonlyArray<Record<string, unknown>> };
+      } | null;
+    };
+    const res = await linearGraphql<Out>(apiKey, q, {
+      teamId: parsed.teamId,
+      first: parsed.first ?? 20,
+    });
+    return jsonResult(linearGqlData(res));
+  },
+);
+
+const linearRoadmapFirstSchema = z.object({
+  first: z.number().int().min(1).max(50).optional(),
+});
+
+reg(
+  "linear_roadmap_list",
+  "List Linear initiatives (roadmap).",
+  linearRoadmapFirstSchema,
+  async (parsed) => {
+    const apiKey = requireProcessEnv("LINEAR_API_KEY");
+    const q = `
+      query InitiativeList($first: Int!) {
+        initiatives(first: $first) {
+          nodes {
+            id
+            name
+            description
+            targetDate
+            updatedAt
+            url
+          }
+        }
+      }
+    `;
+    type Out = { initiatives: { nodes: ReadonlyArray<Record<string, unknown>> } };
+    const res = await linearGraphql<Out>(apiKey, q, { first: parsed.first ?? 30 });
+    return jsonResult(linearGqlData(res));
+  },
+);
+
+reg(
+  "linear_member_list",
+  "List users in the workspace.",
+  linearFirstOptionalSchema,
+  async (parsed) => {
+    const apiKey = requireProcessEnv("LINEAR_API_KEY");
+    const q = `
+      query Users($first: Int!) {
+        users(first: $first) {
+          nodes {
+            id
+            name
+            displayName
+            email
+            active
+          }
+        }
+      }
+    `;
+    type Out = { users: { nodes: ReadonlyArray<Record<string, unknown>> } };
+    const res = await linearGraphql<Out>(apiKey, q, { first: parsed.first ?? 50 });
+    return jsonResult(linearGqlData(res));
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/localdb/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.localdb",
+  "displayName": "Local DB Schema / Saved Queries",
+  "version": "0.1.0",
+  "description": "Local DB Schema Indexing connector (Tier-5 local class). Indexes saved SQL queries and schema scripts that local database tools (DBeaver, DataGrip, pgAdmin) keep on disk as `.sql` files, as `localdb:saved_query` items — the SQL TEXT (capped) plus lightweight metadata (relative path, referenced table names, statement count, size). This enables semantic recall of 'that one SQL query I wrote last month' without any live database connection. It is a pure, bounded, path-traversal-guarded filesystem read: NO database is ever connected to, NO query is ever executed, and NO binary is spawned. The user points the connector at the directory their DB tool stores scripts/consoles in via the non-secret path `localdb.scripts_dir`; read tools are `localdb_list`, `localdb_get`, `localdb_search`. The configured scripts directory arrives as the scoped environment variable LOCALDB_SCRIPTS_DIR and is added to the sandbox filesystem.read allow-list at spawn time. No network access.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/localdb/src/server.ts

@@ -0,0 +1,6 @@
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { registerLocaldbTools } from "./tools.ts";
+
+await runReadOnlyMcpConnector("nimbus-localdb", (reg) => {
+  registerLocaldbTools(reg);
+});

package/connectors/localdb/src/sql-scan.ts

@@ -0,0 +1,158 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/**
+ * Local-only reader for saved SQL queries. This module is the MCP-server-side
+ * counterpart of the gateway's `mapLocalDbQueryToItem` mapper: it reads `.sql`
+ * files from the configured local DB-tool scripts dir (DBeaver/DataGrip/pgAdmin
+ * exports) and returns their TEXT + lightweight metadata for semantic recall.
+ *
+ * No database is ever connected to and no query is ever executed — this is a
+ * pure filesystem read, bounded and path-traversal-guarded.
+ */
+
+const MAX_FILES = 2000;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_WALK_DEPTH = 12;
+const PREVIEW_MAX_CHARS = 4000;
+
+export interface SavedQuery {
+  /** Path relative to the configured scripts dir — the stable id. */
+  readonly relativePath: string;
+  readonly title: string;
+  readonly sizeBytes: number;
+  readonly lineCount: number;
+  /** SQL text, capped. */
+  readonly preview: string;
+}
+
+function clamp(s: string, max: number): string {
+  return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+
+export function baseTitle(relativePath: string): string {
+  const segments = relativePath.split(/[/\\]/);
+  const last = segments.at(-1) ?? relativePath;
+  return last.replace(/\.sql$/i, "");
+}
+
+/**
+ * Resolve the configured scripts dir from the environment. Throws when unset so
+ * the MCP tools surface a clear error rather than reading an empty path.
+ */
+export function scriptsDir(): string {
+  const dir = process.env["LOCALDB_SCRIPTS_DIR"]?.trim();
+  if (dir === undefined || dir === "") {
+    throw new Error("LOCALDB_SCRIPTS_DIR is not set");
+  }
+  return resolve(dir);
+}
+
+/**
+ * Path-traversal guard: confirm `candidate` (an absolute resolved path) is the
+ * scripts dir itself or a descendant. Rejects `..`-escaping inputs.
+ */
+export function assertWithinScriptsDir(candidate: string, root: string): void {
+  const rel = relative(root, candidate);
+  if (rel === "") {
+    return;
+  }
+  if (rel.startsWith("..") || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error("path escapes the configured local DB scripts dir");
+  }
+}
+
+async function collectSqlFiles(root: string): Promise<string[]> {
+  const found: string[] = [];
+  async function walk(dir: string, depth: number): Promise<void> {
+    if (depth > MAX_WALK_DEPTH || found.length >= MAX_FILES) {
+      return;
+    }
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (found.length >= MAX_FILES) {
+        return;
+      }
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full, depth + 1);
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".sql")) {
+        found.push(full);
+      }
+    }
+  }
+  await walk(root, 0);
+  return found;
+}
+
+async function readSavedQuery(path: string, root: string): Promise<SavedQuery | null> {
+  try {
+    const buf = await readFile(path);
+    if (buf.byteLength > MAX_FILE_BYTES) {
+      return null;
+    }
+    const sql = buf.toString("utf8");
+    if (sql.trim() === "") {
+      return null;
+    }
+    let sizeBytes = buf.byteLength;
+    try {
+      const info = await stat(path);
+      sizeBytes = Number.isFinite(info.size) ? info.size : buf.byteLength;
+    } catch {
+      sizeBytes = buf.byteLength;
+    }
+    const relativePath = relative(root, path);
+    return {
+      relativePath,
+      title: baseTitle(relativePath) || relativePath,
+      sizeBytes,
+      lineCount: sql.split("\n").length,
+      preview: clamp(sql, PREVIEW_MAX_CHARS),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Read all saved `.sql` queries under the configured scripts dir (bounded). */
+export async function scanSavedQueries(): Promise<SavedQuery[]> {
+  const root = scriptsDir();
+  const files = await collectSqlFiles(root);
+  const out: SavedQuery[] = [];
+  for (const file of files) {
+    assertWithinScriptsDir(file, root);
+    const q = await readSavedQuery(file, root);
+    if (q !== null) {
+      out.push(q);
+    }
+  }
+  return out;
+}
+
+/** Read one saved query by its relative path (path-guarded). */
+export async function getSavedQuery(relativePath: string): Promise<SavedQuery | null> {
+  const root = scriptsDir();
+  const candidate = resolve(root, relativePath);
+  assertWithinScriptsDir(candidate, root);
+  return readSavedQuery(candidate, root);
+}
+
+/** Substring search over saved-query title / relative path / SQL text. */
+export function filterSavedQueries(queries: readonly SavedQuery[], query: string): SavedQuery[] {
+  const q = query.trim().toLowerCase();
+  if (q === "") {
+    return [...queries];
+  }
+  return queries.filter(
+    (sq) =>
+      sq.title.toLowerCase().includes(q) ||
+      sq.relativePath.toLowerCase().includes(q) ||
+      sq.preview.toLowerCase().includes(q),
+  );
+}