@nimbus-dev/connectors 0.2.1 → 0.2.3

package/connectors/confluence/src/tools.ts

@@ -0,0 +1,320 @@
+import { z } from "zod";
+import {
+  fetchAtlassianBasicAuthJsonText,
+  normalizeRequiredSiteBaseUrl,
+  requireTrimmedEnv,
+} from "../../../shared/atlassian-json-fetch.ts";
+import type { ConsentServer } from "../../../shared/consent-kit.ts";
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.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);
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const CONFLUENCE_TOOL_NAMES = [
+  "confluence_space_list",
+  "confluence_page_list",
+  "confluence_page_get",
+  "confluence_blogpost_list",
+  "confluence_blogpost_get",
+  "confluence_comment_list",
+  "confluence_page_create",
+  "confluence_kb_append",
+  "confluence_page_update",
+  "confluence_comment_add",
+] as const;
+
+export function registerConfluenceTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const registerSimpleTool = createRegisterSimpleTool(server);
+
+  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);
+    },
+  );
+}

package/connectors/dagster/src/server.ts

@@ -1,218 +1,6 @@
-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));
-}
+import { registerDagsterTools } from "./tools.ts";
 
 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 });
-    },
-  );
+  registerDagsterTools(reg);
 });