argocd-mcp

Instructions

Implementation Reference

• src/argocd/client.ts:25-66 (handler)

  Core implementation of listApplications: calls ArgoCD API /api/v1/applications, strips heavy fields for token efficiency, applies pagination, returns paginated list with metadata.

  public async listApplications(params?: { search?: string; limit?: number; offset?: number }) {
    const { body } = await this.client.get<V1alpha1ApplicationList>(
      `/api/v1/applications`,
      params?.search ? { search: params.search } : undefined
    );
  
    // Strip heavy fields to reduce token usage
    const strippedItems =
      body.items?.map((app) => ({
        metadata: {
          name: app.metadata?.name,
          namespace: app.metadata?.namespace,
          labels: app.metadata?.labels,
          creationTimestamp: app.metadata?.creationTimestamp
        },
        spec: {
          project: app.spec?.project,
          source: app.spec?.source,
          destination: app.spec?.destination
        },
        status: {
          sync: app.status?.sync,
          health: app.status?.health,
          summary: app.status?.summary
        }
      })) ?? [];
  
    // Apply pagination
    const start = params?.offset ?? 0;
    const end = params?.limit ? start + params.limit : strippedItems.length;
    const items = strippedItems.slice(start, end);
  
    return {
      items,
      metadata: {
        resourceVersion: body.metadata?.resourceVersion,
        totalItems: strippedItems.length,
        returnedItems: items.length,
        hasMore: end < strippedItems.length
      }
    };
  }

• src/server/server.ts:35-67 (registration)

  Registers the 'list_applications' MCP tool: defines name, description, Zod input schema (search, limit, offset), and thin handler delegating to ArgoCDClient.listApplications.

    'list_applications',
    'list_applications returns list of applications',
    {
      search: z
        .string()
        .optional()
        .describe(
          'Search applications by name. This is a partial match on the application name and does not support glob patterns (e.g. "*"). Optional.'
        ),
      limit: z
        .number()
        .int()
        .positive()
        .optional()
        .describe(
          'Maximum number of applications to return. Use this to reduce token usage when there are many applications. Optional.'
        ),
      offset: z
        .number()
        .int()
        .min(0)
        .optional()
        .describe(
          'Number of applications to skip before returning results. Use with limit for pagination. Optional.'
        )
    },
    async ({ search, limit, offset }) =>
      await this.argocdClient.listApplications({
        search: search ?? undefined,
        limit,
        offset
      })
  );

• src/server/server.ts:37-60 (schema)

  Input schema for 'list_applications' tool using Zod: optional search string, positive integer limit, non-negative integer offset with descriptions.

  {
    search: z
      .string()
      .optional()
      .describe(
        'Search applications by name. This is a partial match on the application name and does not support glob patterns (e.g. "*"). Optional.'
      ),
    limit: z
      .number()
      .int()
      .positive()
      .optional()
      .describe(
        'Maximum number of applications to return. Use this to reduce token usage when there are many applications. Optional.'
      ),
    offset: z
      .number()
      .int()
      .min(0)
      .optional()
      .describe(
        'Number of applications to skip before returning results. Use with limit for pagination. Optional.'
      )
  },

• src/server/server.ts:321-341 (helper)

  Helper method to register MCP tools with automatic JSON stringification of results and error handling.

  private addJsonOutputTool<Args extends ZodRawShape, T>(
    name: string,
    description: string,
    paramsSchema: Args,
    cb: (...cbArgs: Parameters<ToolCallback<Args>>) => T
  ) {
    this.tool(name, description, paramsSchema as ZodRawShape, async (...args) => {
      try {
        const result = await cb.apply(this, args as Parameters<ToolCallback<Args>>);
        return {
          isError: false,
          content: [{ type: 'text', text: JSON.stringify(result) }]
        };
      } catch (error) {
        return {
          isError: true,
          content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }]
        };
      }
    });
  }