yontrack-mcp 1.0.0

package/build/index.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { createServer } from "./server.js";
+import { oauthConfig } from "./config.js";
+import { createOAuthProvider, clientsStore, generateAuthCode, renderAuthFormHtml, } from "./auth.js";
+if (process.argv[2] === "stdio") {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+else {
+    const port = parseInt(process.env.PORT ?? "3000", 10);
+    const app = express();
+    // Trust the first reverse proxy (e.g. Kubernetes ingress controller).
+    // Required for express-rate-limit (used by the OAuth2 handlers) to work correctly
+    // when X-Forwarded-For is set by the ingress.
+    app.set("trust proxy", 1);
+    // Log every request for diagnostics (excluding /health to reduce noise)
+    app.use((req, res, next) => {
+        if (req.path !== "/health") {
+            res.on("finish", () => {
+                process.stderr.write(`${req.method} ${req.originalUrl} → ${res.statusCode}\n`);
+            });
+        }
+        next();
+    });
+    // Static assets (e.g. server icon)
+    app.use(express.static("public"));
+    // Health check
+    app.get("/health", (_req, res) => {
+        res.json({ status: "ok" });
+    });
+    // MCP request handler
+    async function handleMcp(req, res) {
+        const server = createServer(oauthConfig?.serverUrl);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        res.on("close", () => transport.close());
+        await server.connect(transport);
+        // req.body is pre-parsed by express.json() for POST requests
+        await transport.handleRequest(req, res, req.body);
+    }
+    function oauthLog(msg) {
+        process.stderr.write(`[oauth] ${msg}\n`);
+    }
+    if (oauthConfig) {
+        const { serverUrl, authPassword } = oauthConfig;
+        const provider = createOAuthProvider(serverUrl);
+        // Log all incoming OAuth-related requests for easier diagnostics
+        app.use([
+            "/.well-known/oauth-authorization-server",
+            "/.well-known/oauth-protected-resource",
+            "/authorize",
+            "/token",
+            "/register",
+            "/revoke",
+        ], (req, _res, next) => {
+            oauthLog(`${req.method} ${req.path}`);
+            next();
+        });
+        // Login form submission must be registered BEFORE mcpAuthRouter because the
+        // SDK's /authorize handler (prefix-matched) also runs urlencoded() middleware
+        // which would consume the request body before our handler gets to it.
+        app.post("/authorize/login", express.urlencoded({ extended: false }), async (req, res) => {
+            const { client_id, redirect_uri, code_challenge, scopes, state, password, } = req.body;
+            const client = await clientsStore.getClient(client_id);
+            if (!client) {
+                oauthLog(`ERROR: Login attempt for unknown client: ${client_id}`);
+                res
+                    .status(400)
+                    .json({ error: "invalid_client", error_description: "Unknown client" });
+                return;
+            }
+            if (!password || password !== authPassword) {
+                oauthLog(`Login failed — wrong password for client ${client_id}`);
+                res.setHeader("Content-Type", "text/html; charset=utf-8");
+                res.end(renderAuthFormHtml({
+                    serverUrl,
+                    clientName: client.client_name ?? client.client_id,
+                    clientId: client_id,
+                    redirectUri: redirect_uri ?? "",
+                    codeChallenge: code_challenge ?? "",
+                    scopes: scopes ?? "",
+                    state: state ?? "",
+                    error: "Invalid password. Please try again.",
+                }));
+                return;
+            }
+            const code = generateAuthCode({
+                clientId: client_id,
+                codeChallenge: code_challenge ?? "",
+                redirectUri: redirect_uri ?? "",
+                scopes: scopes ? scopes.split(" ").filter(Boolean) : [],
+                state: state || undefined,
+            });
+            oauthLog(`Login successful for client ${client_id}, redirecting with auth code`);
+            const redirectUrl = new URL(redirect_uri);
+            redirectUrl.searchParams.set("code", code);
+            if (state)
+                redirectUrl.searchParams.set("state", state);
+            res.redirect(302, redirectUrl.href);
+        });
+        // OAuth2 discovery + token endpoints
+        app.use(mcpAuthRouter({
+            provider,
+            issuerUrl: new URL(serverUrl),
+            resourceName: "Yontrack MCP",
+        }));
+        // Protected MCP endpoint — requires a valid Bearer token
+        app.all("/mcp", express.json(), requireBearerAuth({ verifier: provider }), handleMcp);
+    }
+    else {
+        // No OAuth configured — MCP is accessible without authentication
+        app.all("/mcp", express.json(), handleMcp);
+    }
+    app.listen(port, () => {
+        process.stderr.write(`MCP server listening on port ${port}\n`);
+        if (oauthConfig) {
+            process.stderr.write(`OAuth2 enabled — issuer: ${oauthConfig.serverUrl}\n`);
+        }
+    });
+}

package/build/server.js

@@ -0,0 +1,21 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerAllTools } from "./tools/index.js";
+export function createServer(serverUrl) {
+    const server = new McpServer({
+        name: "yontrack",
+        version: "1.0.0",
+        ...(serverUrl && {
+            icons: [{ src: `${serverUrl}/yontrack.png`, mimeType: "image/png" }],
+        }),
+    }, {
+        instructions: `
+Use the specific tools (list_projects, get_build, etc.) for simple, single-entity lookups.
+When a task would require calling multiple tools in a loop — for example fetching builds across many branches, or collecting validation runs for a list of builds — use graphql_query instead to retrieve all needed data in a single round-trip.
+Read the yontrack://schema resource before writing a GraphQL query to understand available types and fields.
+When displaying branches, builds, or other entities to the user, always prefer the displayName field over the name field.
+When displaying promotion levels (in any form: list, table, chart, or graph), always fetch their image using get_promotion_level_image for each level whose image field is true, and embed the returned base64 data directly as a data URI (e.g. <img src="data:image/png;base64,...">) alongside the promotion level name. Do not reference the MCP server URL for images as it is not accessible from the browser.
+      `.trim(),
+    });
+    registerAllTools(server);
+    return server;
+}

