yontrack-mcp 1.0.0

package/build/tools/promotion-runs.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { gqlClient } from "../client.js";
+const GET_PROMOTION_RUNS = `
+  query GetPromotionRuns(
+    $project: String!
+    $branch: String!
+    $build: String!
+    $promotion: String
+  ) {
+    builds(project: $project, branch: $branch, name: $build) {
+      promotionRuns(promotion: $promotion) {
+        id
+        description
+        creation { user time }
+        promotionLevel { id name }
+      }
+    }
+  }
+`;
+const PROMOTE_BUILD = `
+  mutation PromoteBuild(
+    $project: String!
+    $branch: String!
+    $build: String!
+    $promotion: String!
+    $description: String
+  ) {
+    createPromotionRun(input: {
+      project: $project
+      branch: $branch
+      build: $build
+      promotion: $promotion
+      description: $description
+    }) {
+      promotionRun {
+        id
+        description
+        creation { user time }
+        promotionLevel { id name }
+      }
+      userErrors { message }
+    }
+  }
+`;
+export function registerPromotionRunTools(server, allowMutations) {
+    server.tool("get_promotion_runs", "Get promotion runs for a build, optionally filtered by promotion level", {
+        project: z.string().describe("Project name"),
+        branch: z.string().describe("Branch name"),
+        build: z.string().describe("Build name"),
+        promotion: z.string().optional().describe("Filter by promotion level name"),
+    }, async ({ project, branch, build, promotion }) => {
+        const data = await gqlClient.request(GET_PROMOTION_RUNS, { project, branch, build, promotion });
+        const runs = data.builds?.[0]?.promotionRuns ?? [];
+        return {
+            content: [{ type: "text", text: JSON.stringify(runs, null, 2) }],
+        };
+    });
+    if (allowMutations)
+        server.tool("promote_build", "Promote a build to a promotion level", {
+            project: z.string().describe("Project name"),
+            branch: z.string().describe("Branch name"),
+            build: z.string().describe("Build name"),
+            promotion: z.string().describe("Promotion level name"),
+            description: z.string().optional().describe("Optional description"),
+        }, async ({ project, branch, build, promotion, description }) => {
+            const data = await gqlClient.request(PROMOTE_BUILD, { project, branch, build, promotion, description });
+            const { promotionRun, userErrors } = data.createPromotionRun;
+            if (userErrors?.length) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: userErrors.map((e) => e.message).join(", ") }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(promotionRun, null, 2) }],
+            };
+        });
+}

