gitlab-mcp-agent-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# gitlab-mcp-agent-server
+
+MCP server for GitLab integration (TypeScript + Node.js).
+
+Полный пользовательский сценарий подключения к ИИ-агенту:
+- `docs/USER_GUIDE.md`
+
+## Run with npx
+
+```bash
+npx -y gitlab-mcp-agent-server
+```
+
+Для конечного пользователя обычно достаточно:
+1. Зарегистрировать GitLab OAuth application.
+2. Передать в MCP-конфиг `GITLAB_OAUTH_CLIENT_ID` и `GITLAB_OAUTH_CLIENT_SECRET`.
+
+Остальное работает по дефолту:
+- OAuth auto-login при отсутствии токена.
+- token store в `~/.config/gitlab-mcp/token.json`.
+- auto-refresh access token.
+- автоопределение проекта из git remote текущего `cwd`.
+
+## Local setup (development)
+
+```bash
+npm install
+cp .env.example .env
+npm run dev
+```
+
+## Build and run
+
+```bash
+npm run build
+npm start
+```
+
+## Quality checks
+
+```bash
+npm run lint
+npm run test
+npm run typecheck
+```

package/bin/gitlab-mcp-server.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../build/src/index.js');

package/build/src/application/policies/issue-workflow-policy.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IssueWorkflowPolicy = void 0;
+const errors_1 = require("../../shared/errors");
+class IssueWorkflowPolicy {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    assertEnabled() {
+        if (!this.config.issueWorkflow.enabled) {
+            throw new errors_1.PolicyError('Issue workflow is disabled by configuration.');
+        }
+    }
+    assertActionAllowed(action) {
+        this.assertEnabled();
+        if (action === 'create' && !this.config.issueWorkflow.allowCreate) {
+            throw new errors_1.PolicyError('Issue creation is disabled by configuration.');
+        }
+        if (action === 'close' && !this.config.issueWorkflow.allowClose) {
+            throw new errors_1.PolicyError('Issue closing is disabled by configuration.');
+        }
+        if (action === 'label_update' && !this.config.issueWorkflow.allowLabelUpdate) {
+            throw new errors_1.PolicyError('Issue label updates are disabled by configuration.');
+        }
+    }
+    assertLabelsAllowed(labels) {
+        const allowed = this.config.issueWorkflow.allowedLabels;
+        if (allowed.length === 0) {
+            return;
+        }
+        const invalid = labels.filter((label) => !allowed.includes(label));
+        if (invalid.length > 0) {
+            throw new errors_1.PolicyError(`Labels are not allowed by policy: ${invalid.join(', ')}. Allowed: ${allowed.join(', ')}.`);
+        }
+    }
+}
+exports.IssueWorkflowPolicy = IssueWorkflowPolicy;

package/build/src/application/services/project-resolver.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectResolver = void 0;
+const errors_1 = require("../../shared/errors");
+class ProjectResolver {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    resolveProject(project) {
+        if (project !== undefined && project !== null && String(project).trim() !== '') {
+            return project;
+        }
+        if (this.config.gitlab.defaultProject) {
+            return this.config.gitlab.defaultProject;
+        }
+        if (this.config.gitlab.autoResolveProjectFromGit && this.config.gitlab.autoDetectedProject) {
+            return this.config.gitlab.autoDetectedProject;
+        }
+        throw new errors_1.ConfigurationError('Project is not resolved. Provide `project` in tool input or set GITLAB_DEFAULT_PROJECT.');
+    }
+}
+exports.ProjectResolver = ProjectResolver;

package/build/src/application/use-cases/close-issue.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloseIssueUseCase = void 0;
+class CloseIssueUseCase {
+    gitlabApi;
+    constructor(gitlabApi) {
+        this.gitlabApi = gitlabApi;
+    }
+    async execute(input) {
+        return this.gitlabApi.closeIssue(input);
+    }
+}
+exports.CloseIssueUseCase = CloseIssueUseCase;

package/build/src/application/use-cases/create-issue.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateIssueUseCase = void 0;
+class CreateIssueUseCase {
+    gitlabApi;
+    constructor(gitlabApi) {
+        this.gitlabApi = gitlabApi;
+    }
+    async execute(input) {
+        return this.gitlabApi.createIssue(input);
+    }
+}
+exports.CreateIssueUseCase = CreateIssueUseCase;

