Skip to content

Commit 841e3ab

Browse files
elee1766hwittenborniwakitakuma33zereight
authored
User based authentication methods (#130)
* noot * noot * wip * wip * wip * noot * noot * noot * noot * noot * add some ai documentation * multiple transports * argon2 fix * npm i * change default token expiry * noot * fix build * remove unused env var * add some logging * add GITLAB_API_URL to the examples * argon2 warning * Fix list of tools * feat: Add NPM publish workflow for automated package publishing (#208) * single logger --------- Co-authored-by: Hunter Wittenborn <[email protected]> Co-authored-by: iwakitakuma <[email protected]> Co-authored-by: zereight <[email protected]>
1 parent d5a652d commit 841e3ab

18 files changed

+7176
-5439
lines changed

‎.github/workflows/npm-publish.yml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: NPM Publish
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
npm:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout code
12+
uses: actions/checkout@v4
13+
- name: Setup Node.js
14+
uses: actions/setup-node@v4
15+
with:
16+
node-version: '20'
17+
registry-url: 'https://registry.npmjs.org/'
18+
- name: Install dependencies
19+
run: npm ci
20+
- name: Publish to npm
21+
env:
22+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
23+
run: npm publish --access public

‎README.md

Lines changed: 83 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -186,80 +186,87 @@ $ sh scripts/image_push.sh docker_user_name
186186
## Tools 🛠️
187187

188188
+<!-- TOOLS-START -->
189-
`verify_namespace` - Verify if a namespace path exists
190-
`update_wiki_page` - Update an existing wiki page in a GitLab project
191-
`update_merge_request` - Update a merge request (Either mergeRequestIid or branchName must be provided)
192-
`update_merge_request_note` - Modify an existing merge request thread note
193-
`update_label` - Update an existing label in a project
194-
`update_issue` - Update an issue in a GitLab project
195-
`update_issue_note` - Modify an existing issue thread note
196-
`update_draft_note` - Update an existing draft note
197-
`search_repositories` - Search for GitLab projects
198-
`retry_pipeline` - Retry a failed or canceled pipeline
199-
`push_files` - Push multiple files to a GitLab project in a single commit
200-
`publish_draft_note` - Publish a single draft note
201-
`promote_milestone` - Promote a milestone to the next stage
202-
`my_issues` - List issues assigned to the authenticated user
203-
`mr_discussions` - List discussion items for a merge request
204-
`list_wiki_pages` - List wiki pages in a GitLab project
205-
`list_projects` - List projects accessible by the current user
206-
`list_project_members` - List members of a GitLab project
207-
`list_pipelines` - List pipelines in a GitLab project with filtering options
208-
`list_pipeline_trigger_jobs` - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines
209-
`list_pipeline_jobs` - List all jobs in a specific pipeline
210-
`list_namespaces` - List all namespaces available to the current user
211-
`list_milestones` - List milestones in a GitLab project with filtering options
212-
`list_merge_requests` - List merge requests in a GitLab project with filtering options
213-
`list_merge_request_diffs` - List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)
214-
`list_labels` - List labels for a project
215-
`list_issues` - List issues in a GitLab project with filtering options
216-
`list_issue_links` - List all issue links for a specific issue
217-
`list_issue_discussions` - List discussions for an issue in a GitLab project
218-
`list_group_projects` - List projects in a GitLab group with filtering options
219-
`list_draft_notes` - List draft notes for a merge request
220-
`get_wiki_page` - Get details of a specific wiki page
221-
`get_users` - Get GitLab user details by usernames
222-
`get_repository_tree` - Get the repository tree for a GitLab project (list files and directories)
223-
`get_project` - Get details of a specific project
224-
`get_pipeline` - Get details of a specific pipeline in a GitLab project
225-
`get_pipeline_job` - Get details of a GitLab pipeline job number
226-
`get_pipeline_job_output` - Get the output/trace of a GitLab pipeline job number
227-
`get_namespace` - Get details of a namespace by ID or path
228-
`get_milestone` - Get details of a specific milestone
229-
`get_milestone_merge_requests` - Get merge requests associated with a specific milestone
230-
`get_milestone_issue` - Get issues associated with a specific milestone
231-
`get_milestone_burndown_events` - Get burndown events for a specific milestone
232-
`get_merge_request` - Get details of a merge request (Either mergeRequestIid or branchName must be provided)
233-
`get_merge_request_diffs` - Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)
234-
`get_label` - Get a single label from a project
235-
`get_issue` - Get details of a specific issue in a GitLab project
236-
`get_issue_link` - Get a specific issue link
237-
`get_file_contents` - Get the contents of a file or directory from a GitLab project
238-
`get_branch_diffs` - Get the changes/diffs between two branches or commits in a GitLab project
239-
`fork_repository` - Fork a GitLab project to your account or specified namespace
240-
`edit_milestone` - Edit an existing milestone in a GitLab project
241-
`delete_wiki_page` - Delete a wiki page from a GitLab project
242-
`delete_milestone` - Delete a milestone from a GitLab project
243-
`delete_label` - Delete a label from a project
244-
`delete_issue` - Delete an issue from a GitLab project
245-
`delete_issue_link` - Delete an issue link
246-
`delete_draft_note` - Delete a draft note
247-
`download_attachment` - Download an uploaded file from a GitLab project by secret and filename
248-
`create_wiki_page` - Create a new wiki page in a GitLab project
249-
`create_repository` - Create a new GitLab project
250-
`create_pipeline` - Create a new pipeline for a branch or tag
251-
`create_or_update_file` - Create or update a single file in a GitLab project
252-
`create_note` - Create a new note (comment) to an issue or merge request
253-
`create_milestone` - Create a new milestone in a GitLab project
254-
`create_merge_request` - Create a new merge request in a GitLab project
255-
`create_merge_request_thread` - Create a new thread on a merge request
256-
`create_merge_request_note` - Add a new note to an existing merge request thread
257-
`create_label` - Create a new label in a project
258-
`create_issue` - Create a new issue in a GitLab project
259-
`create_issue_note` - Add a new note to an existing issue thread
260-
`create_issue_link` - Create an issue link between two issues
261-
`create_draft_note` - Create a draft note for a merge request
262-
`create_branch` - Create a new branch in a GitLab project
263-
`cancel_pipeline` - Cancel a running pipeline
264-
`bulk_publish_draft_notes` - Publish all draft notes for a merge request
189+
1. `merge_merge_request` - Merge a merge request in a GitLab project
190+
2. `create_or_update_file` - Create or update a single file in a GitLab project
191+
3. `search_repositories` - Search for GitLab projects
192+
4. `create_repository` - Create a new GitLab project
193+
5. `get_file_contents` - Get the contents of a file or directory from a GitLab project
194+
6. `push_files` - Push multiple files to a GitLab project in a single commit
195+
7. `create_issue` - Create a new issue in a GitLab project
196+
8. `create_merge_request` - Create a new merge request in a GitLab project
197+
9. `fork_repository` - Fork a GitLab project to your account or specified namespace
198+
10. `create_branch` - Create a new branch in a GitLab project
199+
11. `get_merge_request` - Get details of a merge request (Either mergeRequestIid or branchName must be provided)
200+
12. `get_merge_request_diffs` - Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)
201+
13. `list_merge_request_diffs` - List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)
202+
14. `get_branch_diffs` - Get the changes/diffs between two branches or commits in a GitLab project
203+
15. `update_merge_request` - Update a merge request (Either mergeRequestIid or branchName must be provided)
204+
16. `create_note` - Create a new note (comment) to an issue or merge request
205+
17. `create_merge_request_thread` - Create a new thread on a merge request
206+
18. `mr_discussions` - List discussion items for a merge request
207+
19. `update_merge_request_note` - Modify an existing merge request thread note
208+
20. `create_merge_request_note` - Add a new note to an existing merge request thread
209+
21. `get_draft_note` - Get a single draft note from a merge request
210+
22. `list_draft_notes` - List draft notes for a merge request
211+
23. `create_draft_note` - Create a draft note for a merge request
212+
24. `update_draft_note` - Update an existing draft note
213+
25. `delete_draft_note` - Delete a draft note
214+
26. `publish_draft_note` - Publish a single draft note
215+
27. `bulk_publish_draft_notes` - Publish all draft notes for a merge request
216+
28. `update_issue_note` - Modify an existing issue thread note
217+
29. `create_issue_note` - Add a new note to an existing issue thread
218+
30. `list_issues` - List issues (default: created by current user only; use scope='all' for all accessible issues)
219+
31. `my_issues` - List issues assigned to the authenticated user (defaults to open issues)
220+
32. `get_issue` - Get details of a specific issue in a GitLab project
221+
33. `update_issue` - Update an issue in a GitLab project
222+
34. `delete_issue` - Delete an issue from a GitLab project
223+
35. `list_issue_links` - List all issue links for a specific issue
224+
36. `list_issue_discussions` - List discussions for an issue in a GitLab project
225+
37. `get_issue_link` - Get a specific issue link
226+
38. `create_issue_link` - Create an issue link between two issues
227+
39. `delete_issue_link` - Delete an issue link
228+
40. `list_namespaces` - List all namespaces available to the current user
229+
41. `get_namespace` - Get details of a namespace by ID or path
230+
42. `verify_namespace` - Verify if a namespace path exists
231+
43. `get_project` - Get details of a specific project
232+
44. `list_projects` - List projects accessible by the current user
233+
45. `list_project_members` - List members of a GitLab project
234+
46. `list_labels` - List labels for a project
235+
47. `get_label` - Get a single label from a project
236+
48. `create_label` - Create a new label in a project
237+
49. `update_label` - Update an existing label in a project
238+
50. `delete_label` - Delete a label from a project
239+
51. `list_group_projects` - List projects in a GitLab group with filtering options
240+
52. `list_wiki_pages` - List wiki pages in a GitLab project
241+
53. `get_wiki_page` - Get details of a specific wiki page
242+
54. `create_wiki_page` - Create a new wiki page in a GitLab project
243+
55. `update_wiki_page` - Update an existing wiki page in a GitLab project
244+
56. `delete_wiki_page` - Delete a wiki page from a GitLab project
245+
57. `get_repository_tree` - Get the repository tree for a GitLab project (list files and directories)
246+
58. `list_pipelines` - List pipelines in a GitLab project with filtering options
247+
59. `get_pipeline` - Get details of a specific pipeline in a GitLab project
248+
60. `list_pipeline_jobs` - List all jobs in a specific pipeline
249+
61. `list_pipeline_trigger_jobs` - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines
250+
62. `get_pipeline_job` - Get details of a GitLab pipeline job number
251+
63. `get_pipeline_job_output` - Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage
252+
64. `create_pipeline` - Create a new pipeline for a branch or tag
253+
65. `retry_pipeline` - Retry a failed or canceled pipeline
254+
66. `cancel_pipeline` - Cancel a running pipeline
255+
67. `list_merge_requests` - List merge requests in a GitLab project with filtering options
256+
68. `list_milestones` - List milestones in a GitLab project with filtering options
257+
69. `get_milestone` - Get details of a specific milestone
258+
70. `create_milestone` - Create a new milestone in a GitLab project
259+
71. `edit_milestone` - Edit an existing milestone in a GitLab project
260+
72. `delete_milestone` - Delete a milestone from a GitLab project
261+
73. `get_milestone_issue` - Get issues associated with a specific milestone
262+
74. `get_milestone_merge_requests` - Get merge requests associated with a specific milestone
263+
75. `promote_milestone` - Promote a milestone to the next stage
264+
76. `get_milestone_burndown_events` - Get burndown events for a specific milestone
265+
77. `get_users` - Get GitLab user details by usernames
266+
78. `list_commits` - List repository commits with filtering options
267+
79. `get_commit` - Get details of a specific commit
268+
80. `get_commit_diff` - Get changes/diffs of a specific commit
269+
81. `list_group_iterations` - List group iterations with filtering options
270+
82. `upload_markdown` - Upload a file to a GitLab project for use in markdown content
271+
83. `download_attachment` - Download an uploaded file from a GitLab project by secret and filename
265272
<!-- TOOLS-END -->

