host-mcp-jenkins: Instructions file for GitHub Copilot

Adding a New Jenkins API Feature

Procedure for adding a new MCP tool that maps to a specific Jenkins REST API endpoint.

Prerequisites

• Identify the target Jenkins REST API endpoint (e.g., GET /job/{name}/api/json)
• Determine the HTTP method (GET, POST) and expected response format
• Check the Jenkins API documentation:
  • Remote Access API: https://www.jenkins.io/doc/book/using/remote-access-api/
  • Jenkins Javadoc: https://javadoc.jenkins.io/
• Determine which tool category the feature belongs to:
  • core (src/tools/core.ts) — Jobs, builds, queue, triggers, status
  • logs (src/tools/logs.ts) — Build console output and log search
  • scm (src/tools/scm.ts) — Source control configurations and change sets
  • tests (src/tools/tests.ts) — Test results and flaky test analysis

Step-by-Step Procedure

1. Define TypeScript Types

Add response interfaces in src/jenkins/types.ts for the Jenkins API response structure.

// Example: Adding a new type for a Jenkins plugin API response
export interface JenkinsPluginInfo {
    shortName: string;
    longName: string;
    version: string;
    active: boolean;
    enabled: boolean;
    url?: string;
    [key: string]: unknown; // Allow extra fields from Jenkins
}

Tip: Use [key: string]: unknown on interfaces to handle extra fields Jenkins may return.

2. Register the Tool

Add the tool registration in the appropriate src/tools/{category}.ts file. Follow the existing pattern:

/*
 * ── getPlugins ──────────────────────────────────────────────────────
 * Jenkins API: GET /pluginManager/api/json
 * @see https://javadoc.jenkins.io/hudson/PluginManager.html
 */
server.registerTool(
    "getPlugins",
    {
        description: "Get a list of installed Jenkins plugins",
        inputSchema: {
            // Define input parameters using Zod schemas
            active: z.boolean().default(true).optional()
                .describe("Filter to only active plugins")
        },
        annotations: { readOnlyHint: true } // Set to false for write operations
    },
    async({ active = true }) => {
        logger.debug(`getPlugins: active=${active}`);

        try {
            const data = await client.get<JenkinsPluginList>(
                "/pluginManager/api/json",
                { tree: "plugins[shortName,longName,version,active,enabled,url]" }
            );

            const plugins = active
                ? data.plugins.filter(p => p.active)
                : data.plugins;

            return toMcpResult(toolSuccess(plugins));
        } catch (error) {
            if (error instanceof JenkinsClientError && error.statusCode === 404) {
                return toMcpResult(toolNotFound("Plugin Manager", ""));
            }

            return toMcpResult(toolError(error));
        }
    }
);