package/build/src/application/use-cases/ensure-labels.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnsureLabelsUseCase = void 0;
+class EnsureLabelsUseCase {
+    gitlabApi;
+    constructor(gitlabApi) {
+        this.gitlabApi = gitlabApi;
+    }
+    async execute(input) {
+        const existingLabels = await this.gitlabApi.listLabels({
+            project: input.project
+        });
+        const existingByName = new Map(existingLabels.map((label) => [label.name, label]));
+        const created = [];
+        const existing = [];
+        for (const item of input.labels) {
+            const alreadyExists = existingByName.get(item.name);
+            if (alreadyExists) {
+                existing.push(alreadyExists);
+                continue;
+            }
+            const payload = {
+                project: input.project,
+                name: item.name,
+                color: item.color,
+                description: item.description
+            };
+            const createdLabel = await this.gitlabApi.createLabel(payload);
+            created.push(createdLabel);
+        }
+        return { created, existing };
+    }
+}
+exports.EnsureLabelsUseCase = EnsureLabelsUseCase;

package/build/src/application/use-cases/get-issue.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetIssueUseCase = void 0;
+class GetIssueUseCase {
+    gitlabApi;
+    constructor(gitlabApi) {
+        this.gitlabApi = gitlabApi;
+    }
+    async execute(input) {
+        return this.gitlabApi.getIssue(input);
+    }
+}
+exports.GetIssueUseCase = GetIssueUseCase;

package/build/src/application/use-cases/health-check.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthCheckUseCase = void 0;
+class HealthCheckUseCase {
+    execute(input) {
+        return {
+            status: 'ok',
+            echo: input.ping ?? 'pong'
+        };
+    }
+}
+exports.HealthCheckUseCase = HealthCheckUseCase;

package/build/src/application/use-cases/list-issues.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListIssuesUseCase = void 0;
+class ListIssuesUseCase {
+    gitlabApi;
+    constructor(gitlabApi) {
+        this.gitlabApi = gitlabApi;
+    }
+    async execute(input) {
+        return this.gitlabApi.listIssues(input);
+    }
+}
+exports.ListIssuesUseCase = ListIssuesUseCase;

package/build/src/application/use-cases/list-labels.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListLabelsUseCase = void 0;
+class ListLabelsUseCase {
+    gitlabApi;
+    constructor(gitlabApi) {
+        this.gitlabApi = gitlabApi;
+    }
+    async execute(input) {
+        return this.gitlabApi.listLabels(input);
+    }
+}
+exports.ListLabelsUseCase = ListLabelsUseCase;

package/build/src/application/use-cases/list-projects.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListProjectsUseCase = void 0;
+class ListProjectsUseCase {
+    gitlabApi;
+    constructor(gitlabApi) {
+        this.gitlabApi = gitlabApi;
+    }
+    async execute() {
+        return this.gitlabApi.listProjects();
+    }
+}
+exports.ListProjectsUseCase = ListProjectsUseCase;

package/build/src/application/use-cases/update-issue-labels.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateIssueLabelsUseCase = void 0;
+class UpdateIssueLabelsUseCase {
+    gitlabApi;
+    constructor(gitlabApi) {
+        this.gitlabApi = gitlabApi;
+    }
+    async execute(input) {
+        const current = await this.gitlabApi.getIssue({
+            project: input.project,
+            issueIid: input.issueIid
+        });
+        let nextLabels = [...current.labels];
+        if (input.mode === 'replace') {
+            nextLabels = [...input.labels];
+        }
+        if (input.mode === 'add') {
+            nextLabels = mergeLabels(nextLabels, input.labels);
+        }
+        if (input.mode === 'remove') {
+            nextLabels = nextLabels.filter((label) => !input.labels.includes(label));
+        }
+        if (input.autoRemovePreviousStateLabels && input.stateLabels && input.mode !== 'remove') {
+            nextLabels = removeOtherStateLabels(nextLabels, input.labels, input.stateLabels);
+        }
+        return this.gitlabApi.updateIssueLabels({
+            project: input.project,
+            issueIid: input.issueIid,
+            labels: nextLabels
+        });
+    }
+}
+exports.UpdateIssueLabelsUseCase = UpdateIssueLabelsUseCase;
+function mergeLabels(existing, adding) {
+    return Array.from(new Set([...existing, ...adding]));
+}
+function removeOtherStateLabels(labels, targetLabels, stateLabels) {
+    const targetSet = new Set(targetLabels);
+    const stateSet = new Set(stateLabels);
+    return labels.filter((label) => {
+        if (!stateSet.has(label)) {
+            return true;
+        }
+        return targetSet.has(label);
+    });
+}