package/build/test/helpers.js

@@ -0,0 +1,17 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+/**
+ * Creates a linked in-process MCP server+client pair.
+ * Pass a register function to attach tools to the server before connecting.
+ * `allowMutations` defaults to `true` so existing tests cover all tools.
+ */
+export async function createTestClient(register, allowMutations = true) {
+    const server = new McpServer({ name: "test", version: "0.0.0" });
+    register(server, allowMutations);
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "test-client", version: "0.0.0" });
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+    return client;
+}

package/build/test/setup.js

@@ -0,0 +1,5 @@
+// Must run before any module that imports src/config.ts,
+// which calls process.exit(1) if these vars are absent.
+process.env.YONTRACK_URL = "https://yontrack.example.com";
+process.env.YONTRACK_TOKEN = "test-token";
+export {};

package/build/tools/branches.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { gqlClient } from "../client.js";
+const LIST_BRANCHES = `
+  query ListBranches($project: String!, $name: String) {
+    branches(project: $project, name: $name) {
+      id
+      name
+      displayName
+      description
+      disabled
+      project { id name }
+    }
+  }
+`;
+const CREATE_BRANCH = `
+  mutation CreateBranch($projectName: String!, $name: String!, $description: String) {
+    createBranch(input: {
+      projectName: $projectName
+      name: $name
+      description: $description
+    }) {
+      branch { id name displayName description disabled project { id name } }
+      userErrors { message }
+    }
+  }
+`;
+export function registerBranchTools(server, allowMutations) {
+    server.tool("list_branches", "List branches for a project, optionally filtered by name", {
+        project: z.string().describe("Project name"),
+        name: z.string().optional().describe("Filter by branch name"),
+    }, async ({ project, name }) => {
+        const data = await gqlClient.request(LIST_BRANCHES, { project, name });
+        return {
+            content: [{ type: "text", text: JSON.stringify(data.branches, null, 2) }],
+        };
+    });
+    if (allowMutations)
+        server.tool("create_branch", "Create a new branch in a project", {
+            project: z.string().describe("Project name"),
+            name: z.string().describe("Branch name"),
+            description: z.string().optional().describe("Branch description"),
+        }, async ({ project, name, description }) => {
+            const data = await gqlClient.request(CREATE_BRANCH, { projectName: project, name, description });
+            const { branch, userErrors } = data.createBranch;
+            if (userErrors?.length) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: userErrors.map((e) => e.message).join(", ") }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(branch, null, 2) }],
+            };
+        });
+}