package/build/tools/promotion-runs.test.js

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createTestClient } from "../test/helpers.js";
+import { registerPromotionRunTools } from "./promotion-runs.js";
+vi.mock("../client.js", () => ({
+    gqlClient: { request: vi.fn() },
+}));
+const { gqlClient } = await import("../client.js");
+const mockRequest = gqlClient.request;
+beforeEach(() => {
+    mockRequest.mockReset();
+});
+describe("get_promotion_runs", () => {
+    it("returns promotion runs for a build", async () => {
+        const runs = [
+            { id: 1, description: null, creation: { user: "alice", time: "2024-01-01T00:00:00Z" }, promotionLevel: { id: 1, name: "BRONZE" } },
+        ];
+        mockRequest.mockResolvedValueOnce({ builds: [{ promotionRuns: runs }] });
+        const client = await createTestClient(registerPromotionRunTools);
+        const result = await client.callTool({
+            name: "get_promotion_runs",
+            arguments: { project: "myproject", branch: "main", build: "1.0.1" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(runs);
+    });
+    it("returns empty array when build not found", async () => {
+        mockRequest.mockResolvedValueOnce({ builds: [] });
+        const client = await createTestClient(registerPromotionRunTools);
+        const result = await client.callTool({
+            name: "get_promotion_runs",
+            arguments: { project: "myproject", branch: "main", build: "missing" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual([]);
+    });
+    it("passes the promotion filter to the GraphQL client", async () => {
+        mockRequest.mockResolvedValueOnce({ builds: [{ promotionRuns: [] }] });
+        const client = await createTestClient(registerPromotionRunTools);
+        await client.callTool({
+            name: "get_promotion_runs",
+            arguments: { project: "myproject", branch: "main", build: "1.0.1", promotion: "GOLD" },
+        });
+        expect(mockRequest).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ promotion: "GOLD" }));
+    });
+});
+describe("promote_build", () => {
+    it("returns the created promotion run", async () => {
+        const run = { id: 5, description: null, creation: { user: "alice", time: "2024-01-01T00:00:00Z" }, promotionLevel: { id: 1, name: "BRONZE" } };
+        mockRequest.mockResolvedValueOnce({ createPromotionRun: { promotionRun: run, userErrors: [] } });
+        const client = await createTestClient(registerPromotionRunTools);
+        const result = await client.callTool({
+            name: "promote_build",
+            arguments: { project: "myproject", branch: "main", build: "1.0.1", promotion: "BRONZE" },
+        });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(run);
+    });
+    it("returns an error when userErrors is non-empty", async () => {
+        mockRequest.mockResolvedValueOnce({
+            createPromotionRun: { promotionRun: null, userErrors: [{ message: "Build not found" }] },
+        });
+        const client = await createTestClient(registerPromotionRunTools);
+        const result = await client.callTool({
+            name: "promote_build",
+            arguments: { project: "myproject", branch: "main", build: "9.9.9", promotion: "BRONZE" },
+        });
+        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(registerPromotionRunTools, false);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).not.toContain("promote_build");
+    });
+    it("is registered when mutations are enabled", async () => {
+        const client = await createTestClient(registerPromotionRunTools, true);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).toContain("promote_build");
+    });
+});

package/build/tools/search.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { gqlClient } from "../client.js";
+const SEARCH = `
+  query Search($token: String!, $type: String, $size: Int) {
+    search(token: $token, type: $type, size: $size) {
+      pageItems {
+        type { id name description }
+        title
+        description
+        accuracy
+      }
+      pageInfo { totalSize }
+    }
+  }
+`;
+export function registerSearchTools(server) {
+    server.tool("search", "Full-text search across all Yontrack entities (projects, branches, builds, etc.)", {
+        token: z.string().describe("Search query"),
+        type: z.string().optional().describe("Entity type filter (e.g. 'project', 'build')"),
+        size: z.number().int().optional().default(10).describe("Max number of results"),
+    }, async ({ token, type, size }) => {
+        const data = await gqlClient.request(SEARCH, { token, type, size });
+        return {
+            content: [{ type: "text", text: JSON.stringify(data.search, null, 2) }],
+        };
+    });
+}

package/build/tools/search.test.js

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createTestClient } from "../test/helpers.js";
+import { registerSearchTools } from "./search.js";
+vi.mock("../client.js", () => ({
+    gqlClient: { request: vi.fn() },
+}));
+const { gqlClient } = await import("../client.js");
+const mockRequest = gqlClient.request;
+beforeEach(() => {
+    mockRequest.mockReset();
+});
+describe("search", () => {
+    it("returns search results", async () => {
+        const search = {
+            pageItems: [
+                { type: { id: "project", name: "Project", description: null }, title: "myproject", description: null, accuracy: 1.0 },
+            ],
+            pageInfo: { totalSize: 1 },
+        };
+        mockRequest.mockResolvedValueOnce({ search });
+        const client = await createTestClient(registerSearchTools);
+        const result = await client.callTool({
+            name: "search",
+            arguments: { token: "myproject" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(search);
+    });
+    it("returns empty results when nothing matches", async () => {
+        const search = { pageItems: [], pageInfo: { totalSize: 0 } };
+        mockRequest.mockResolvedValueOnce({ search });
+        const client = await createTestClient(registerSearchTools);
+        const result = await client.callTool({
+            name: "search",
+            arguments: { token: "zzznomatch" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(search);
+    });
+    it("passes type and size filters to the GraphQL client", async () => {
+        mockRequest.mockResolvedValueOnce({ search: { pageItems: [], pageInfo: { totalSize: 0 } } });
+        const client = await createTestClient(registerSearchTools);
+        await client.callTool({
+            name: "search",
+            arguments: { token: "foo", type: "build", size: 5 },
+        });
+        expect(mockRequest).toHaveBeenCalledWith(expect.any(String), { token: "foo", type: "build", size: 5 });
+    });
+});

package/build/tools/validation-runs.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { gqlClient } from "../client.js";
+const GET_VALIDATION_RUNS = `
+  query GetValidationRuns(
+    $project: String!
+    $branch: String!
+    $build: String!
+    $validationStamp: String
+    $count: Int
+  ) {
+    builds(project: $project, branch: $branch, name: $build) {
+      validationRuns(validationStamp: $validationStamp, count: $count) {
+        id
+        runOrder
+        description
+        lastStatus { statusID { id name } description }
+        creation { user time }
+        validationStamp { id name }
+      }
+    }
+  }
+`;
+const CREATE_VALIDATION_RUN = `
+  mutation CreateValidationRun(
+    $project: String!
+    $branch: String!
+    $build: String!
+    $validationStamp: String!
+    $status: String!
+    $description: String
+  ) {
+    createValidationRun(input: {
+      project: $project
+      branch: $branch
+      build: $build
+      validationStamp: $validationStamp
+      validationRunStatus: $status
+      description: $description
+    }) {
+      validationRun {
+        id
+        runOrder
+        lastStatus { statusID { id name } }
+      }
+      userErrors { message }
+    }
+  }
+`;
+export function registerValidationRunTools(server, allowMutations) {
+    server.tool("get_validation_runs", "Get validation runs for a build, optionally filtered by validation stamp", {
+        project: z.string().describe("Project name"),
+        branch: z.string().describe("Branch name"),
+        build: z.string().describe("Build name"),
+        validationStamp: z.string().optional().describe("Filter by validation stamp name"),
+        count: z.number().int().optional().default(10).describe("Max number of runs to return"),
+    }, async ({ project, branch, build, validationStamp, count }) => {
+        const data = await gqlClient.request(GET_VALIDATION_RUNS, { project, branch, build, validationStamp, count });
+        const runs = data.builds?.[0]?.validationRuns ?? [];
+        return {
+            content: [{ type: "text", text: JSON.stringify(runs, null, 2) }],
+        };
+    });
+    if (allowMutations)
+        server.tool("create_validation_run", "Create a validation run for a build with a status", {
+            project: z.string().describe("Project name"),
+            branch: z.string().describe("Branch name"),
+            build: z.string().describe("Build name"),
+            validationStamp: z.string().describe("Validation stamp name"),
+            status: z
+                .enum(["PASSED", "FAILED", "WARNING", "DEFECTIVE", "INTERRUPTED", "INVESTIGATED"])
+                .describe("Validation status"),
+            description: z.string().optional().describe("Optional description or notes"),
+        }, async ({ project, branch, build, validationStamp, status, description }) => {
+            const data = await gqlClient.request(CREATE_VALIDATION_RUN, {
+                project,
+                branch,
+                build,
+                validationStamp,
+                status,
+                description,
+            });
+            const { validationRun, userErrors } = data.createValidationRun;
+            if (userErrors?.length) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: userErrors.map((e) => e.message).join(", ") }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(validationRun, null, 2) }],
+            };
+        });
+}

package/build/tools/validation-runs.test.js

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createTestClient } from "../test/helpers.js";
+import { registerValidationRunTools } from "./validation-runs.js";
+vi.mock("../client.js", () => ({
+    gqlClient: { request: vi.fn() },
+}));
+const { gqlClient } = await import("../client.js");
+const mockRequest = gqlClient.request;
+beforeEach(() => {
+    mockRequest.mockReset();
+});
+describe("get_validation_runs", () => {
+    it("returns validation runs for a build", async () => {
+        const runs = [
+            { id: 1, runOrder: 1, description: null, lastStatus: { statusID: { id: "PASSED", name: "Passed" }, description: null }, creation: { user: "alice", time: "2024-01-01T00:00:00Z" }, validationStamp: { id: 1, name: "CI" } },
+        ];
+        mockRequest.mockResolvedValueOnce({ builds: [{ validationRuns: runs }] });
+        const client = await createTestClient(registerValidationRunTools);
+        const result = await client.callTool({
+            name: "get_validation_runs",
+            arguments: { project: "myproject", branch: "main", build: "1.0.1" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(runs);
+    });
+    it("returns empty array when build not found", async () => {
+        mockRequest.mockResolvedValueOnce({ builds: [] });
+        const client = await createTestClient(registerValidationRunTools);
+        const result = await client.callTool({
+            name: "get_validation_runs",
+            arguments: { project: "myproject", branch: "main", build: "missing" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual([]);
+    });
+    it("passes the validationStamp filter to the GraphQL client", async () => {
+        mockRequest.mockResolvedValueOnce({ builds: [{ validationRuns: [] }] });
+        const client = await createTestClient(registerValidationRunTools);
+        await client.callTool({
+            name: "get_validation_runs",
+            arguments: { project: "myproject", branch: "main", build: "1.0.1", validationStamp: "CI" },
+        });
+        expect(mockRequest).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ validationStamp: "CI" }));
+    });
+});
+describe("create_validation_run", () => {
+    it("returns the created validation run", async () => {
+        const run = { id: 10, runOrder: 1, lastStatus: { statusID: { id: "PASSED", name: "Passed" } } };
+        mockRequest.mockResolvedValueOnce({ createValidationRun: { validationRun: run, userErrors: [] } });
+        const client = await createTestClient(registerValidationRunTools);
+        const result = await client.callTool({
+            name: "create_validation_run",
+            arguments: { project: "myproject", branch: "main", build: "1.0.1", validationStamp: "CI", status: "PASSED" },
+        });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(run);
+    });
+    it("returns an error when userErrors is non-empty", async () => {
+        mockRequest.mockResolvedValueOnce({
+            createValidationRun: { validationRun: null, userErrors: [{ message: "Validation stamp not found" }] },
+        });
+        const client = await createTestClient(registerValidationRunTools);
+        const result = await client.callTool({
+            name: "create_validation_run",
+            arguments: { project: "myproject", branch: "main", build: "1.0.1", validationStamp: "MISSING", status: "FAILED" },
+        });
+        expect(result.isError).toBe(true);
+        const text = result.content[0].text;
+        expect(text).toContain("Validation stamp not found");
+    });
+    it("is not registered when mutations are disabled", async () => {
+        const client = await createTestClient(registerValidationRunTools, false);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).not.toContain("create_validation_run");
+    });
+    it("is registered when mutations are enabled", async () => {
+        const client = await createTestClient(registerValidationRunTools, true);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).toContain("create_validation_run");
+    });
+});

package/build/tools/validation-stamps.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { gqlClient } from "../client.js";
+import { resolveBranchId } from "../utils.js";
+const LIST_VALIDATION_STAMPS = `
+  query ListValidationStamps($project: String!, $branch: String!, $name: String) {
+    branches(project: $project, name: $branch) {
+      validationStamps(name: $name) {
+        id
+        name
+        description
+      }
+    }
+  }
+`;
+const CREATE_VALIDATION_STAMP = `
+  mutation CreateValidationStampById(
+    $branchId: Int!
+    $name: String!
+    $description: String!
+  ) {
+    createValidationStampById(input: {
+      branchId: $branchId
+      name: $name
+      description: $description
+    }) {
+      validationStamp { id name description }
+      userErrors { message }
+    }
+  }
+`;
+export function registerValidationStampTools(server, allowMutations) {
+    server.tool("list_validation_stamps", "List validation stamps for a branch", {
+        project: z.string().describe("Project name"),
+        branch: z.string().describe("Branch name"),
+        name: z.string().optional().describe("Filter by stamp name"),
+    }, async ({ project, branch, name }) => {
+        const data = await gqlClient.request(LIST_VALIDATION_STAMPS, { project, branch, name });
+        const stamps = data.branches?.[0]?.validationStamps ?? [];
+        return {
+            content: [{ type: "text", text: JSON.stringify(stamps, null, 2) }],
+        };
+    });
+    if (allowMutations)
+        server.tool("create_validation_stamp", "Create a new validation stamp on a branch", {
+            project: z.string().describe("Project name"),
+            branch: z.string().describe("Branch name"),
+            name: z.string().describe("Validation stamp name"),
+            description: z.string().optional().default("").describe("Description"),
+        }, async ({ project, branch, name, description }) => {
+            const branchId = await resolveBranchId(project, branch);
+            const data = await gqlClient.request(CREATE_VALIDATION_STAMP, { branchId, name, description });
+            const { validationStamp, userErrors } = data.createValidationStampById;
+            if (userErrors?.length) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: userErrors.map((e) => e.message).join(", ") }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(validationStamp, null, 2) }],
+            };
+        });
+}

