MCP for Internal Platforms: Wrapping Jenkins, Buildkite, and Internal CLIs

# roles.yaml
roles:
  engineer:
    description: "Standard engineer access"
    permissions:
      jenkins:
        - read_build
        - read_logs
        - trigger_build:own-team-pipelines
      buildkite:
        - read_pipeline
        - read_build
        - trigger_build:own-team-pipelines
      backstage:
        - read_service
        - read_ownership
 
  platform-on-call:
    description: "On-call platform engineer"
    extends: engineer
    permissions:
      jenkins:
        - read_build
        - read_logs
        - trigger_build:all-pipelines
        - cancel_build:all-pipelines
      buildkite:
        - read_pipeline
        - read_build
        - trigger_build:all-pipelines
        - cancel_build:all-pipelines
 
  platform-admin:
    description: "Platform admin — for break-glass scenarios only"
    extends: platform-on-call
    permissions:
      jenkins:
        - "*"
      buildkite:
        - "*"

import yaml from "js-yaml";
import fs from "fs";
 
interface RoleConfig {
  roles: Record<string, {
    description: string;
    extends?: string;
    permissions: Record<string, string[]>;
  }>;
}
 
function loadRoles(path: string): RoleConfig {
  return yaml.load(fs.readFileSync(path, "utf8")) as RoleConfig;
}
 
function resolvePermissions(
  roleName: string,
  config: RoleConfig,
  system: string
): string[] {
  const role = config.roles[roleName];
  if (!role) return [];
 
  const inherited = role.extends
    ? resolvePermissions(role.extends, config, system)
    : [];
  const own = role.permissions[system] ?? [];
  return [...new Set([...inherited, ...own])];
}
 
function hasPermission(
  roleName: string,
  config: RoleConfig,
  system: string,
  action: string,
  resource?: string
): boolean {
  const perms = resolvePermissions(roleName, config, system);
  return perms.some(p => {
    if (p === "*") return true;
    const [permAction, permResource] = p.split(":");
    if (permAction !== action) return false;
    if (!permResource) return true;
    return resource?.startsWith(permResource.replace("*", "")) ?? false;
  });
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import axios from "axios";
 
const jenkins = axios.create({
  baseURL: process.env.JENKINS_URL,
  auth: {
    username: process.env.JENKINS_USER!,
    password: process.env.JENKINS_API_TOKEN!,
  },
});
 
server.tool(
  "get_build_status",
  "Get the status of a Jenkins build by job name and build number. Use 'lastBuild' as build_number for the most recent build.",
  {
    job_name: z.string().describe("Full job path, e.g. 'my-team/service-name/main'"),
    build_number: z.union([z.number().int().positive(), z.literal("lastBuild")]),
  },
  async ({ job_name, build_number }, ctx) => {
    assertPermission(ctx, "jenkins", "read_build");
 
    const path = job_name.split("/").map(p => `job/${p}`).join("/");
    const res = await jenkins.get(`/${path}/${build_number}/api/json`);
    const build = res.data;
 
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          number: build.number,
          status: build.result ?? build.building ? "RUNNING" : "UNKNOWN",
          duration_ms: build.duration,
          url: build.url,
          started_at: new Date(build.timestamp).toISOString(),
          causes: build.actions
            ?.find((a: any) => a._class?.includes("CauseAction"))
            ?.causes?.map((c: any) => c.shortDescription) ?? [],
        }),
      }],
    };
  }
);
 
server.tool(
  "get_build_log_tail",
  "Get the last N lines of a Jenkins build log. Use this to diagnose build failures.",
  {
    job_name: z.string(),
    build_number: z.union([z.number().int().positive(), z.literal("lastBuild")]),
    lines: z.number().int().min(10).max(500).default(100),
  },
  async ({ job_name, build_number, lines }, ctx) => {
    assertPermission(ctx, "jenkins", "read_logs");
 
    const path = job_name.split("/").map(p => `job/${p}`).join("/");
    const res = await jenkins.get(`/${path}/${build_number}/logText/progressiveText`, {
      params: { start: 0 },
    });
 
    const logLines = (res.data as string).split("\n");
    const tail = logLines.slice(-lines).join("\n");
 
    return { content: [{ type: "text", text: tail }] };
  }
);
 