package/build/tools/branches.test.js

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createTestClient } from "../test/helpers.js";
+import { registerBranchTools } from "./branches.js";
+vi.mock("../client.js", () => ({
+    gqlClient: { request: vi.fn() },
+}));
+const { gqlClient } = await import("../client.js");
+const mockRequest = gqlClient.request;
+beforeEach(() => {
+    mockRequest.mockReset();
+});
+describe("list_branches", () => {
+    it("returns branches for a project", async () => {
+        const branches = [
+            { id: 1, name: "main", displayName: "main", description: null, disabled: false, project: { id: 1, name: "myproject" } },
+        ];
+        mockRequest.mockResolvedValueOnce({ branches });
+        const client = await createTestClient(registerBranchTools);
+        const result = await client.callTool({
+            name: "list_branches",
+            arguments: { project: "myproject" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(branches);
+    });
+    it("returns empty array when no branches match", async () => {
+        mockRequest.mockResolvedValueOnce({ branches: [] });
+        const client = await createTestClient(registerBranchTools);
+        const result = await client.callTool({
+            name: "list_branches",
+            arguments: { project: "myproject", name: "nonexistent" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual([]);
+    });
+    it("passes the name filter to the GraphQL client", async () => {
+        mockRequest.mockResolvedValueOnce({ branches: [] });
+        const client = await createTestClient(registerBranchTools);
+        await client.callTool({
+            name: "list_branches",
+            arguments: { project: "myproject", name: "feature" },
+        });
+        expect(mockRequest).toHaveBeenCalledWith(expect.any(String), { project: "myproject", name: "feature" });
+    });
+});
+describe("create_branch", () => {
+    it("returns the created branch", async () => {
+        const branch = { id: 10, name: "feature-x", displayName: "feature-x", description: "My feature", disabled: false };
+        mockRequest.mockResolvedValueOnce({ createBranch: { branch, userErrors: [] } });
+        const client = await createTestClient(registerBranchTools);
+        const result = await client.callTool({
+            name: "create_branch",
+            arguments: { project: "myproject", name: "feature-x", description: "My feature" },
+        });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(branch);
+    });
+    it("returns an error when userErrors is non-empty", async () => {
+        mockRequest.mockResolvedValueOnce({
+            createBranch: { branch: null, userErrors: [{ message: "Branch already exists" }] },
+        });
+        const client = await createTestClient(registerBranchTools);
+        const result = await client.callTool({
+            name: "create_branch",
+            arguments: { project: "myproject", name: "main" },
+        });
+        expect(result.isError).toBe(true);
+        const text = result.content[0].text;
+        expect(text).toContain("Branch already exists");
+    });
+    it("is not registered when mutations are disabled", async () => {
+        const client = await createTestClient(registerBranchTools, false);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).not.toContain("create_branch");
+    });
+    it("is registered when mutations are enabled", async () => {
+        const client = await createTestClient(registerBranchTools, true);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).toContain("create_branch");
+    });
+});

package/build/tools/build-links.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { gqlClient } from "../client.js";
+const GET_BUILD_LINKS = `
+  query GetBuildLinks($project: String!, $branch: String!, $build: String!) {
+    builds(project: $project, branch: $branch, name: $build) {
+      usingQualified {
+        pageItems {
+          qualifier
+          build { id name branch { id name project { id name } } }
+        }
+        pageInfo { totalSize }
+      }
+      usedByQualified {
+        pageItems {
+          qualifier
+          build { id name branch { id name project { id name } } }
+        }
+        pageInfo { totalSize }
+      }
+    }
+  }
+`;
+const SET_BUILD_LINKS = `
+  mutation LinksBuild(
+    $fromProject: String!
+    $fromBuild: String!
+    $links: [LinksBuildInputItem!]!
+  ) {
+    linksBuild(input: {
+      fromProject: $fromProject
+      fromBuild: $fromBuild
+      links: $links
+    }) {
+      userErrors { message }
+    }
+  }
+`;
+const BuildLinkInput = z.object({
+    project: z.string().describe("Target project name"),
+    build: z.string().describe("Target build name"),
+    qualifier: z.string().optional().describe("Optional link qualifier"),
+});
+export function registerBuildLinkTools(server, allowMutations) {
+    server.tool("get_build_links", "Get dependency links for a build (builds it uses and builds that use it)", {
+        project: z.string().describe("Project name"),
+        branch: z.string().describe("Branch name"),
+        build: z.string().describe("Build name"),
+    }, async ({ project, branch, build }) => {
+        const data = await gqlClient.request(GET_BUILD_LINKS, { project, branch, build });
+        const result = data.builds?.[0] ?? { usingQualified: null, usedByQualified: null };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    if (allowMutations)
+        server.tool("set_build_links", "Set dependency links from a build to one or more target builds", {
+            fromProject: z.string().describe("Source project name"),
+            fromBuild: z.string().describe("Source build name"),
+            links: z.array(BuildLinkInput).describe("Target builds to link to"),
+        }, async ({ fromProject, fromBuild, links }) => {
+            const data = await gqlClient.request(SET_BUILD_LINKS, { fromProject, fromBuild, links });
+            const { userErrors } = data.linksBuild;
+            if (userErrors?.length) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: userErrors.map((e) => e.message).join(", ") }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: "Build links updated successfully." }],
+            };
+        });
+}

package/build/tools/build-links.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createTestClient } from "../test/helpers.js";
+import { registerBuildLinkTools } from "./build-links.js";
+vi.mock("../client.js", () => ({
+    gqlClient: { request: vi.fn() },
+}));
+const { gqlClient } = await import("../client.js");
+const mockRequest = gqlClient.request;
+beforeEach(() => {
+    mockRequest.mockReset();
+});
+describe("get_build_links", () => {
+    it("returns using and usedBy links for a build", async () => {
+        const links = {
+            usingQualified: {
+                pageItems: [{ qualifier: null, build: { id: 2, name: "dep-1.0.0", branch: { id: 5, name: "main", project: { id: 3, name: "dep" } } } }],
+                pageInfo: { totalSize: 1 },
+            },
+            usedByQualified: { pageItems: [], pageInfo: { totalSize: 0 } },
+        };
+        mockRequest.mockResolvedValueOnce({ builds: [links] });
+        const client = await createTestClient(registerBuildLinkTools);
+        const result = await client.callTool({
+            name: "get_build_links",
+            arguments: { project: "myproject", branch: "main", build: "1.0.1" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(links);
+    });
+    it("returns nulls when build not found", async () => {
+        mockRequest.mockResolvedValueOnce({ builds: [] });
+        const client = await createTestClient(registerBuildLinkTools);
+        const result = await client.callTool({
+            name: "get_build_links",
+            arguments: { project: "myproject", branch: "main", build: "missing" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual({ usingQualified: null, usedByQualified: null });
+    });
+});
+describe("set_build_links", () => {
+    it("returns success message when links are set", async () => {
+        mockRequest.mockResolvedValueOnce({ linksBuild: { userErrors: [] } });
+        const client = await createTestClient(registerBuildLinkTools);
+        const result = await client.callTool({
+            name: "set_build_links",
+            arguments: {
+                fromProject: "myproject",
+                fromBuild: "1.0.1",
+                links: [{ project: "dep", build: "dep-1.0.0" }],
+            },
+        });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        expect(text).toContain("updated successfully");
+    });
+    it("returns an error when userErrors is non-empty", async () => {
+        mockRequest.mockResolvedValueOnce({
+            linksBuild: { userErrors: [{ message: "Build not found" }] },
+        });
+        const client = await createTestClient(registerBuildLinkTools);
+        const result = await client.callTool({
+            name: "set_build_links",
+            arguments: {
+                fromProject: "myproject",
+                fromBuild: "9.9.9",
+                links: [{ project: "dep", build: "dep-1.0.0" }],
+            },
+        });
+        expect(result.isError).toBe(true);
+        const text = result.content[0].text;
+        expect(text).toContain("Build not found");
+    });
+    it("is not registered when mutations are disabled", async () => {
+        const client = await createTestClient(registerBuildLinkTools, false);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).not.toContain("set_build_links");
+    });
+    it("is registered when mutations are enabled", async () => {
+        const client = await createTestClient(registerBuildLinkTools, true);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).toContain("set_build_links");
+    });
+});

package/build/tools/builds.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { gqlClient } from "../client.js";
+const LIST_BUILDS = `
+  query ListBuilds($project: String!, $branch: String!, $count: Int) {
+    branches(project: $project, name: $branch) {
+      builds(count: $count) {
+        id
+        name
+        displayName
+        description
+        creation { user time }
+      }
+    }
+  }
+`;
+const FIND_BUILD = `
+  query FindBuild($project: String!, $branch: String!, $name: String!) {
+    builds(project: $project, branch: $branch, name: $name) {
+      id
+      name
+      displayName
+      description
+      branch { id name displayName project { id name } }
+      creation { user time }
+      runInfo { sourceType sourceUri triggerType triggerData runTime }
+    }
+  }
+`;
+const GET_BUILD_DURATION = `
+  query GetBuildDuration($project: String!, $branch: String!, $name: String!, $promotion: String!) {
+    builds(project: $project, branch: $branch, name: $name) {
+      creation { time }
+      promotionRuns(promotion: $promotion) {
+        creation { time }
+      }
+    }
+  }
+`;
+const CREATE_BUILD = `
+  mutation CreateBuild(
+    $project: String!
+    $branch: String!
+    $name: String!
+    $description: String
+  ) {
+    createBuild(input: {
+      projectName: $project
+      branchName: $branch
+      name: $name
+      description: $description
+    }) {
+      build { id name displayName description branch { id name displayName project { id name } } }
+      userErrors { message }
+    }
+  }
+`;
+export function registerBuildTools(server, allowMutations) {
+    server.tool("list_builds", "List builds for a branch", {
+        project: z.string().describe("Project name"),
+        branch: z.string().describe("Branch name"),
+        count: z.number().int().optional().default(10).describe("Max number of builds to return"),
+    }, async ({ project, branch, count }) => {
+        const data = await gqlClient.request(LIST_BUILDS, { project, branch, count });
+        const builds = data.branches?.[0]?.builds ?? [];
+        return {
+            content: [{ type: "text", text: JSON.stringify(builds, null, 2) }],
+        };
+    });
+    server.tool("find_build", "Find a specific build by project, branch, and build name", {
+        project: z.string().describe("Project name"),
+        branch: z.string().describe("Branch name"),
+        name: z.string().describe("Build name"),
+    }, async ({ project, branch, name }) => {
+        const data = await gqlClient.request(FIND_BUILD, { project, branch, name });
+        const build = data.builds?.[0] ?? null;
+        return {
+            content: [{ type: "text", text: JSON.stringify(build, null, 2) }],
+        };
+    });
+    if (allowMutations)
+        server.tool("create_build", "Create a new build on a branch", {
+            project: z.string().describe("Project name"),
+            branch: z.string().describe("Branch name"),
+            name: z.string().describe("Build name (e.g. '1.0.42')"),
+            description: z.string().optional().describe("Build description"),
+        }, async ({ project, branch, name, description }) => {
+            const data = await gqlClient.request(CREATE_BUILD, { project, branch, name, description });
+            const { build, userErrors } = data.createBuild;
+            if (userErrors?.length) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: userErrors.map((e) => e.message).join(", ") }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(build, null, 2) }],
+            };
+        });
+    server.tool("get_build_duration", "Get the duration of a build, measured from build creation to its first promotion to a given level (defaults to BRONZE)", {
+        project: z.string().describe("Project name"),
+        branch: z.string().describe("Branch name"),
+        build: z.string().describe("Build name"),
+        promotion: z.string().optional().default("BRONZE").describe("Promotion level name to measure duration against"),
+    }, async ({ project, branch, build, promotion }) => {
+        const data = await gqlClient.request(GET_BUILD_DURATION, { project, branch, name: build, promotion });
+        const buildData = data.builds?.[0];
+        if (!buildData) {
+            return { isError: true, content: [{ type: "text", text: `Build not found: ${build}` }] };
+        }
+        const promotionRun = buildData.promotionRuns?.[0];
+        if (!promotionRun) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            project, branch, build, promotion,
+                            buildCreatedAt: buildData.creation.time,
+                            promoted: false,
+                            durationSeconds: null,
+                        }, null, 2),
+                    }],
+            };
+        }
+        const buildTime = new Date(buildData.creation.time).getTime();
+        const promotionTime = new Date(promotionRun.creation.time).getTime();
+        const durationSeconds = Math.round((promotionTime - buildTime) / 1000);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        project, branch, build, promotion,
+                        buildCreatedAt: buildData.creation.time,
+                        promotedAt: promotionRun.creation.time,
+                        durationSeconds,
+                    }, null, 2),
+                }],
+        };
+    });
+}