@nimbus-dev/connectors 0.1.0

package/connectors/confluence/src/server.ts

@@ -0,0 +1,309 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  fetchAtlassianBasicAuthJsonText,
+  normalizeRequiredSiteBaseUrl,
+  requireTrimmedEnv,
+} from "../../../shared/atlassian-json-fetch.ts";
+import { joinApiPath } from "../../../shared/join-api-path.ts";
+import { parseCitationsJson } from "../../../shared/kb-markdown.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResultFromTextIfOk,
+} from "../../../shared/mcp-tool-kit.ts";
+import { buildConfluenceKbPageBody } from "./kb-append.ts";
+
+function wikiRoot(siteBase: string): string {
+  const b = normalizeRequiredSiteBaseUrl(siteBase, "CONFLUENCE_BASE_URL is empty");
+  return b.endsWith("/wiki") ? b : `${b}/wiki`;
+}
+
+function requireConfluenceConfig(): { wikiApi: string; email: string; token: string } {
+  const baseRaw = requireTrimmedEnv("CONFLUENCE_BASE_URL", "CONFLUENCE_BASE_URL is not set");
+  const email = requireTrimmedEnv("CONFLUENCE_EMAIL", "CONFLUENCE_EMAIL is not set");
+  const token = requireTrimmedEnv("CONFLUENCE_API_TOKEN", "CONFLUENCE_API_TOKEN is not set");
+  return {
+    wikiApi: `${wikiRoot(baseRaw)}/rest/api`,
+    email,
+    token,
+  };
+}
+
+async function confFetch(
+  path: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; text: string }> {
+  const { wikiApi, email, token } = requireConfluenceConfig();
+  const url = joinApiPath(wikiApi, path);
+  return fetchAtlassianBasicAuthJsonText(url, email, token, init);
+}
+
+const server = new McpServer({ name: "nimbus-confluence", version: "0.1.0" });
+
+const registerSimpleTool = createRegisterSimpleTool(server);
+
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+const reg = createZodToolRegistrar(registerSimpleTool);
+
+/**
+ * Every MUTATING confluence 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: "confluence",
+  scopeEnv: "NIMBUS_MCP_CONFLUENCE_WRITE_SCOPE",
+  scopeKinds: ["space", "page"],
+});
+
+const confluenceLimitStartSchema = z.object({
+  limit: z.number().int().min(1).max(100).optional(),
+  start: z.number().int().min(0).optional(),
+});
+
+reg(
+  "confluence_space_list",
+  "List Confluence spaces (GET /space).",
+  confluenceLimitStartSchema,
+  async (parsed) => {
+    const qs = new URLSearchParams({
+      limit: String(parsed.limit ?? 25),
+      start: String(parsed.start ?? 0),
+    });
+    const res = await confFetch(`/space?${qs.toString()}`);
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+const confluenceSpaceContentSchema = z.object({
+  spaceKey: z.string().min(1),
+  limit: z.number().int().min(1).max(100).optional(),
+  start: z.number().int().min(0).optional(),
+});
+
+reg(
+  "confluence_page_list",
+  "List pages in a space (GET /content, type=page).",
+  confluenceSpaceContentSchema,
+  async (parsed) => {
+    const qs = new URLSearchParams({
+      type: "page",
+      spaceKey: parsed.spaceKey,
+      limit: String(parsed.limit ?? 50),
+      start: String(parsed.start ?? 0),
+      expand: "history.lastUpdated,version",
+    });
+    const res = await confFetch(`/content?${qs.toString()}`);
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+const confluencePageIdSchema = z.object({ pageId: z.string().min(1) });
+
+reg(
+  "confluence_page_get",
+  "Get a Confluence page with body.storage (GET /content/{id}).",
+  confluencePageIdSchema,
+  async (parsed) => {
+    const id = encodeURIComponent(parsed.pageId);
+    const res = await confFetch(
+      `/content/${id}?expand=body.storage,version,history.lastUpdated,space`,
+    );
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+reg(
+  "confluence_blogpost_list",
+  "List blog posts in a space (GET /content, type=blogpost).",
+  confluenceSpaceContentSchema,
+  async (parsed) => {
+    const qs = new URLSearchParams({
+      type: "blogpost",
+      spaceKey: parsed.spaceKey,
+      limit: String(parsed.limit ?? 25),
+      start: String(parsed.start ?? 0),
+      expand: "history.lastUpdated,version",
+    });
+    const res = await confFetch(`/content?${qs.toString()}`);
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+const confluencePostIdSchema = z.object({ postId: z.string().min(1) });
+
+reg(
+  "confluence_blogpost_get",
+  "Get a blog post by id (GET /content/{id}).",
+  confluencePostIdSchema,
+  async (parsed) => {
+    const id = encodeURIComponent(parsed.postId);
+    const res = await confFetch(
+      `/content/${id}?expand=body.storage,version,history.lastUpdated,space`,
+    );
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+const confluenceCommentListSchema = z.object({
+  pageId: z.string().min(1),
+  limit: z.number().int().min(1).max(100).optional(),
+  start: z.number().int().min(0).optional(),
+});
+
+reg(
+  "confluence_comment_list",
+  "List footer comments on a page (GET /content/{id}/child/comment).",
+  confluenceCommentListSchema,
+  async (parsed) => {
+    const id = encodeURIComponent(parsed.pageId);
+    const qs = new URLSearchParams({
+      limit: String(parsed.limit ?? 50),
+      start: String(parsed.start ?? 0),
+      expand: "body.storage,version",
+    });
+    const res = await confFetch(`/content/${id}/child/comment?${qs.toString()}`);
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+const confluencePageCreateSchema = z.object({
+  spaceKey: z.string().min(1),
+  title: z.string().min(1),
+  storageHtml: z.string().min(1),
+  parentPageId: z.string().min(1).optional(),
+});
+
+registerWriteTool(
+  "confluence_page_create",
+  {
+    mutates: "confluence.page.create",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "space", value: p.spaceKey }),
+  },
+  "Create a page in a space (POST /content). Optional parentPageId.",
+  confluencePageCreateSchema,
+  async (parsed) => {
+    const body: Record<string, unknown> = {
+      type: "page",
+      title: parsed.title,
+      space: { key: parsed.spaceKey },
+      body: {
+        storage: {
+          value: parsed.storageHtml,
+          representation: "storage",
+        },
+      },
+    };
+    if (parsed.parentPageId !== undefined) {
+      body["ancestors"] = [{ id: parsed.parentPageId }];
+    }
+    const res = await confFetch("/content", { method: "POST", body: JSON.stringify(body) });
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+const confluenceKbAppendSchema = z.object({
+  spaceKey: z.string().min(1),
+  parentPageId: z.string().min(1),
+  title: z.string().min(1),
+  bodyMarkdown: z.string().min(1),
+  citationsJson: z.string().optional(),
+});
+
+registerWriteTool(
+  "confluence_kb_append",
+  {
+    mutates: "confluence.knowledge.write",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "space", value: p.spaceKey }),
+  },
+  "Create a knowledge-base page under a parent from simple markdown + citations (POST /content). " +
+    "Used by Nimbus tribal-knowledge capture; the destination space/parent is supplied by the gateway from local config only.",
+  confluenceKbAppendSchema,
+  async (parsed) => {
+    const body = buildConfluenceKbPageBody({
+      spaceKey: parsed.spaceKey,
+      parentPageId: parsed.parentPageId,
+      title: parsed.title,
+      bodyMarkdown: parsed.bodyMarkdown,
+      citations: parseCitationsJson(parsed.citationsJson ?? "[]"),
+    });
+    const res = await confFetch("/content", { method: "POST", body: JSON.stringify(body) });
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+const confluencePageUpdateSchema = z.object({
+  pageId: z.string().min(1),
+  versionNumber: z.number().int().min(1),
+  title: z.string().min(1),
+  storageHtml: z.string().min(1),
+});
+
+registerWriteTool(
+  "confluence_page_update",
+  {
+    mutates: "confluence.page.update",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "page", value: p.pageId }),
+  },
+  "Update page body and bump version (PUT /content/{id}). Pass current version number and title.",
+  confluencePageUpdateSchema,
+  async (parsed) => {
+    const id = encodeURIComponent(parsed.pageId);
+    const body: Record<string, unknown> = {
+      type: "page",
+      title: parsed.title,
+      version: { number: parsed.versionNumber + 1, message: "nimbus" },
+      body: {
+        storage: {
+          value: parsed.storageHtml,
+          representation: "storage",
+        },
+      },
+    };
+    const res = await confFetch(`/content/${id}`, { method: "PUT", body: JSON.stringify(body) });
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+const confluenceCommentAddSchema = z.object({
+  pageId: z.string().min(1),
+  storageHtml: z.string().min(1),
+});
+
+registerWriteTool(
+  "confluence_comment_add",
+  {
+    mutates: "confluence.comment.add",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "page", value: p.pageId }),
+  },
+  "Add a footer comment to a page (POST /content/{id}/child/comment).",
+  confluenceCommentAddSchema,
+  async (parsed) => {
+    const id = encodeURIComponent(parsed.pageId);
+    const body = {
+      type: "comment",
+      container: { id: parsed.pageId, type: "page" },
+      body: {
+        storage: {
+          value: parsed.storageHtml,
+          representation: "storage",
+        },
+      },
+    };
+    const res = await confFetch(`/content/${id}/child/comment`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+    return mcpJsonResultFromTextIfOk("Confluence", res);
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/dagster/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.dagster",
+  "displayName": "Dagster",
+  "version": "0.1.0",
+  "description": "Dagster connector (read-only). Surfaces the user's data-orchestration jobs from a Dagster Cloud deployment or a self-hosted Dagster OSS instance as dagster:job items in the local index — each job's name, repository, code location, description, isJob flag, and tags. Useful for answering orchestration questions (\"which jobs live in the analytics repository?\", \"what tags does the nightly job carry?\") without leaving Nimbus. Dagster exposes a single GraphQL endpoint at <base_url>/graphql; auth is the Dagster-Cloud-Api-Token header (required for Dagster Cloud; self-hosted OSS users may set any non-empty placeholder). Dagster has no universal SaaS host: the per-tenant host root is supplied via the dagster base_url vault key and added to the sandbox network list at spawn time by phase3AddDagsterMcp, so the static manifest network list is intentionally empty. The list query walks the repositories→jobs catalog (repositoriesOrError → nodes[].pipelines[]) in one response and flattens to jobs, capturing each job's repository + location; a PythonError typename or a top-level GraphQL errors array degrades gracefully. v1 indexes jobs only — runs and assets are a deferred follow-up. No write tools.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/dagster/src/search-filter.ts

@@ -0,0 +1,53 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type DagsterSearchMatchOptions = SearchMatchOptions;
+
+/** Dagster pipeline tags are `{ key, value }` objects, not bare strings. */
+function tagText(row: Record<string, unknown>): string {
+  const tags = row["tags"];
+  if (!Array.isArray(tags)) {
+    return "";
+  }
+  const parts: string[] = [];
+  for (const t of tags) {
+    const tr = asObjectish(t);
+    if (tr === undefined) {
+      continue;
+    }
+    const key = stringField(tr, "key");
+    const value = stringField(tr, "value");
+    if (key !== "") {
+      parts.push(key);
+    }
+    if (value !== "") {
+      parts.push(value);
+    }
+  }
+  return parts.join(" ");
+}
+
+/**
+ * The connector flattens each job to a row carrying its name, repository,
+ * location, plus the raw pipeline fields (description, tags). Search matches the
+ * query against all of those.
+ */
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "name"),
+    stringField(row, "repository"),
+    stringField(row, "location"),
+    stringField(row, "description"),
+    tagText(row),
+  ];
+}
+
+export const filterDagsterJobs = makeQueryFilter(fieldsOf);

