mcp-gitlab-jira

Instructions

Implementation Reference

• src/gitlab.service.ts:473-507 (handler)

  Core handler function that implements the tool logic: queries GitLab API for exact username match first, falls back to fuzzy search on username and name, returns the user ID or throws descriptive errors.

  async getUserIdByUsername(username: string): Promise<number> {
    // First try exact username match
    const exactUsers = await this.callGitLabApi<GitLabUser[]>(
      `users?username=${username}`,
    );
    if (exactUsers.length > 0) {
      return exactUsers[0].id;
    }
  
    // Fallback: search all users and filter by partial username (case-insensitive)
    const allUsers =
      await this.callGitLabApi<GitLabUser[]>(`users?per_page=100`);
    const lowerCaseUsername = username.toLowerCase();
  
    const matchingUsers = allUsers.filter(
      (user) =>
        user.username.toLowerCase().includes(lowerCaseUsername) ||
        user.name.toLowerCase().includes(lowerCaseUsername),
    );
  
    if (matchingUsers.length === 0) {
      throw new Error(`User with username containing '${username}' not found.`);
    }
  
    if (matchingUsers.length > 1) {
      const userList = matchingUsers
        .map((user) => `${user.username} (${user.name})`)
        .join(', ');
      throw new Error(
        `Multiple users found matching '${username}': ${userList}. Please be more specific.`,
      );
    }
  
    return matchingUsers[0].id;
  }

• src/index.ts:1430-1444 (registration)

  Tool execution handler in the MCP server request handler switch statement: extracts username argument, calls the service method, and returns the userId in JSON format.

  case 'gitlab_get_user_id_by_username': {
    if (!gitlabService) {
      throw new Error('GitLab service is not initialized.');
    }
    const { username } = args as { username: string };
    const userId = await gitlabService.getUserIdByUsername(username);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({ userId }, null, 2),
        },
      ],
    };
  }

• src/index.ts:271-284 (schema)

  Tool registration in the allTools array, including the tool name, description, and input schema defining the required 'username' string parameter.

  {
    name: 'gitlab_get_user_id_by_username',
    description: 'Retrieves the GitLab user ID for a given username.',
    inputSchema: {
      type: 'object',
      properties: {
        username: {
          type: 'string',
          description: 'The username of the GitLab user.',
        },
      },
      required: ['username'],
    },
  },

• src/gitlab.ts:151-158 (schema)

  TypeScript interface defining the GitLabUser object structure used by the handler for API responses.

  export interface GitLabUser {
    id: number;
    username: string;
    name: string;
    state: string;
    avatar_url: string;
    web_url: string;
  }