server.tool(
  "trigger_build",
  "[MUTATES] Trigger a Jenkins job. Optionally pass build parameters as key-value pairs.",
  {
    job_name: z.string(),
    parameters: z.record(z.string()).optional().describe("Build parameters"),
  },
  async ({ job_name, parameters }, ctx) => {
    assertPermission(ctx, "jenkins", "trigger_build", job_name);
    await auditLog(ctx, "jenkins.trigger_build", { job_name, parameters });
 
    const path = job_name.split("/").map(p => `job/${p}`).join("/");
    const endpoint = parameters
      ? `/${path}/buildWithParameters`
      : `/${path}/build`;
 
    const res = await jenkins.post(endpoint, null, {
      params: parameters,
    });
 
    const queueUrl = res.headers["location"];
    return {
      content: [{
        type: "text",
        text: `Build triggered for ${job_name}. Queue item: ${queueUrl}`,
      }],
    };
  }
);

const buildkite = axios.create({
  baseURL: "https://api.buildkite.com/v2",
  headers: { Authorization: `Bearer ${process.env.BUILDKITE_API_TOKEN}` },
});
 
// Resource: list pipelines so the agent can discover slugs
server.resource(
  "buildkite-pipelines",
  "buildkite://pipelines",
  { mimeType: "application/json" },
  async () => {
    const org = process.env.BUILDKITE_ORG!;
    const res = await buildkite.get(`/organizations/${org}/pipelines`, {
      params: { per_page: 100 },
    });
 
    return {
      contents: [{
        uri: "buildkite://pipelines",
        mimeType: "application/json",
        text: JSON.stringify(
          res.data.map((p: any) => ({
            slug: p.slug,
            name: p.name,
            description: p.description,
            default_branch: p.default_branch,
            uri: `buildkite://pipelines/${p.slug}`,
          }))
        ),
      }],
    };
  }
);
 
server.tool(
  "get_buildkite_build",
  "Get the latest build for a Buildkite pipeline, optionally filtered to a specific branch.",
  {
    pipeline_slug: z.string(),
    branch: z.string().optional(),
  },
  async ({ pipeline_slug, branch }, ctx) => {
    assertPermission(ctx, "buildkite", "read_build");
    const org = process.env.BUILDKITE_ORG!;
    const res = await buildkite.get(
      `/organizations/${org}/pipelines/${pipeline_slug}/builds`,
      { params: { branch, per_page: 1 } }
    );
    const build = res.data[0];
    if (!build) {
      return { content: [{ type: "text", text: "No builds found." }] };
    }
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          number: build.number,
          state: build.state,
          branch: build.branch,
          commit: build.commit,
          created_at: build.created_at,
          finished_at: build.finished_at,
          url: build.web_url,
          creator: build.creator?.name,
        }),
      }],
    };
  }
);

import { spawn } from "child_process";
 
const ALLOWED_COMMANDS: Record<string, {
  executable: string;
  allowed_subcommands: string[];
  max_runtime_ms: number;
}> = {
  kubectl: {
    executable: "/usr/local/bin/kubectl",
    allowed_subcommands: ["get", "describe", "logs", "rollout status"],
    max_runtime_ms: 30_000,
  },
  terraform: {
    executable: "/usr/local/bin/terraform",
    allowed_subcommands: ["plan", "output", "state list"],
    max_runtime_ms: 120_000,
  },
};
 
async function runSandboxedCLI(
  command: string,
  subcommand: string,
  args: string[]
): Promise<string> {
  const config = ALLOWED_COMMANDS[command];
  if (!config) throw new Error(`Command '${command}' not in allowlist`);
 
  const isAllowed = config.allowed_subcommands.some(
    s => subcommand.startsWith(s)
  );
  if (!isAllowed) throw new Error(`Subcommand '${subcommand}' not permitted for ${command}`);
 
  // Sanitize args: no shell metacharacters
  const safeArgs = args.map(a => a.replace(/[;&|`$()\\]/g, ""));
 
  return new Promise((resolve, reject) => {
    const proc = spawn(config.executable, [subcommand, ...safeArgs], {
      timeout: config.max_runtime_ms,
      env: { PATH: "/usr/local/bin:/usr/bin:/bin" },  // minimal PATH
    });
 
    let stdout = "";
    let stderr = "";
    proc.stdout.on("data", d => (stdout += d));
    proc.stderr.on("data", d => (stderr += d));
    proc.on("close", code => {
      if (code !== 0) reject(new Error(`Command failed (${code}): ${stderr.slice(0, 500)}`));
      else resolve(stdout.slice(0, 50_000));  // cap output size
    });
  });
}