‎docs/oauth2_proxy.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# GitLab MCP OAuth2 Proxy Configuration
2+
3+
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.
4+
5+
## Overview
6+
7+
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.
8+
9+
**Note:** OAuth2 proxy mode is only available when using SSE or STREAMABLE_HTTP transport modes. It is not supported with STDIO transport.
10+
11+
## Required Environment Variables
12+
13+
To enable OAuth2 proxy mode, you must set the following environment variables:
14+
15+
### Core OAuth2 Configuration
16+
17+
```bash
18+
# GitLab OAuth2 Application Credentials
19+
GITLAB_OAUTH2_CLIENT_ID=your_gitlab_app_id
20+
GITLAB_OAUTH2_CLIENT_SECRET=your_gitlab_app_secret
21+
22+
# GitLab OAuth2 Endpoints
23+
GITLAB_OAUTH2_AUTHORIZATION_URL=https://gitlab.com/oauth/authorize
24+
GITLAB_OAUTH2_TOKEN_URL=https://gitlab.com/oauth/token
25+
GITLAB_OAUTH2_ISSUER_URL=https://gitlab.com
26+
GITLAB_OAUTH2_BASE_URL=http://localhost:3000 # Your MCP server URL
27+
28+
# OAuth2 Redirect Configuration
29+
GITLAB_OAUTH2_REDIRECT_URL=http://localhost:3000/callback
30+
```
31+
32+
### Optional Configuration
33+
34+
```bash
35+
# Token Revocation Endpoint (optional)
36+
GITLAB_OAUTH2_REVOCATION_URL=https://gitlab.com/oauth/revoke
37+
38+
# Database Path (defaults to in-memory if not set)
39+
GITLAB_OAUTH2_DB_PATH=/path/to/oauth.db
40+
```
41+
42+
## Setting Up a GitLab OAuth2 Application
43+
44+
1. Go to your GitLab instance (e.g., https://gitlab.com)
45+
2. Navigate to **User Settings** → **Applications**
46+
3. Create a new application with:
47+
- **Name**: Your MCP Server (or any descriptive name)
48+
- **Redirect URI**: Must match `GITLAB_OAUTH2_REDIRECT_URL` exactly (e.g., `http://localhost:3000/callback`)
49+
- **Scopes**: Select the following:
50+
- `api` - Access the authenticated user's API
51+
- `openid` - Authenticate using OpenID Connect
52+
- `profile` - Read user's profile data
53+
- `email` - Read user's email address
54+
55+
4. After creation, GitLab will provide:
56+
- **Application ID**: Use this for `GITLAB_OAUTH2_CLIENT_ID`
57+
- **Secret**: Use this for `GITLAB_OAUTH2_CLIENT_SECRET`
58+
59+
## Configuration Examples
60+
61+
### Development Setup (localhost)
62+
63+
```bash
64+
# .env file
65+
GITLAB_API_URL=https://gitlab.com
66+
67+
GITLAB_OAUTH2_CLIENT_ID=your_app_id_here
68+
GITLAB_OAUTH2_CLIENT_SECRET=your_app_secret_here
69+
GITLAB_OAUTH2_AUTHORIZATION_URL=https://gitlab.com/oauth/authorize
70+
GITLAB_OAUTH2_TOKEN_URL=https://gitlab.com/oauth/token
71+
GITLAB_OAUTH2_ISSUER_URL=https://gitlab.com
72+
GITLAB_OAUTH2_BASE_URL=http://localhost:3000
73+
GITLAB_OAUTH2_REDIRECT_URL=http://localhost:3000/callback
74+
```
75+
76+
### Production Setup
77+
78+
```bash
79+
# .env file
80+
GITLAB_API_URL=https://gitlab.company.com
81+
82+
GITLAB_OAUTH2_CLIENT_ID=your_app_id_here
83+
GITLAB_OAUTH2_CLIENT_SECRET=your_app_secret_here
84+
GITLAB_OAUTH2_AUTHORIZATION_URL=https://gitlab.company.com/oauth/authorize
85+
GITLAB_OAUTH2_TOKEN_URL=https://gitlab.company.com/oauth/token
86+
GITLAB_OAUTH2_ISSUER_URL=https://gitlab.company.com
87+
GITLAB_OAUTH2_BASE_URL=https://mcp.company.com
88+
GITLAB_OAUTH2_REDIRECT_URL=https://mcp.company.com/callback
89+
GITLAB_OAUTH2_DB_PATH=/var/lib/gitlab-mcp/oauth.db
90+
```
91+
92+
## Database Storage
93+
94+
By default, the OAuth2 proxy uses an in-memory SQLite database. For production use, specify a persistent database path:
95+
96+
```bash
97+
GITLAB_OAUTH2_DB_PATH=/path/to/persistent/oauth.db
98+
```
99+
100+
The database stores:
101+
- OAuth client registrations
102+
- State mappings for OAuth flow
103+
- Access token hashes (using Argon2 for security)
104+
105+
## Security Considerations
106+
107+
1. **Client Secrets**: Never commit `GITLAB_OAUTH2_CLIENT_SECRET` to version control
108+
2. **HTTPS**: Always use HTTPS for production deployments
109+
3. **Token Storage**: Access tokens are hashed using Argon2 before storage
110+
4. **Token Expiry**: Tokens expire after 1 hour by default
111+
5. **State Expiry**: OAuth state parameters expire after 15 minutes
112+
113+
## Troubleshooting
114+
115+
### Common Issues
116+
117+
1. **"Protected resource URL mismatch"**
118+
- Ensure `GITLAB_OAUTH2_BASE_URL` matches your server's actual URL
119+
- Check that the redirect URI in GitLab matches `GITLAB_OAUTH2_REDIRECT_URL`
120+
121+
2. **"Invalid redirect URI"**
122+
- The redirect URI must match exactly (including protocol and port)
123+
- No trailing slashes unless specified in GitLab
124+
125+
3. **"Invalid scope"**
126+
- Ensure your GitLab OAuth app has the required scopes enabled
127+
- The MCP server requests: `api`, `openid`, `profile`, `email`
128+
129+
130+
## Starting the Server
131+
132+
OAuth2 proxy mode requires SSE or STREAMABLE_HTTP transport.
133+
134+
The server will log:
135+
```
136+
Configuring GitLab OAuth2 proxy authentication
137+
```
138+
139+
**Note:** STDIO transport mode does not support OAuth2 proxy authentication.
140+
141+
## Client Configuration
142+
143+
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.
144+
145+
## Note
146+
147+
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.

0 commit comments

Comments
 (0)