@nimbus-dev/connectors 0.2.0 → 0.2.2

package/connectors/jenkins/src/tools.ts

@@ -0,0 +1,240 @@
+import { z } from "zod";
+import type { ConsentServer } from "../../../shared/consent-kit.ts";
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import {
+  getJenkinsCrumb,
+  jenkinsAuthHeader,
+  jenkinsBaseUrl,
+  jenkinsFetchJson,
+  jenkinsPost,
+  jobApiRoot,
+} from "./jenkins-api.ts";
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const JENKINS_TOOL_NAMES = [
+  "jenkins_job_list",
+  "jenkins_job_get",
+  "jenkins_build_list",
+  "jenkins_build_get",
+  "jenkins_build_trigger",
+  "jenkins_build_abort",
+  "jenkins_build_log_tail",
+] as const;
+
+/**
+ * GET one Jenkins JSON endpoint, throwing `Jenkins <status>: <body>` on a
+ * non-2xx. Module scope, not nested in the registrar: it closes over nothing.
+ */
+export async function jenkinsGetJsonExpectOk(url: string): Promise<unknown> {
+  const res = await jenkinsFetchJson(url, { method: "GET", authHeader: jenkinsAuthHeader() });
+  if (!res.ok) {
+    throw new Error(`Jenkins ${String(res.status)}: ${res.text.slice(0, 400)}`);
+  }
+  return res.json;
+}
+
+/**
+ * A state-changing POST to `<job root><suffix>`, carrying the CSRF crumb Jenkins requires for
+ * one. A failure throws `Jenkins <action> <status>: <body>`. Module scope for the same reason as
+ * {@link jenkinsGetJsonExpectOk}: it closes over nothing.
+ */
+async function postToJob(jobName: string, suffix: string, action: string): Promise<void> {
+  const base = jenkinsBaseUrl();
+  const auth = jenkinsAuthHeader();
+  const crumb = await getJenkinsCrumb(base, auth);
+  const url = `${jobApiRoot(base, jobName)}${suffix}`;
+  const res = await jenkinsPost(url, auth, crumb);
+  if (!res.ok) {
+    throw new Error(`Jenkins ${action} ${String(res.status)}: ${res.text.slice(0, 400)}`);
+  }
+}
+
+export function registerJenkinsTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+
+  /**
+   * Every MUTATING jenkins 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: "jenkins",
+    scopeEnv: "NIMBUS_MCP_JENKINS_WRITE_SCOPE",
+    scopeKinds: ["job"],
+  });
+
+  const JOBS_TREE =
+    "jobs[name,fullname,url,jobs[name,fullname,url,jobs[name,fullname,url,jobs[name,fullname,url]]]]";
+
+  type JobNode = {
+    name?: string;
+    fullName?: string;
+    url?: string;
+    jobs?: JobNode[];
+  };
+
+  function jenkinsJobNodeDisplayName(n: JobNode): string {
+    if (typeof n.fullName === "string" && n.fullName !== "") {
+      return n.fullName;
+    }
+    if (typeof n.name === "string") {
+      return n.name;
+    }
+    return "";
+  }
+
+  function flattenJobs(
+    nodes: JobNode[] | undefined,
+    out: { fullName: string; url?: string }[],
+  ): void {
+    if (nodes === undefined) {
+      return;
+    }
+    for (const n of nodes) {
+      const fn = jenkinsJobNodeDisplayName(n);
+      if (fn !== "") {
+        if (typeof n.url === "string") {
+          out.push({ fullName: fn, url: n.url });
+        } else {
+          out.push({ fullName: fn });
+        }
+      }
+      flattenJobs(n.jobs, out);
+    }
+  }
+
+  reg(
+    "jenkins_job_list",
+    "List Jenkins jobs (nested folders, limited depth).",
+    z.object({}),
+    async () => {
+      const base = jenkinsBaseUrl();
+      const url = `${base}/api/json?tree=${encodeURIComponent(JOBS_TREE)}`;
+      const root = await jenkinsGetJsonExpectOk(url);
+      if (root === null || typeof root !== "object" || Array.isArray(root)) {
+        throw new Error("Jenkins: invalid jobs response");
+      }
+      const jobsRaw = (root as Record<string, unknown>)["jobs"];
+      const list: { fullName: string; url?: string }[] = [];
+      flattenJobs(Array.isArray(jobsRaw) ? (jobsRaw as JobNode[]) : undefined, list);
+      return jsonResult({ jobs: list });
+    },
+  );
+
+  const jobNameSchema = z.object({
+    jobName: z.string().min(1).describe("Job full name (e.g. folder/sub/job)"),
+  });
+
+  reg(
+    "jenkins_job_get",
+    "Get Jenkins job metadata by full name.",
+    jobNameSchema,
+    async (parsed) => {
+      const base = jenkinsBaseUrl();
+      const root = jobApiRoot(base, parsed.jobName);
+      const url = `${root}/api/json`;
+      return jsonResult(await jenkinsGetJsonExpectOk(url));
+    },
+  );
+
+  reg(
+    "jenkins_build_list",
+    "List recent builds for a job.",
+    z.object({
+      jobName: z.string().min(1),
+      limit: z.number().int().min(1).max(50).optional(),
+    }),
+    async (parsed) => {
+      const base = jenkinsBaseUrl();
+      const lim = parsed.limit ?? 20;
+      const tree = encodeURIComponent(
+        `builds[number,url,result,duration,timestamp,building]{0,${String(lim)}}`,
+      );
+      const url = `${jobApiRoot(base, parsed.jobName)}/api/json?tree=${tree}`;
+      return jsonResult(await jenkinsGetJsonExpectOk(url));
+    },
+  );
+
+  reg(
+    "jenkins_build_get",
+    "Get a single build by job name and build number.",
+    z.object({
+      jobName: z.string().min(1),
+      buildNumber: z.number().int().min(1),
+    }),
+    async (parsed) => {
+      const base = jenkinsBaseUrl();
+      const url = `${jobApiRoot(base, parsed.jobName)}/${String(parsed.buildNumber)}/api/json`;
+      return jsonResult(await jenkinsGetJsonExpectOk(url));
+    },
+  );
+
+  registerWriteTool(
+    "jenkins_build_trigger",
+    {
+      mutates: "jenkins.build.trigger",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "job", value: p.jobName }),
+    },
+    "Trigger a new build for a job.",
+    jobNameSchema,
+    async (parsed) => {
+      await postToJob(parsed.jobName, "/build", "trigger");
+      return jsonResult({ ok: true, jobName: parsed.jobName });
+    },
+  );
+
+  registerWriteTool(
+    "jenkins_build_abort",
+    {
+      mutates: "jenkins.build.abort",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "job", value: p.jobName }),
+    },
+    "Abort/stop a running build.",
+    z.object({
+      jobName: z.string().min(1),
+      buildNumber: z.number().int().min(1),
+    }),
+    async (parsed) => {
+      await postToJob(parsed.jobName, `/${String(parsed.buildNumber)}/stop`, "abort");
+      return jsonResult({ ok: true, jobName: parsed.jobName, buildNumber: parsed.buildNumber });
+    },
+  );
+
+  reg(
+    "jenkins_build_log_tail",
+    "Fetch console text for a build (full log; tail client-side).",
+    z.object({
+      jobName: z.string().min(1),
+      buildNumber: z.number().int().min(1),
+      maxLines: z.number().int().min(1).max(5000).optional(),
+    }),
+    async (parsed) => {
+      const base = jenkinsBaseUrl();
+      const auth = jenkinsAuthHeader();
+      const url = `${jobApiRoot(base, parsed.jobName)}/${String(parsed.buildNumber)}/consoleText`;
+      const res = await fetch(url, { headers: { Authorization: auth } });
+      const text = await res.text();
+      if (!res.ok) {
+        throw new Error(`Jenkins log ${String(res.status)}: ${text.slice(0, 400)}`);
+      }
+      const maxLines = parsed.maxLines ?? 200;
+      const lines = text.split(/\r?\n/);
+      const tail = lines.slice(Math.max(0, lines.length - maxLines)).join("\n");
+      return jsonResult({
+        jobName: parsed.jobName,
+        buildNumber: parsed.buildNumber,
+        lineCount: lines.length,
+        tail,
+      });
+    },
+  );
+}

package/connectors/jira/src/server.ts

@@ -1,309 +1,10 @@
 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 {
-  createRegisterSimpleTool,
-  createZodToolRegistrar,
-  mcpJsonResult as jsonResult,
-  mcpJsonResultFromTextIfOk,
-} from "../../../shared/mcp-tool-kit.ts";
-
-function requireJiraConfig(): { baseUrl: string; email: string; token: string } {
-  const baseRaw = requireTrimmedEnv("JIRA_BASE_URL", "JIRA_BASE_URL is not set");
-  const email = requireTrimmedEnv("JIRA_EMAIL", "JIRA_EMAIL is not set");
-  const token = requireTrimmedEnv("JIRA_API_TOKEN", "JIRA_API_TOKEN is not set");
-  return {
-    baseUrl: normalizeRequiredSiteBaseUrl(baseRaw, "JIRA_BASE_URL is empty"),
-    email,
-    token,
-  };
-}
-
-async function jiraFetch(
-  baseUrl: string,
-  email: string,
-  token: string,
-  path: string,
-  init?: RequestInit,
-): Promise<{ ok: boolean; status: number; text: string }> {
-  const relativePath = path.startsWith("/") ? path : `/${path}`;
-  const url = `${baseUrl}${relativePath}`;
-  return fetchAtlassianBasicAuthJsonText(url, email, token, init);
-}
-
-function plainToAdf(text: string): Record<string, unknown> {
-  return {
-    type: "doc",
-    version: 1,
-    content: [
-      {
-        type: "paragraph",
-        content: [{ type: "text", text }],
-      },
-    ],
-  };
-}
+import { registerJiraTools } from "./tools.ts";
 
 const server = new McpServer({ name: "nimbus-jira", version: "0.1.0" });
 
-const registerSimpleTool = createRegisterSimpleTool(server);
-
-import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
-
-const reg = createZodToolRegistrar(registerSimpleTool);
-
-/**
- * Every MUTATING jira 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: "jira",
-  scopeEnv: "NIMBUS_MCP_JIRA_WRITE_SCOPE",
-  scopeKinds: ["project", "issue"],
-});
-
-const jiraIssueListSchema = z.object({
-  jql: z.string().min(1).optional(),
-  startAt: z.number().int().min(0).optional(),
-  maxResults: z.number().int().min(1).max(100).optional(),
-});
-
-reg(
-  "jira_issue_list",
-  "Search Jira issues with JQL (Jira Cloud REST POST /rest/api/3/search).",
-  jiraIssueListSchema,
-  async (parsed) => {
-    const { baseUrl, email, token } = requireJiraConfig();
-    const jql = parsed.jql ?? "order by updated DESC";
-    const body = JSON.stringify({
-      jql,
-      startAt: parsed.startAt ?? 0,
-      maxResults: parsed.maxResults ?? 50,
-      fields: ["summary", "description", "updated", "status", "issuetype", "priority", "assignee"],
-    });
-    const res = await jiraFetch(baseUrl, email, token, "/rest/api/3/search", {
-      method: "POST",
-      body,
-    });
-    return mcpJsonResultFromTextIfOk("Jira", res, {
-      jsonParseErrorMessage: "Jira: invalid JSON from search",
-    });
-  },
-);
-
-const jiraIssueKeySchema = z.object({ issueKey: z.string().min(1) });
-
-reg(
-  "jira_issue_get",
-  "Get a Jira issue by key or id (GET /rest/api/3/issue/{issueIdOrKey}).",
-  jiraIssueKeySchema,
-  async (parsed) => {
-    const { baseUrl, email, token } = requireJiraConfig();
-    const key = encodeURIComponent(parsed.issueKey);
-    const res = await jiraFetch(
-      baseUrl,
-      email,
-      token,
-      `/rest/api/3/issue/${key}?fields=summary,description,updated,status,issuetype,priority,assignee,comment`,
-    );
-    return mcpJsonResultFromTextIfOk("Jira", res, {
-      jsonParseErrorMessage: "Jira: invalid JSON from issue get",
-    });
-  },
-);
-
-const jiraIssueCreateSchema = z.object({
-  projectKey: z.string().min(1),
-  summary: z.string().min(1),
-  description: z.string().optional(),
-  issueTypeName: z.string().min(1).optional(),
-});
-
-registerWriteTool(
-  "jira_issue_create",
-  {
-    mutates: "jira.issue.create",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "project", value: p.projectKey }),
-  },
-  "Create a Jira issue (POST /rest/api/3/issue). Requires project key and summary.",
-  jiraIssueCreateSchema,
-  async (parsed) => {
-    const { baseUrl, email, token } = requireJiraConfig();
-    const fields: Record<string, unknown> = {
-      project: { key: parsed.projectKey },
-      summary: parsed.summary,
-      issuetype: { name: parsed.issueTypeName ?? "Task" },
-    };
-    if (parsed.description !== undefined && parsed.description !== "") {
-      fields["description"] = plainToAdf(parsed.description);
-    }
-    const body = JSON.stringify({ fields });
-    const res = await jiraFetch(baseUrl, email, token, "/rest/api/3/issue", {
-      method: "POST",
-      body,
-    });
-    return mcpJsonResultFromTextIfOk("Jira", res, {
-      jsonParseErrorMessage: "Jira: invalid JSON from issue create",
-    });
-  },
-);
-
-const jiraIssueUpdateSchema = z.object({
-  issueKey: z.string().min(1),
-  summary: z.string().min(1).optional(),
-  description: z.string().optional(),
-});
-
-registerWriteTool(
-  "jira_issue_update",
-  {
-    mutates: "jira.issue.update",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "issue", value: p.issueKey }),
-  },
-  "Update summary and/or description on a Jira issue (PUT /rest/api/3/issue/{key}).",
-  jiraIssueUpdateSchema,
-  async (parsed) => {
-    if (parsed.summary === undefined && parsed.description === undefined) {
-      throw new Error("Provide summary and/or description to update");
-    }
-    const { baseUrl, email, token } = requireJiraConfig();
-    const fields: Record<string, unknown> = {};
-    if (parsed.summary !== undefined) {
-      fields["summary"] = parsed.summary;
-    }
-    if (parsed.description !== undefined) {
-      fields["description"] = plainToAdf(parsed.description);
-    }
-    const key = encodeURIComponent(parsed.issueKey);
-    const body = JSON.stringify({ fields });
-    const res = await jiraFetch(baseUrl, email, token, `/rest/api/3/issue/${key}`, {
-      method: "PUT",
-      body,
-    });
-    if (!res.ok) {
-      throw new Error(`Jira ${String(res.status)}: ${res.text.slice(0, 400)}`);
-    }
-    return jsonResult({ ok: true, issueKey: parsed.issueKey });
-  },
-);
-
-const jiraCommentAddSchema = z.object({
-  issueKey: z.string().min(1),
-  body: z.string().min(1),
-});
-
-registerWriteTool(
-  "jira_comment_add",
-  {
-    mutates: "jira.comment.add",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "issue", value: p.issueKey }),
-  },
-  "Add a comment to a Jira issue (POST /rest/api/3/issue/{key}/comment).",
-  jiraCommentAddSchema,
-  async (parsed) => {
-    const { baseUrl, email, token } = requireJiraConfig();
-    const key = encodeURIComponent(parsed.issueKey);
-    const payload = JSON.stringify({ body: plainToAdf(parsed.body) });
-    const res = await jiraFetch(baseUrl, email, token, `/rest/api/3/issue/${key}/comment`, {
-      method: "POST",
-      body: payload,
-    });
-    return mcpJsonResultFromTextIfOk("Jira", res, {
-      jsonParseErrorMessage: "Jira: invalid JSON from comment add",
-    });
-  },
-);
-
-const jiraBoardListSchema = z.object({
-  startAt: z.number().int().min(0).optional(),
-  maxResults: z.number().int().min(1).max(50).optional(),
-});
-
-reg(
-  "jira_board_list",
-  "List Jira boards (GET /rest/agile/1.0/board).",
-  jiraBoardListSchema,
-  async (parsed) => {
-    const { baseUrl, email, token } = requireJiraConfig();
-    const start = parsed.startAt ?? 0;
-    const max = parsed.maxResults ?? 50;
-    const res = await jiraFetch(
-      baseUrl,
-      email,
-      token,
-      `/rest/agile/1.0/board?startAt=${String(start)}&maxResults=${String(max)}`,
-    );
-    return mcpJsonResultFromTextIfOk("Jira", res, {
-      jsonParseErrorMessage: "Jira: invalid JSON from board list",
-    });
-  },
-);
-
-const jiraSprintListSchema = z.object({
-  boardId: z.number().int().min(1),
-  startAt: z.number().int().min(0).optional(),
-  maxResults: z.number().int().min(1).max(50).optional(),
-});
-
-reg(
-  "jira_sprint_list",
-  "List sprints for a board (GET /rest/agile/1.0/board/{boardId}/sprint).",
-  jiraSprintListSchema,
-  async (parsed) => {
-    const { baseUrl, email, token } = requireJiraConfig();
-    const start = parsed.startAt ?? 0;
-    const max = parsed.maxResults ?? 50;
-    const bid = String(parsed.boardId);
-    const res = await jiraFetch(
-      baseUrl,
-      email,
-      token,
-      `/rest/agile/1.0/board/${bid}/sprint?startAt=${String(start)}&maxResults=${String(max)}`,
-    );
-    return mcpJsonResultFromTextIfOk("Jira", res, {
-      jsonParseErrorMessage: "Jira: invalid JSON from sprint list",
-    });
-  },
-);
-
-const jiraEpicListSchema = z.object({
-  projectKey: z.string().min(1),
-  maxResults: z.number().int().min(1).max(100).optional(),
-});
-
-reg(
-  "jira_epic_list",
-  "List epics in a project via JQL search.",
-  jiraEpicListSchema,
-  async (parsed) => {
-    const { baseUrl, email, token } = requireJiraConfig();
-    const pk = parsed.projectKey;
-    const jql = `project = ${pk} AND issuetype = Epic ORDER BY updated DESC`;
-    const body = JSON.stringify({
-      jql,
-      startAt: 0,
-      maxResults: parsed.maxResults ?? 50,
-      fields: ["summary", "updated", "status"],
-    });
-    const res = await jiraFetch(baseUrl, email, token, "/rest/api/3/search", {
-      method: "POST",
-      body,
-    });
-    return mcpJsonResultFromTextIfOk("Jira", res, {
-      jsonParseErrorMessage: "Jira: invalid JSON from epic search",
-    });
-  },
-);
+registerJiraTools(server);
 
 const transport = new StdioServerTransport();
 await server.connect(transport);