package/build/src/domain/ports/gitlab-api.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/src/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const create_mcp_server_1 = require("./interface/mcp/create-mcp-server");
+async function main() {
+    const server = (0, create_mcp_server_1.createMcpServer)();
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('gitlab-mcp-server is running via stdio transport');
+}
+main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});

package/build/src/infrastructure/auth/gitlab-oauth-manager.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitLabOAuthManager = void 0;
+const node_http_1 = require("node:http");
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_child_process_2 = require("node:child_process");
+const errors_1 = require("../../shared/errors");
+const oauth_token_store_1 = require("./oauth-token-store");
+class GitLabOAuthManager {
+    options;
+    tokenStore;
+    oauthBaseUrl;
+    constructor(options) {
+        this.options = options;
+        this.tokenStore = new oauth_token_store_1.OAuthTokenStore(options.tokenStorePath);
+        this.oauthBaseUrl = new URL(options.apiUrl).origin;
+    }
+    async getAccessToken() {
+        const stored = this.tokenStore.read();
+        if (stored && !isExpiringSoon(stored.expiresAt)) {
+            return stored.accessToken;
+        }
+        if (stored?.refreshToken) {
+            const refreshed = await this.refreshToken(stored.refreshToken);
+            this.tokenStore.write(refreshed);
+            return refreshed.accessToken;
+        }
+        if (this.options.bootstrapAccessToken) {
+            return this.options.bootstrapAccessToken;
+        }
+        if (!this.options.autoLogin) {
+            throw new errors_1.ConfigurationError('OAuth token is missing. Enable GITLAB_OAUTH_AUTO_LOGIN or provide GITLAB_OAUTH_ACCESS_TOKEN.');
+        }
+        const interactiveToken = await this.loginInteractively();
+        this.tokenStore.write(interactiveToken);
+        return interactiveToken.accessToken;
+    }
+    async refreshToken(refreshToken) {
+        this.assertOAuthClientCredentials();
+        this.assertRedirectUri();
+        const response = await fetch(`${this.oauthBaseUrl}/oauth/token`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            },
+            body: toFormUrlEncoded({
+                client_id: this.options.clientId,
+                client_secret: this.options.clientSecret,
+                grant_type: 'refresh_token',
+                refresh_token: refreshToken,
+                redirect_uri: this.options.redirectUri
+            })
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Failed to refresh OAuth token: ${response.status} ${body}`);
+        }
+        const payload = (await response.json());
+        return mapTokenResponse(payload);
+    }
+    async loginInteractively() {
+        this.assertOAuthClientCredentials();
+        this.assertRedirectUri();
+        const redirect = new URL(this.options.redirectUri);
+        const state = (0, node_crypto_1.randomBytes)(16).toString('hex');
+        const code = await new Promise((resolve, reject) => {
+            const server = (0, node_http_1.createServer)((req, res) => {
+                if (!req.url) {
+                    return;
+                }
+                const url = new URL(req.url, `${redirect.protocol}//${redirect.host}`);
+                if (url.pathname !== redirect.pathname) {
+                    res.statusCode = 404;
+                    res.end('Not found');
+                    return;
+                }
+                const responseState = url.searchParams.get('state');
+                const error = url.searchParams.get('error');
+                const authCode = url.searchParams.get('code');
+                if (error) {
+                    res.statusCode = 400;
+                    res.end('Authorization failed. You can close this tab.');
+                    server.close();
+                    reject(new Error(`OAuth authorization failed: ${error}`));
+                    return;
+                }
+                if (!authCode || responseState !== state) {
+                    res.statusCode = 400;
+                    res.end('Invalid callback. You can close this tab.');
+                    server.close();
+                    reject(new Error('Invalid OAuth callback: code/state mismatch.'));
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                res.end('<html><body><h3>Authorization completed. You can close this tab.</h3></body></html>');
+                server.close();
+                resolve(authCode);
+            });
+            server.listen(resolvePort(redirect), redirect.hostname, () => {
+                const authorizeUrl = new URL(`${this.oauthBaseUrl}/oauth/authorize`);
+                authorizeUrl.searchParams.set('client_id', this.options.clientId);
+                authorizeUrl.searchParams.set('redirect_uri', this.options.redirectUri);
+                authorizeUrl.searchParams.set('response_type', 'code');
+                authorizeUrl.searchParams.set('scope', this.options.scopes.join(' '));
+                authorizeUrl.searchParams.set('state', state);
+                const authorizeUrlText = authorizeUrl.toString();
+                const opened = this.options.openBrowser && openInBrowser(authorizeUrlText);
+                if (!opened) {
+                    console.error('Open this URL to authorize GitLab access:');
+                    console.error(authorizeUrlText);
+                }
+            });
+        });
+        const tokenResponse = await fetch(`${this.oauthBaseUrl}/oauth/token`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded'
+            },
+            body: toFormUrlEncoded({
+                client_id: this.options.clientId,
+                client_secret: this.options.clientSecret,
+                code,
+                grant_type: 'authorization_code',
+                redirect_uri: this.options.redirectUri
+            })
+        });
+        if (!tokenResponse.ok) {
+            const body = await tokenResponse.text();
+            throw new Error(`Failed to exchange OAuth code: ${tokenResponse.status} ${body}`);
+        }
+        const payload = (await tokenResponse.json());
+        return mapTokenResponse(payload);
+    }
+    assertOAuthClientCredentials() {
+        if (!this.options.clientId || !this.options.clientSecret) {
+            throw new errors_1.ConfigurationError('OAuth client is not configured. Set GITLAB_OAUTH_CLIENT_ID and GITLAB_OAUTH_CLIENT_SECRET.');
+        }
+    }
+    assertRedirectUri() {
+        if (!this.options.redirectUri) {
+            throw new errors_1.ConfigurationError('GITLAB_OAUTH_REDIRECT_URI is required for OAuth flow.');
+        }
+    }
+}
+exports.GitLabOAuthManager = GitLabOAuthManager;
+function mapTokenResponse(payload) {
+    const expiresAt = resolveExpiresAt(payload);
+    return {
+        accessToken: payload.access_token,
+        refreshToken: payload.refresh_token,
+        expiresAt,
+        scope: payload.scope,
+        tokenType: payload.token_type
+    };
+}
+function resolveExpiresAt(payload) {
+    const createdAtMs = payload.created_at ? payload.created_at * 1000 : Date.now();
+    const expiresInSec = payload.expires_in ?? 3600;
+    return createdAtMs + expiresInSec * 1000;
+}
+function isExpiringSoon(expiresAt) {
+    const marginMs = 60 * 1000;
+    return Date.now() + marginMs >= expiresAt;
+}
+function toFormUrlEncoded(data) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(data)) {
+        if (value !== undefined) {
+            params.set(key, value);
+        }
+    }
+    return params.toString();
+}
+function openInBrowser(url) {
+    const platform = process.platform;
+    if (!hasOpenCommand(platform)) {
+        return false;
+    }
+    const command = platform === 'darwin'
+        ? `open "${url}"`
+        : platform === 'win32'
+            ? `start "" "${url}"`
+            : `xdg-open "${url}"`;
+    (0, node_child_process_1.exec)(command, () => { });
+    return true;
+}
+function resolvePort(url) {
+    if (url.port) {
+        return Number(url.port);
+    }
+    return url.protocol === 'https:' ? 443 : 80;
+}
+function hasOpenCommand(platform) {
+    try {
+        if (platform === 'darwin') {
+            (0, node_child_process_2.execSync)('command -v open', { stdio: ['ignore', 'ignore', 'ignore'] });
+            return true;
+        }
+        if (platform === 'win32') {
+            return true;
+        }
+        (0, node_child_process_2.execSync)('command -v xdg-open', { stdio: ['ignore', 'ignore', 'ignore'] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/build/src/infrastructure/auth/oauth-token-store.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthTokenStore = void 0;
+const node_fs_1 = require("node:fs");
+class OAuthTokenStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    read() {
+        if (!(0, node_fs_1.existsSync)(this.filePath)) {
+            return undefined;
+        }
+        const raw = (0, node_fs_1.readFileSync)(this.filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.accessToken || !parsed.expiresAt) {
+            return undefined;
+        }
+        return parsed;
+    }
+    write(token) {
+        (0, node_fs_1.writeFileSync)(this.filePath, JSON.stringify(token, null, 2), 'utf8');
+        (0, node_fs_1.chmodSync)(this.filePath, 0o600);
+    }
+}
+exports.OAuthTokenStore = OAuthTokenStore;

package/build/src/infrastructure/auth/token-provider.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StaticTokenProvider = void 0;
+class StaticTokenProvider {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+    async getAccessToken() {
+        if (!this.token) {
+            throw new Error('Static token is not configured.');
+        }
+        return this.token;
+    }
+}
+exports.StaticTokenProvider = StaticTokenProvider;