User based authentication methods

.github/workflows/npm-publish.yml

@@ -0,0 +1,23 @@
+name: NPM Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  npm:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org/'
+      - name: Install dependencies
+        run: npm ci
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

README.md

@@ -186,80 +186,87 @@ $ sh scripts/image_push.sh docker_user_name
 ## Tools 🛠️
 
 +<!-- TOOLS-START -->
-`verify_namespace` - Verify if a namespace path exists
-`update_wiki_page` - Update an existing wiki page in a GitLab project
-`update_merge_request` - Update a merge request (Either mergeRequestIid or branchName must be provided)
-`update_merge_request_note` - Modify an existing merge request thread note
-`update_label` - Update an existing label in a project
-`update_issue` - Update an issue in a GitLab project
-`update_issue_note` - Modify an existing issue thread note
-`update_draft_note` - Update an existing draft note
-`search_repositories` - Search for GitLab projects
-`retry_pipeline` - Retry a failed or canceled pipeline
-`push_files` - Push multiple files to a GitLab project in a single commit
-`publish_draft_note` - Publish a single draft note
-`promote_milestone` - Promote a milestone to the next stage
-`my_issues` - List issues assigned to the authenticated user
-`mr_discussions` - List discussion items for a merge request
-`list_wiki_pages` - List wiki pages in a GitLab project
-`list_projects` - List projects accessible by the current user
-`list_project_members` - List members of a GitLab project
-`list_pipelines` - List pipelines in a GitLab project with filtering options
-`list_pipeline_trigger_jobs` - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines
-`list_pipeline_jobs` - List all jobs in a specific pipeline
-`list_namespaces` - List all namespaces available to the current user
-`list_milestones` - List milestones in a GitLab project with filtering options
-`list_merge_requests` - List merge requests in a GitLab project with filtering options
-`list_merge_request_diffs` - List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)
-`list_labels` - List labels for a project
-`list_issues` - List issues in a GitLab project with filtering options
-`list_issue_links` - List all issue links for a specific issue
-`list_issue_discussions` - List discussions for an issue in a GitLab project
-`list_group_projects` - List projects in a GitLab group with filtering options
-`list_draft_notes` - List draft notes for a merge request
-`get_wiki_page` - Get details of a specific wiki page
-`get_users` - Get GitLab user details by usernames
-`get_repository_tree` - Get the repository tree for a GitLab project (list files and directories)
-`get_project` - Get details of a specific project
-`get_pipeline` - Get details of a specific pipeline in a GitLab project
-`get_pipeline_job` - Get details of a GitLab pipeline job number
-`get_pipeline_job_output` - Get the output/trace of a GitLab pipeline job number
-`get_namespace` - Get details of a namespace by ID or path
-`get_milestone` - Get details of a specific milestone
-`get_milestone_merge_requests` - Get merge requests associated with a specific milestone
-`get_milestone_issue` - Get issues associated with a specific milestone
-`get_milestone_burndown_events` - Get burndown events for a specific milestone
-`get_merge_request` - Get details of a merge request (Either mergeRequestIid or branchName must be provided)
-`get_merge_request_diffs` - Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)
-`get_label` - Get a single label from a project
-`get_issue` - Get details of a specific issue in a GitLab project
-`get_issue_link` - Get a specific issue link
-`get_file_contents` - Get the contents of a file or directory from a GitLab project
-`get_branch_diffs` - Get the changes/diffs between two branches or commits in a GitLab project
-`fork_repository` - Fork a GitLab project to your account or specified namespace
-`edit_milestone` - Edit an existing milestone in a GitLab project
-`delete_wiki_page` - Delete a wiki page from a GitLab project
-`delete_milestone` - Delete a milestone from a GitLab project
-`delete_label` - Delete a label from a project
-`delete_issue` - Delete an issue from a GitLab project
-`delete_issue_link` - Delete an issue link
-`delete_draft_note` - Delete a draft note
-`download_attachment` - Download an uploaded file from a GitLab project by secret and filename
-`create_wiki_page` - Create a new wiki page in a GitLab project
-`create_repository` - Create a new GitLab project
-`create_pipeline` - Create a new pipeline for a branch or tag
-`create_or_update_file` - Create or update a single file in a GitLab project
-`create_note` - Create a new note (comment) to an issue or merge request
-`create_milestone` - Create a new milestone in a GitLab project
-`create_merge_request` - Create a new merge request in a GitLab project
-`create_merge_request_thread` - Create a new thread on a merge request
-`create_merge_request_note` - Add a new note to an existing merge request thread
-`create_label` - Create a new label in a project
-`create_issue` - Create a new issue in a GitLab project
-`create_issue_note` - Add a new note to an existing issue thread
-`create_issue_link` - Create an issue link between two issues
-`create_draft_note` - Create a draft note for a merge request
-`create_branch` - Create a new branch in a GitLab project
-`cancel_pipeline` - Cancel a running pipeline
-`bulk_publish_draft_notes` - Publish all draft notes for a merge request
+1. `merge_merge_request` - Merge a merge request in a GitLab project
+2. `create_or_update_file` - Create or update a single file in a GitLab project
+3. `search_repositories` - Search for GitLab projects
+4. `create_repository` - Create a new GitLab project
+5. `get_file_contents` - Get the contents of a file or directory from a GitLab project
+6. `push_files` - Push multiple files to a GitLab project in a single commit
+7. `create_issue` - Create a new issue in a GitLab project
+8. `create_merge_request` - Create a new merge request in a GitLab project
+9. `fork_repository` - Fork a GitLab project to your account or specified namespace
+10. `create_branch` - Create a new branch in a GitLab project
+11. `get_merge_request` - Get details of a merge request (Either mergeRequestIid or branchName must be provided)
+12. `get_merge_request_diffs` - Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)
+13. `list_merge_request_diffs` - List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)
+14. `get_branch_diffs` - Get the changes/diffs between two branches or commits in a GitLab project
+15. `update_merge_request` - Update a merge request (Either mergeRequestIid or branchName must be provided)
+16. `create_note` - Create a new note (comment) to an issue or merge request
+17. `create_merge_request_thread` - Create a new thread on a merge request
+18. `mr_discussions` - List discussion items for a merge request
+19. `update_merge_request_note` - Modify an existing merge request thread note
+20. `create_merge_request_note` - Add a new note to an existing merge request thread
+21. `get_draft_note` - Get a single draft note from a merge request
+22. `list_draft_notes` - List draft notes for a merge request
+23. `create_draft_note` - Create a draft note for a merge request
+24. `update_draft_note` - Update an existing draft note
+25. `delete_draft_note` - Delete a draft note
+26. `publish_draft_note` - Publish a single draft note
+27. `bulk_publish_draft_notes` - Publish all draft notes for a merge request
+28. `update_issue_note` - Modify an existing issue thread note
+29. `create_issue_note` - Add a new note to an existing issue thread
+30. `list_issues` - List issues (default: created by current user only; use scope='all' for all accessible issues)
+31. `my_issues` - List issues assigned to the authenticated user (defaults to open issues)
+32. `get_issue` - Get details of a specific issue in a GitLab project
+33. `update_issue` - Update an issue in a GitLab project
+34. `delete_issue` - Delete an issue from a GitLab project
+35. `list_issue_links` - List all issue links for a specific issue
+36. `list_issue_discussions` - List discussions for an issue in a GitLab project
+37. `get_issue_link` - Get a specific issue link
+38. `create_issue_link` - Create an issue link between two issues
+39. `delete_issue_link` - Delete an issue link
+40. `list_namespaces` - List all namespaces available to the current user
+41. `get_namespace` - Get details of a namespace by ID or path
+42. `verify_namespace` - Verify if a namespace path exists
+43. `get_project` - Get details of a specific project
+44. `list_projects` - List projects accessible by the current user
+45. `list_project_members` - List members of a GitLab project
+46. `list_labels` - List labels for a project
+47. `get_label` - Get a single label from a project
+48. `create_label` - Create a new label in a project
+49. `update_label` - Update an existing label in a project
+50. `delete_label` - Delete a label from a project
+51. `list_group_projects` - List projects in a GitLab group with filtering options
+52. `list_wiki_pages` - List wiki pages in a GitLab project
+53. `get_wiki_page` - Get details of a specific wiki page
+54. `create_wiki_page` - Create a new wiki page in a GitLab project
+55. `update_wiki_page` - Update an existing wiki page in a GitLab project
+56. `delete_wiki_page` - Delete a wiki page from a GitLab project
+57. `get_repository_tree` - Get the repository tree for a GitLab project (list files and directories)
+58. `list_pipelines` - List pipelines in a GitLab project with filtering options
+59. `get_pipeline` - Get details of a specific pipeline in a GitLab project
+60. `list_pipeline_jobs` - List all jobs in a specific pipeline
+61. `list_pipeline_trigger_jobs` - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines
+62. `get_pipeline_job` - Get details of a GitLab pipeline job number
+63. `get_pipeline_job_output` - Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage
+64. `create_pipeline` - Create a new pipeline for a branch or tag
+65. `retry_pipeline` - Retry a failed or canceled pipeline
+66. `cancel_pipeline` - Cancel a running pipeline
+67. `list_merge_requests` - List merge requests in a GitLab project with filtering options
+68. `list_milestones` - List milestones in a GitLab project with filtering options
+69. `get_milestone` - Get details of a specific milestone
+70. `create_milestone` - Create a new milestone in a GitLab project
+71. `edit_milestone` - Edit an existing milestone in a GitLab project
+72. `delete_milestone` - Delete a milestone from a GitLab project
+73. `get_milestone_issue` - Get issues associated with a specific milestone
+74. `get_milestone_merge_requests` - Get merge requests associated with a specific milestone
+75. `promote_milestone` - Promote a milestone to the next stage
+76. `get_milestone_burndown_events` - Get burndown events for a specific milestone
+77. `get_users` - Get GitLab user details by usernames
+78. `list_commits` - List repository commits with filtering options
+79. `get_commit` - Get details of a specific commit
+80. `get_commit_diff` - Get changes/diffs of a specific commit
+81. `list_group_iterations` - List group iterations with filtering options
+82. `upload_markdown` - Upload a file to a GitLab project for use in markdown content
+83. `download_attachment` - Download an uploaded file from a GitLab project by secret and filename
 <!-- TOOLS-END -->