package/connectors/dagster/src/server.ts

@@ -0,0 +1,218 @@
+import { z } from "zod";
+import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterDagsterJobs } from "./search-filter.ts";
+
+function trimTrailingSlash(s: string): string {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+
+function apiBase(): string {
+  const v = process.env["DAGSTER_BASE_URL"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("DAGSTER_BASE_URL is not set");
+  }
+  return trimTrailingSlash(v);
+}
+
+function apiToken(): string {
+  // Required for Dagster Cloud; self-hosted OSS may use a placeholder. The
+  // gateway injects it regardless to keep spawn wiring uniform.
+  const v = process.env["DAGSTER_API_TOKEN"]?.trim();
+  if (v === undefined || v === "") {
+    throw new Error("DAGSTER_API_TOKEN is not set");
+  }
+  return v;
+}
+
+const JOBS_QUERY = `
+query NimbusJobs {
+  repositoriesOrError {
+    __typename
+    ... on RepositoryConnection {
+      nodes {
+        name
+        location { name }
+        pipelines { id name description isJob tags { key value } }
+      }
+    }
+    ... on PythonError { message }
+  }
+}
+`;
+
+async function dagsterGraphql<T>(query: string): Promise<T> {
+  const res = await fetch(`${apiBase()}/graphql`, {
+    method: "POST",
+    headers: {
+      "Dagster-Cloud-Api-Token": apiToken(),
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify({ query }),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Dagster ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  const parsed = JSON.parse(text) as { data?: T; errors?: unknown };
+  if (parsed.errors !== undefined) {
+    throw new Error(`Dagster GraphQL error: ${JSON.stringify(parsed.errors).slice(0, 400)}`);
+  }
+  if (parsed.data === undefined) {
+    throw new Error("Dagster GraphQL: response missing `data` field");
+  }
+  return parsed.data;
+}
+
+interface FlatJob {
+  name: string;
+  repository: string;
+  location: string | null;
+  id: string | null;
+  description: string | null;
+  isJob: boolean;
+  tags: Array<{ key: string; value: string }>;
+}
+
+function asRecord(v: unknown): Record<string, unknown> | undefined {
+  return v !== null && typeof v === "object" && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : undefined;
+}
+
+function str(row: Record<string, unknown>, key: string): string | null {
+  const v = row[key];
+  return typeof v === "string" && v !== "" ? v : null;
+}
+
+function tagPairs(raw: unknown): Array<{ key: string; value: string }> {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const out: Array<{ key: string; value: string }> = [];
+  for (const t of raw) {
+    const tr = asRecord(t);
+    if (tr === undefined) {
+      continue;
+    }
+    const key = str(tr, "key");
+    if (key === null) {
+      continue;
+    }
+    out.push({ key, value: str(tr, "value") ?? "" });
+  }
+  return out;
+}
+
+function pipelinesOf(node: unknown): {
+  repository: string;
+  location: string | null;
+  rows: unknown[];
+} {
+  const repo = asRecord(node);
+  if (repo === undefined) {
+    return { repository: "", location: null, rows: [] };
+  }
+  const locationRow = asRecord(repo["location"]);
+  const pipelines = repo["pipelines"];
+  return {
+    repository: str(repo, "name") ?? "",
+    location: locationRow === undefined ? null : str(locationRow, "name"),
+    rows: Array.isArray(pipelines) ? pipelines : [],
+  };
+}
+
+function pipelineToJob(p: unknown, repository: string, location: string | null): FlatJob | null {
+  const pr = asRecord(p);
+  if (pr === undefined) {
+    return null;
+  }
+  const name = str(pr, "name");
+  if (name === null) {
+    return null;
+  }
+  return {
+    name,
+    repository,
+    location,
+    id: str(pr, "id"),
+    description: str(pr, "description"),
+    isJob: pr["isJob"] === true,
+    tags: tagPairs(pr["tags"]),
+  };
+}
+
+function flattenJobs(data: unknown): FlatJob[] {
+  const root = asRecord(data) ?? {};
+  const repos = asRecord(root["repositoriesOrError"]) ?? {};
+  if (repos["__typename"] === "PythonError") {
+    const message = str(repos, "message") ?? "unknown error";
+    throw new Error(`Dagster repositoriesOrError PythonError: ${message}`);
+  }
+  const nodes = repos["nodes"];
+  if (!Array.isArray(nodes)) {
+    return [];
+  }
+  const out: FlatJob[] = [];
+  for (const node of nodes) {
+    const { repository, location, rows } = pipelinesOf(node);
+    for (const p of rows) {
+      const job = pipelineToJob(p, repository, location);
+      if (job !== null) {
+        out.push(job);
+      }
+    }
+  }
+  return out;
+}
+
+async function listJobs(): Promise<FlatJob[]> {
+  return flattenJobs(await dagsterGraphql<unknown>(JOBS_QUERY));
+}
+
+await runReadOnlyMcpConnector("nimbus-dagster", (reg) => {
+  reg(
+    "dagster_list",
+    "List Dagster jobs. Walks the repositories catalog via a single GraphQL query (repositoriesOrError → nodes[].pipelines[]) against POST <base_url>/graphql and flattens to jobs, each carrying its repository and code location. Returns an { items: [...] } envelope.",
+    z.object({
+      limit: z.number().int().min(1).max(2000).optional(),
+    }),
+    async (p) => {
+      const jobs = await listJobs();
+      const limited = p.limit === undefined ? jobs : jobs.slice(0, p.limit);
+      return jsonResult({ items: limited });
+    },
+  );
+
+  reg(
+    "dagster_get",
+    "Fetch one Dagster job by its stable id. The id is either the full location:repository:jobName triple or just the bare jobName (the first match wins when only a name is given). Throws when no job matches.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      const jobs = await listJobs();
+      const match = jobs.find((j) => {
+        const triple = `${j.location ?? "_"}:${j.repository}:${j.name}`;
+        return triple === p.id || j.name === p.id;
+      });
+      if (match === undefined) {
+        throw new Error(`Dagster: job ${p.id} not found`);
+      }
+      return jsonResult(match);
+    },
+  );
+
+  reg(
+    "dagster_search",
+    "Substring search across Dagster jobs. Matches the query (case-insensitive) against the job name, repository, code location, description, and tag keys/values. Returns a { matches: [...] } envelope.",
+    searchToolInputSchema(2000),
+    async (p) => {
+      const jobs = await listJobs();
+      const matches = filterDagsterJobs(jobs, { query: p.query, limit: p.limit });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/databricks/nimbus.extension.json

@@ -0,0 +1,16 @@
+{
+  "id": "com.nimbus.databricks",
+  "displayName": "Databricks",
+  "version": "0.1.0",
+  "description": "Databricks connector (read-only). Surfaces Databricks Jobs — name, creator, schedule, format, created timestamp, and the latest run status (life-cycle/result state, run id, started-at, duration, cluster, triggered-by) — into the local index as `databricks:data_pipeline` items via the Jobs API 2.1 (`GET /api/2.1/jobs/list`, token-paginated, enriched from one page of `GET /api/2.1/jobs/runs/list`). Databricks Personal Access Token auth (sent as `Authorization: Bearer <token>`). Databricks has no universal SaaS host: the per-workspace URL is supplied via the `databricks.host` vault key and added to the sandbox network list at spawn time by `phase3AddDatabricksMcp`, so the static manifest network list is intentionally empty. v1 indexes jobs only — clusters, SQL warehouses, and notebooks/workspace listing are a deferred follow-up; `job.trigger` / `job.cancel` / `cluster.restart` (HITL) writes are deferred to Phase 6. No write tools.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": [],
+    "filesystem": { "read": [], "write": [] }
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/databricks/src/search-filter.ts

@@ -0,0 +1,28 @@
+import {
+  asRecord,
+  makeQueryFilter,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type DatabricksSearchMatchOptions = SearchMatchOptions;
+
+function stringAt(row: Record<string, unknown>, key: string): string {
+  const v = row[key];
+  return typeof v === "string" ? v : "";
+}
+
+function numberAt(row: Record<string, unknown>, key: string): string {
+  const v = row[key];
+  return typeof v === "number" && Number.isFinite(v) ? String(v) : "";
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asRecord(item);
+  if (row === undefined) {
+    return null;
+  }
+  const settings = asRecord(row["settings"]) ?? {};
+  return [stringAt(settings, "name"), stringAt(row, "creator_user_name"), numberAt(row, "job_id")];
+}
+
+export const filterDatabricksJobs = makeQueryFilter(fieldsOf);