Octopus Deploy MCP Server

Instructions

Implementation Reference

• src/tools/getVariables.ts:13-55 (registration)

  Primary registration of the 'get_variables' tool on the McpServer. Defines the tool name, description, input schema (using Zod), execution handler, and metadata. The handler fetches variables from Octopus Deploy API.
  export function registerGetVariablesTool(server: McpServer) { server.tool( "get_variables", `This tool gets all project and library variable set variables for a given project. Projects can contain variables (specific to a project), library variable sets (shared collections of variables associated with many projects), and tenant variables (variables related to a tenants connected to the project) If you want to retrieve tenant variables for a tenant connected to the project, use the get_tenant_variables tool. `, { spaceName: z.string().describe("The space name"), projectId: z.string().describe("The ID of the project to retrieve the variables for"), gitRef: z.string().describe("The gitRef to retrieve the variables from, if the project is a config-as-code project").optional(), }, { title: "Get variables for a Project from Octopus Deploy", readOnlyHint: true, }, async ({ spaceName, projectId, gitRef }) => { const configuration = getClientConfigurationFromEnvironment(); const client = await Client.create(configuration); const spaceId = await resolveSpaceId(client, spaceName); const variables = await getAllVariables({ projectId: projectId, spaceName: spaceName, spaceId: spaceId, gitRef: gitRef }, client) return { content: [ { type: "text", text: JSON.stringify({ variables }), }, ], }; } ); }
• src/tools/getVariables.ts:57-61 (registration)

  Registers the tool metadata in the global TOOL_REGISTRY, allowing conditional enabling via toolsets in src/tools/index.ts.
  registerToolDefinition({ toolName: "get_variables", config: { toolset: "projects", readOnly: true }, registerFn: registerGetVariablesTool, });
• src/tools/getVariables.ts:147-163 (helper)

  Helper function called by the handler to fetch all variables for the project: project-specific variable set and included library variable sets.
  export async function getAllVariables( params: GetAllVariablesParams, apiClient: Client ): Promise<AllVariablesForProject> { const { spaceId, spaceName, gitRef, projectId } = params; const projectRepository = new ProjectRepository(apiClient, spaceName); const project = await projectRepository.get(projectId); const projectVariableSet = await loadProjectVariableSet(project, gitRef, apiClient, spaceId); const libraryVariableSets = await loadLibraryVariableSetVariables(project.IncludedLibraryVariableSetIds, apiClient, spaceId); return { projectVariableSet, libraryVariableSets }; }
• src/tools/getVariables.ts:165-228 (helper)

  Helper to load project variable set, handling both database-stored and Git-based (config-as-code) projects by fetching text and sensitive variables separately if needed.
  async function loadProjectVariableSet( project: Project, gitRef: string | undefined, apiClient: Client, spaceId: string ): Promise<VariableSetResponse | undefined> { // This is a bit hacky, but gets around the limitations of our ts client types without having to define // a heap of new types. // We are expecting the type to match { ConversionState: { VariablesAreInGit: true } } // If the variables are stored in git. function hasVariablesInGit(value: unknown): boolean { if (typeof value !== 'object' || value === null || !('ConversionState' in value)) { return false; } const obj = value as Record<string, unknown>; const conversionState = obj.ConversionState; return ( typeof conversionState === 'object' && conversionState !== null && 'VariablesAreInGit' in conversionState && (conversionState as Record<string, unknown>).VariablesAreInGit === true ); } // Check if project has git persistence const hasGitVariables = hasVariablesInGit(project.PersistenceSettings); if (hasGitVariables && !gitRef) { throw new Error(`Missing gitRef for config-as-code project ${project.Name}`); } let resource: VariableSetResource; if (hasGitVariables) { // For git projects, we need to get both text and sensitive variables separately // Retrieve the variable set stored in git for the associated gitRef const textVariableSet = await apiClient.get<VariableSetResource>( `~/api/spaces/${spaceId}/projects/${project.Id}/${gitRef}/variables` ); // Sensitive variables are still stored in the database so that they can be encrypted const sensitiveVariableSet = await apiClient.get<VariableSetResource>( `~/api/spaces/${spaceId}/projects/${project.Id}/variables` ); // Combine variables from both sets resource = { ...textVariableSet, Variables: [...textVariableSet.Variables, ...sensitiveVariableSet.Variables] }; } else { // For database projects, get variables directly resource = await apiClient.get<VariableSetResource>(`~/api/spaces/${spaceId}/variables/${project.VariableSetId}`); } // eslint-disable-next-line @typescript-eslint/no-unused-vars const { ScopeValues, ...result } = resource; return result; }
• src/tools/getVariables.ts:230-265 (helper)

  Helper to load library variable sets included in the project and their associated variables from the Octopus API.
  async function loadLibraryVariableSetVariables( includedLibraryVariableSetIds: string[], apiClient: Client, spaceId: string ): Promise<LibraryVariableSetWithVariables[]> { if (includedLibraryVariableSetIds.length === 0) return []; // Get library variable sets const libraryVariableSets = await apiClient.get<ResourceCollection<LibraryVariableSetResource>>( `~/api/spaces/${spaceId}/libraryvariablesets?ids=${includedLibraryVariableSetIds.join(',')}` ); // Get all variable sets for the library variable sets const variableSetIds = libraryVariableSets.Items.map(lvs => lvs.VariableSetId); const allVariableSets = await apiClient.get<VariableSetResource[]>( `~/api/spaces/${spaceId}/variables/all?ids=${variableSetIds.join(',')}` ); const responseVariableSets: VariableSetResponse[] = allVariableSets.map(resource => { // eslint-disable-next-line @typescript-eslint/no-unused-vars const { ScopeValues, ...result } = resource; return result; }) // Create lookup map const allVariableSetsMap = responseVariableSets.reduce((acc: ResourcesById<VariableSetResponse>, resource) => { acc[resource.Id] = resource; return acc; }, {}); // Combine library variable sets with their variable sets return libraryVariableSets.Items.map(lvs => ({ variableSet: allVariableSetsMap[lvs.VariableSetId], libraryVariableSet: lvs })); }