docs/oauth2_proxy.md

@@ -0,0 +1,147 @@
+# GitLab MCP OAuth2 Proxy Configuration
+
+This guide explains how to configure the GitLab MCP server to use OAuth2 proxy authentication, allowing users to authenticate with GitLab OAuth2 applications instead of using personal access tokens.
+
+## Overview
+
+The OAuth2 proxy mode enables dynamic client registration and token management, providing a more secure and flexible authentication method compared to static personal access tokens.
+
+**Note:** OAuth2 proxy mode is only available when using SSE or STREAMABLE_HTTP transport modes. It is not supported with STDIO transport.
+
+## Required Environment Variables
+
+To enable OAuth2 proxy mode, you must set the following environment variables:
+
+### Core OAuth2 Configuration
+
+```bash
+# GitLab OAuth2 Application Credentials
+GITLAB_OAUTH2_CLIENT_ID=your_gitlab_app_id
+GITLAB_OAUTH2_CLIENT_SECRET=your_gitlab_app_secret
+
+# GitLab OAuth2 Endpoints
+GITLAB_OAUTH2_AUTHORIZATION_URL=https://gitlab.com/oauth/authorize
+GITLAB_OAUTH2_TOKEN_URL=https://gitlab.com/oauth/token
+GITLAB_OAUTH2_ISSUER_URL=https://gitlab.com
+GITLAB_OAUTH2_BASE_URL=http://localhost:3000  # Your MCP server URL
+
+# OAuth2 Redirect Configuration
+GITLAB_OAUTH2_REDIRECT_URL=http://localhost:3000/callback
+```
+
+### Optional Configuration
+
+```bash
+# Token Revocation Endpoint (optional)
+GITLAB_OAUTH2_REVOCATION_URL=https://gitlab.com/oauth/revoke
+
+# Database Path (defaults to in-memory if not set)
+GITLAB_OAUTH2_DB_PATH=/path/to/oauth.db
+```
+
+## Setting Up a GitLab OAuth2 Application
+
+1. Go to your GitLab instance (e.g., https://gitlab.com)
+2. Navigate to **User Settings** → **Applications**
+3. Create a new application with:
+   - **Name**: Your MCP Server (or any descriptive name)
+   - **Redirect URI**: Must match `GITLAB_OAUTH2_REDIRECT_URL` exactly (e.g., `http://localhost:3000/callback`)
+   - **Scopes**: Select the following:
+     - `api` - Access the authenticated user's API
+     - `openid` - Authenticate using OpenID Connect
+     - `profile` - Read user's profile data
+     - `email` - Read user's email address
+
+4. After creation, GitLab will provide:
+   - **Application ID**: Use this for `GITLAB_OAUTH2_CLIENT_ID`
+   - **Secret**: Use this for `GITLAB_OAUTH2_CLIENT_SECRET`
+
+## Configuration Examples
+
+### Development Setup (localhost)
+
+```bash
+# .env file
+GITLAB_API_URL=https://gitlab.com
+
+GITLAB_OAUTH2_CLIENT_ID=your_app_id_here
+GITLAB_OAUTH2_CLIENT_SECRET=your_app_secret_here
+GITLAB_OAUTH2_AUTHORIZATION_URL=https://gitlab.com/oauth/authorize
+GITLAB_OAUTH2_TOKEN_URL=https://gitlab.com/oauth/token
+GITLAB_OAUTH2_ISSUER_URL=https://gitlab.com
+GITLAB_OAUTH2_BASE_URL=http://localhost:3000
+GITLAB_OAUTH2_REDIRECT_URL=http://localhost:3000/callback
+```
+
+### Production Setup
+
+```bash
+# .env file
+GITLAB_API_URL=https://gitlab.company.com
+
+GITLAB_OAUTH2_CLIENT_ID=your_app_id_here
+GITLAB_OAUTH2_CLIENT_SECRET=your_app_secret_here
+GITLAB_OAUTH2_AUTHORIZATION_URL=https://gitlab.company.com/oauth/authorize
+GITLAB_OAUTH2_TOKEN_URL=https://gitlab.company.com/oauth/token
+GITLAB_OAUTH2_ISSUER_URL=https://gitlab.company.com
+GITLAB_OAUTH2_BASE_URL=https://mcp.company.com
+GITLAB_OAUTH2_REDIRECT_URL=https://mcp.company.com/callback
+GITLAB_OAUTH2_DB_PATH=/var/lib/gitlab-mcp/oauth.db
+```
+
+## Database Storage
+
+By default, the OAuth2 proxy uses an in-memory SQLite database. For production use, specify a persistent database path:
+
+```bash
+GITLAB_OAUTH2_DB_PATH=/path/to/persistent/oauth.db
+```
+
+The database stores:
+- OAuth client registrations
+- State mappings for OAuth flow
+- Access token hashes (using Argon2 for security)
+
+## Security Considerations
+
+1. **Client Secrets**: Never commit `GITLAB_OAUTH2_CLIENT_SECRET` to version control
+2. **HTTPS**: Always use HTTPS for production deployments
+3. **Token Storage**: Access tokens are hashed using Argon2 before storage
+4. **Token Expiry**: Tokens expire after 1 hour by default
+5. **State Expiry**: OAuth state parameters expire after 15 minutes
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Protected resource URL mismatch"**
+   - Ensure `GITLAB_OAUTH2_BASE_URL` matches your server's actual URL
+   - Check that the redirect URI in GitLab matches `GITLAB_OAUTH2_REDIRECT_URL`
+
+2. **"Invalid redirect URI"**
+   - The redirect URI must match exactly (including protocol and port)
+   - No trailing slashes unless specified in GitLab
+
+3. **"Invalid scope"**
+   - Ensure your GitLab OAuth app has the required scopes enabled
+   - The MCP server requests: `api`, `openid`, `profile`, `email`
+
+
+## Starting the Server
+
+OAuth2 proxy mode requires SSE or STREAMABLE_HTTP transport.
+
+The server will log:
+```
+Configuring GitLab OAuth2 proxy authentication
+```
+
+**Note:** STDIO transport mode does not support OAuth2 proxy authentication.
+
+## Client Configuration
+
+MCP clients connecting to an OAuth2-enabled server should use the OAuth2 flow instead of providing a GitLab token directly. The server will handle dynamic client registration and token management automatically.
+
+## Note
+
+OAuth2 proxy support is currently in beta. While functional, it may have limitations compared to personal access token authentication. Please report any issues to the project's issue tracker.