Custom GraphQL Query

Instructions

Implementation Reference

• src/tools.ts:256-262 (handler)

  Handler function that executes the custom GraphQL query. It validates user credentials, checks if write operations require authentication, and calls the client.query() method with the provided query string, variables, credentials, and write flag.

  handler: async (input, client, userConfig) => {
    const credentials = input.userCredentials ? validateUserConfig(input.userCredentials) : userConfig;
    if (input.requiresWrite && !credentials) {
      throw new Error('User authentication is required for write operations. Please provide your GitLab credentials.');
    }
    return await client.query(input.query, input.variables, credentials, input.requiresWrite);
  },

• src/tools.ts:240-263 (schema)

  Complete tool definition including input schema with user authentication support. Defines the tool name 'execute_custom_query', description, input schema (query string, optional variables, requiresWrite flag), and handler.

  const executeCustomQueryTool: Tool = {
    name: 'execute_custom_query',
    title: 'Custom GraphQL Query',
    description: 'Execute custom GraphQL queries for complex filtering (e.g., issues with assigneeUsernames: ["user"], labelName: ["bug"]). Use this for structured filtering by assignee/author/labels when search tools return 0 results. Use pagination and limit complexity to avoid timeouts.',
    requiresAuth: false,
    requiresWrite: false,
    annotations: {
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: false,
    },
    inputSchema: withUserAuth(z.object({
      query: z.string().describe('GraphQL query string. Example: query { issues(assigneeUsernames: ["cdhanlon"], state: opened, first: 50) { nodes { iid title webUrl } } }'),
      variables: z.record(z.any()).optional().describe('Variables for the GraphQL query'),
      requiresWrite: z.boolean().default(false).describe('Set to true if this is a mutation that requires write permissions'),
    })),
    handler: async (input, client, userConfig) => {
      const credentials = input.userCredentials ? validateUserConfig(input.userCredentials) : userConfig;
      if (input.requiresWrite && !credentials) {
        throw new Error('User authentication is required for write operations. Please provide your GitLab credentials.');
      }
      return await client.query(input.query, input.variables, credentials, input.requiresWrite);
    },
  };

• src/tools.ts:1294-1310 (registration)

  The tool is registered in the readOnlyTools export array, which makes it available as a read-only tool in the MCP server.

  export const readOnlyTools: Tool[] = [
    getProjectTool,
    getIssuesTool,
    getMergeRequestsTool,
    executeCustomQueryTool,
    getAvailableQueriesTools,
    getMergeRequestPipelinesTool,
    getPipelineJobsTool,
    getMergeRequestDiffsTool,
    getMergeRequestCommitsTool,
    getNotesTool,
    listMilestonesTool,
    listIterationsTool,
    getTimeTrackingTool,
    getMergeRequestReviewersTool,
    getProjectStatisticsTool,
  ];

• src/tools.ts:1339-1349 (registration)

  The tool is also included in the main tools export array that aggregates all tool categories (readOnlyTools, userAuthTools, writeTools, and searchTools).

  export const tools: Tool[] = [
    ...readOnlyTools,
    ...userAuthTools,
    ...writeTools,
    updateIssueTool,
    updateMergeRequestTool,
    resolvePathTool,
    getGroupProjectsTool,
    getTypeFieldsTool,
    ...searchTools,
  ];

• src/gitlab-client.ts:306-312 (helper)

  The client.query method that actually executes GraphQL queries with retry logic. It gets the appropriate GraphQL client (user-specific or shared) and executes the query with exponential backoff retry for reliability.

  async query<T = any>(query: string, variables?: any, userConfig?: UserConfig, requiresWrite = false): Promise<T> {
    const client = this.getClient(userConfig, requiresWrite);
    return this.executeWithRetry(
      () => client.request<T>(query, variables),
      'GraphQL query'
    );
  }