package/build/tools/validation-stamps.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createTestClient } from "../test/helpers.js";
+import { registerValidationStampTools } from "./validation-stamps.js";
+vi.mock("../client.js", () => ({
+    gqlClient: { request: vi.fn() },
+}));
+vi.mock("../utils.js", () => ({
+    resolveBranchId: vi.fn().mockResolvedValue(42),
+}));
+const { gqlClient } = await import("../client.js");
+const mockRequest = gqlClient.request;
+beforeEach(() => {
+    mockRequest.mockReset();
+});
+describe("list_validation_stamps", () => {
+    it("returns validation stamps for a branch", async () => {
+        const stamps = [
+            { id: 1, name: "CI", description: "Continuous integration" },
+        ];
+        mockRequest.mockResolvedValueOnce({ branches: [{ validationStamps: stamps }] });
+        const client = await createTestClient(registerValidationStampTools);
+        const result = await client.callTool({
+            name: "list_validation_stamps",
+            arguments: { project: "myproject", branch: "main" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(stamps);
+    });
+    it("returns empty array when branch not found", async () => {
+        mockRequest.mockResolvedValueOnce({ branches: [] });
+        const client = await createTestClient(registerValidationStampTools);
+        const result = await client.callTool({
+            name: "list_validation_stamps",
+            arguments: { project: "myproject", branch: "missing" },
+        });
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual([]);
+    });
+});
+describe("create_validation_stamp", () => {
+    it("returns the created validation stamp", async () => {
+        const stamp = { id: 5, name: "SECURITY", description: "Security scan" };
+        mockRequest.mockResolvedValueOnce({ createValidationStampById: { validationStamp: stamp, userErrors: [] } });
+        const client = await createTestClient(registerValidationStampTools);
+        const result = await client.callTool({
+            name: "create_validation_stamp",
+            arguments: { project: "myproject", branch: "main", name: "SECURITY", description: "Security scan" },
+        });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        expect(JSON.parse(text)).toEqual(stamp);
+    });
+    it("returns an error when userErrors is non-empty", async () => {
+        mockRequest.mockResolvedValueOnce({
+            createValidationStampById: { validationStamp: null, userErrors: [{ message: "Stamp already exists" }] },
+        });
+        const client = await createTestClient(registerValidationStampTools);
+        const result = await client.callTool({
+            name: "create_validation_stamp",
+            arguments: { project: "myproject", branch: "main", name: "CI" },
+        });
+        expect(result.isError).toBe(true);
+        const text = result.content[0].text;
+        expect(text).toContain("Stamp already exists");
+    });
+    it("is not registered when mutations are disabled", async () => {
+        const client = await createTestClient(registerValidationStampTools, false);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).not.toContain("create_validation_stamp");
+    });
+    it("is registered when mutations are enabled", async () => {
+        const client = await createTestClient(registerValidationStampTools, true);
+        const { tools } = await client.listTools();
+        expect(tools.map((t) => t.name)).toContain("create_validation_stamp");
+    });
+});

package/build/utils.js

@@ -0,0 +1,16 @@
+import { gqlClient } from "./client.js";
+const GET_BRANCH_ID = `
+  query GetBranchId($project: String!, $name: String!) {
+    branches(project: $project, name: $name) {
+      id
+    }
+  }
+`;
+export async function resolveBranchId(project, branch) {
+    const data = await gqlClient.request(GET_BRANCH_ID, { project, name: branch });
+    const found = data.branches?.[0];
+    if (!found) {
+        throw new Error(`Branch '${branch}' not found in project '${project}'`);
+    }
+    return found.id;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "yontrack-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Yontrack (Ontrack CI/CD monitoring platform)",
+  "type": "module",
+  "bin": {
+    "yontrack-mcp": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "dev": "tsx watch src/index.ts",
+    "start": "node build/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "build",
+    "yontrack.graphql"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "express": "^5.2.1",
+    "graphql-request": "^7.1.2",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.0.0",
+    "semantic-release": "^24.2.9",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
+  }
+}