gitlab-mcp-agent-server 0.2.2 → 0.2.4

package/README.md

@@ -5,7 +5,10 @@ MCP server for GitLab integration (TypeScript + Node.js).
 Полный пользовательский сценарий подключения к ИИ-агенту:
 - `docs/USER_GUIDE.md`
 
-Основной сценарий: добавить сервер в `~/.codex/config.toml` (готовый блок есть в `docs/USER_GUIDE.md`).
+Основной сценарий: модель `multi-instance`.
+- Один MCP-блок в `~/.codex/config.toml` на один GitLab instance.
+- Для `gitlab.com` и каждого self-hosted GitLab добавляется отдельный блок.
+- Готовые блоки есть в `docs/USER_GUIDE.md`.
 
 Для конечного пользователя обычно достаточно:
 1. Зарегистрировать GitLab OAuth application.
@@ -13,9 +16,10 @@ MCP server for GitLab integration (TypeScript + Node.js).
 
 Остальное работает по дефолту:
 - OAuth auto-login при отсутствии токена.
-- token store в `~/.config/gitlab-mcp/token.json`.
+- instance-aware token store в `~/.config/gitlab-mcp/<gitlab-host>/token.json`.
+- OAuth-flow lock на instance (`<tokenStorePath>.oauth.lock`) для исключения гонки callback-порта.
 - auto-refresh access token.
-- автоопределение проекта из git remote текущего `cwd`.
+- поддержка явного `project` в tool input и fallback-резолва проекта.
 
 ## Local setup (development)
 

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

@@ -1,10 +1,10 @@
 "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 node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_http_1 = require("node:http");
 const errors_1 = require("../../shared/errors");
 const oauth_token_store_1 = require("./oauth-token-store");
 class GitLabOAuthManager {
@@ -22,9 +22,20 @@ class GitLabOAuthManager {
             return stored.accessToken;
         }
         if (stored?.refreshToken) {
-            const refreshed = await this.refreshToken(stored.refreshToken);
-            this.tokenStore.write(refreshed);
-            return refreshed.accessToken;
+            try {
+                const refreshed = await this.refreshToken(stored.refreshToken);
+                this.tokenStore.write(refreshed);
+                return refreshed.accessToken;
+            }
+            catch (error) {
+                if (!shouldReloginOnRefreshFailure(error)) {
+                    throw error;
+                }
+                this.tokenStore.delete();
+                if (!this.options.autoLogin) {
+                    throw new errors_1.ConfigurationError('Stored OAuth refresh token is invalid or expired. Enable GITLAB_OAUTH_AUTO_LOGIN or re-authorize manually.');
+                }
+            }
         }
         if (this.options.bootstrapAccessToken) {
             return this.options.bootstrapAccessToken;
@@ -32,10 +43,51 @@ class GitLabOAuthManager {
         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();
+        const interactiveToken = await this.loginInteractivelyWithLock();
         this.tokenStore.write(interactiveToken);
         return interactiveToken.accessToken;
     }
+    async loginInteractivelyWithLock() {
+        const lockFilePath = `${this.options.tokenStorePath}.oauth.lock`;
+        const lock = acquireOauthLock(lockFilePath);
+        if (lock.acquired) {
+            try {
+                return await this.loginInteractively();
+            }
+            finally {
+                lock.release();
+            }
+        }
+        return this.waitForTokenFromOtherProcess(lockFilePath);
+    }
+    async waitForTokenFromOtherProcess(lockFilePath) {
+        const maxWaitMs = 2 * 60 * 1000;
+        const pollMs = 1000;
+        let elapsed = 0;
+        console.error('OAuth flow is already running in another process for this instance. Waiting for token...');
+        while (elapsed < maxWaitMs) {
+            const stored = this.tokenStore.read();
+            if (stored && !isExpiringSoon(stored.expiresAt)) {
+                return stored;
+            }
+            if (!(0, node_fs_1.existsSync)(lockFilePath) && stored?.refreshToken) {
+                try {
+                    const refreshed = await this.refreshToken(stored.refreshToken);
+                    this.tokenStore.write(refreshed);
+                    return refreshed;
+                }
+                catch (error) {
+                    if (shouldReloginOnRefreshFailure(error) && this.options.autoLogin) {
+                        return this.loginInteractivelyWithLock();
+                    }
+                    throw error;
+                }
+            }
+            await sleep(pollMs);
+            elapsed += pollMs;
+        }
+        throw new Error('Timed out waiting for OAuth token from another process. Retry request or complete authorization in the first window.');
+    }
     async refreshToken(refreshToken) {
         this.assertOAuthClientCredentials();
         this.assertRedirectUri();
@@ -54,7 +106,7 @@ class GitLabOAuthManager {
         });
         if (!response.ok) {
             const body = await response.text();
-            throw new Error(`Failed to refresh OAuth token: ${response.status} ${body}`);
+            throw new OAuthRefreshError(response.status, body);
         }
         const payload = (await response.json());
         return mapTokenResponse(payload);
@@ -93,21 +145,42 @@ class GitLabOAuthManager {
                 const authCode = url.searchParams.get('code');
                 if (error) {
                     res.statusCode = 400;
-                    res.end('Authorization failed. You can close this tab.');
+                    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                    res.end(renderOAuthResultPage({
+                        status: 'error',
+                        title: 'Authorization Failed',
+                        message: `GitLab returned error: ${escapeHtml(error)}.`,
+                        hint: 'Return to your AI agent and retry the request.',
+                        actionHref: localEntryUrl,
+                        actionLabel: 'Start OAuth Again'
+                    }));
                     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.');
+                    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                    res.end(renderOAuthResultPage({
+                        status: 'error',
+                        title: 'Invalid OAuth Callback',
+                        message: 'Authorization code is missing or state verification failed.',
+                        hint: 'Return to your AI agent and retry the request.',
+                        actionHref: localEntryUrl,
+                        actionLabel: 'Start OAuth Again'
+                    }));
                     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>');
+                res.end(renderOAuthResultPage({
+                    status: 'success',
+                    title: 'Authorization Completed',
+                    message: 'GitLab token is saved. You can return to your AI agent.',
+                    hint: 'This tab can be closed now.'
+                }));
                 server.close();
                 resolve(authCode);
             });
@@ -206,19 +279,114 @@ function resolvePort(url) {
 function hasOpenCommand(platform) {
     try {
         if (platform === 'darwin') {
-            (0, node_child_process_2.execSync)('command -v open', { stdio: ['ignore', 'ignore', 'ignore'] });
+            (0, node_child_process_1.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'] });
+        (0, node_child_process_1.execSync)('command -v xdg-open', { stdio: ['ignore', 'ignore', 'ignore'] });
         return true;
     }
     catch {
         return false;
     }
 }
+class OAuthRefreshError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Failed to refresh OAuth token: ${status} ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'OAuthRefreshError';
+    }
+}
+function shouldReloginOnRefreshFailure(error) {
+    if (!(error instanceof OAuthRefreshError)) {
+        return false;
+    }
+    if (error.status === 400 || error.status === 401) {
+        return true;
+    }
+    return false;
+}
+function acquireOauthLock(lockFilePath) {
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(lockFilePath, 'wx');
+    }
+    catch (error) {
+        const e = error;
+        if (e.code !== 'EEXIST') {
+            throw error;
+        }
+        if (isStaleLock(lockFilePath)) {
+            try {
+                (0, node_fs_1.unlinkSync)(lockFilePath);
+            }
+            catch {
+                // ignore race
+            }
+            return acquireOauthLock(lockFilePath);
+        }
+        return {
+            acquired: false,
+            release: () => { }
+        };
+    }
+    const payload = JSON.stringify({
+        pid: process.pid,
+        startedAt: new Date().toISOString()
+    }, null, 2);
+    (0, node_fs_1.writeFileSync)(fd, payload, 'utf8');
+    (0, node_fs_1.closeSync)(fd);
+    let released = false;
+    return {
+        acquired: true,
+        release: () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            try {
+                (0, node_fs_1.unlinkSync)(lockFilePath);
+            }
+            catch {
+                // ignore
+            }
+        }
+    };
+}
+function isStaleLock(lockFilePath) {
+    try {
+        const raw = (0, node_fs_1.readFileSync)(lockFilePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed.pid || !Number.isInteger(parsed.pid)) {
+            return true;
+        }
+        return !isProcessAlive(parsed.pid);
+    }
+    catch {
+        return true;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const e = error;
+        if (e.code === 'EPERM') {
+            return true;
+        }
+        return false;
+    }
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
 function renderOAuthEntryPage(authorizeUrl) {
     const escapedUrl = authorizeUrl.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
     return `<!doctype html>
@@ -251,3 +419,55 @@ function renderOAuthEntryPage(authorizeUrl) {
   </body>
 </html>`;
 }
+function renderOAuthResultPage(input) {
+    const title = escapeHtml(input.title);
+    const message = escapeHtml(input.message);
+    const hint = input.hint ? escapeHtml(input.hint) : '';
+    const isSuccess = input.status === 'success';
+    const borderColor = isSuccess ? '#14532d' : '#7f1d1d';
+    const badgeColor = isSuccess ? '#22c55e' : '#ef4444';
+    const bgTop = isSuccess ? '#052e16' : '#450a0a';
+    const button = input.actionHref && input.actionLabel
+        ? `<a class="btn" href="${escapeHtmlAttr(input.actionHref)}">${escapeHtml(input.actionLabel)}</a>`
+        : '';
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <style>
+      body { font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif; margin: 0; padding: 24px; background: radial-gradient(circle at top, ${bgTop}, #0b1220 55%); color: #e5e7eb; min-height: 100vh; }
+      .wrap { max-width: 680px; margin: 40px auto; }
+      .card { background: #121a2b; border: 1px solid ${borderColor}; border-radius: 14px; padding: 28px; box-shadow: 0 10px 30px rgba(0, 0, 0, .35); }
+      .badge { display: inline-block; padding: 4px 10px; border-radius: 999px; font-size: 12px; font-weight: 700; letter-spacing: .04em; text-transform: uppercase; background: ${badgeColor}; color: #fff; }
+      h1 { margin: 12px 0 8px; font-size: 24px; }
+      p { margin: 0 0 12px; color: #cbd5e1; line-height: 1.55; }
+      .hint { font-size: 13px; color: #94a3b8; }
+      .btn { display: inline-block; margin-top: 10px; background: #2563eb; color: #fff; text-decoration: none; padding: 10px 14px; border-radius: 8px; font-weight: 600; }
+    </style>
+  </head>
+  <body>
+    <div class="wrap">
+      <div class="card">
+        <span class="badge">${isSuccess ? 'Success' : 'Error'}</span>
+        <h1>${title}</h1>
+        <p>${message}</p>
+        ${hint ? `<p class="hint">${hint}</p>` : ''}
+        ${button}
+      </div>
+    </div>
+  </body>
+</html>`;
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function escapeHtmlAttr(value) {
+    return escapeHtml(value);
+}

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

@@ -12,9 +12,17 @@ class OAuthTokenStore {
         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);
+        let parsed;
+        try {
+            const raw = (0, node_fs_1.readFileSync)(this.filePath, 'utf8');
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.delete();
+            return undefined;
+        }
         if (!parsed.accessToken || !parsed.expiresAt) {
+            this.delete();
             return undefined;
         }
         return parsed;
@@ -24,5 +32,16 @@ class OAuthTokenStore {
         (0, node_fs_1.writeFileSync)(this.filePath, JSON.stringify(token, null, 2), 'utf8');
         (0, node_fs_1.chmodSync)(this.filePath, 0o600);
     }
+    delete() {
+        if (!(0, node_fs_1.existsSync)(this.filePath)) {
+            return;
+        }
+        try {
+            (0, node_fs_1.unlinkSync)(this.filePath);
+        }
+        catch {
+            // ignore
+        }
+    }
 }
 exports.OAuthTokenStore = OAuthTokenStore;

package/build/src/infrastructure/gitlab/gitlab-api-client.js

@@ -2,10 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GitLabApiClient = void 0;
 const errors_1 = require("../../shared/errors");
+const http_client_1 = require("../http/http-client");
 class GitLabApiClient {
     options;
+    httpClient;
     constructor(options) {
         this.options = options;
+        this.httpClient = new http_client_1.HttpClient({
+            service: 'gitlab',
+            timeoutMs: 12_000,
+            maxRetries: 2,
+            retryBaseDelayMs: 200
+        });
     }
     async listProjects() {
         const data = await this.request('/projects?simple=true&membership=true');
@@ -93,19 +101,24 @@ class GitLabApiClient {
         if (!token) {
             throw new errors_1.ConfigurationError('GitLab access token is not configured. Set GITLAB_OAUTH_ACCESS_TOKEN (oauth) or GITLAB_PAT (pat).');
         }
-        const response = await fetch(`${this.options.apiUrl}${path}`, {
-            ...init,
-            headers: {
-                Authorization: `Bearer ${token}`,
-                'Content-Type': 'application/json',
-                ...(init?.headers ?? {})
-            }
-        });
-        if (!response.ok) {
-            const body = await safeReadBody(response);
-            throw new Error(`GitLab API ${response.status}: ${body}`);
+        const mergedHeaders = {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/json'
+        };
+        const hasBody = Boolean(init?.body);
+        if (hasBody) {
+            mergedHeaders['Content-Type'] = 'application/json';
+        }
+        const fromInit = init?.headers;
+        if (fromInit && typeof fromInit === 'object' && !Array.isArray(fromInit)) {
+            Object.assign(mergedHeaders, fromInit);
         }
-        return (await response.json());
+        return this.httpClient.requestJson({
+            url: `${this.options.apiUrl}${path}`,
+            method: init?.method ?? 'GET',
+            headers: mergedHeaders,
+            body: typeof init?.body === 'string' ? init.body : undefined
+        });
     }
 }
 exports.GitLabApiClient = GitLabApiClient;
@@ -140,11 +153,3 @@ function mapLabel(label) {
 function encodeProjectRef(project) {
     return encodeURIComponent(String(project));
 }
-async function safeReadBody(response) {
-    try {
-        return await response.text();
-    }
-    catch {
-        return 'Unable to read response body';
-    }
-}

package/build/src/infrastructure/http/http-client.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const errors_1 = require("../../shared/errors");
+class HttpClient {
+    service;
+    timeoutMs;
+    maxRetries;
+    retryBaseDelayMs;
+    logger;
+    constructor(options) {
+        this.service = options.service;
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.retryBaseDelayMs = options.retryBaseDelayMs ?? 200;
+        this.logger = options.logger;
+    }
+    async requestJson(options) {
+        const method = (options.method ?? 'GET').toUpperCase();
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const response = await fetch(options.url, {
+                    method,
+                    headers: options.headers,
+                    body: options.body,
+                    signal: controller.signal
+                });
+                clearTimeout(timeout);
+                if (response.ok) {
+                    return (await response.json());
+                }
+                const body = await safeReadBody(response);
+                const requestId = response.headers.get('x-request-id') ?? response.headers.get('x-gitlab-request-id') ?? undefined;
+                const error = mapHttpError(this.service, response.status, body, requestId);
+                this.log({
+                    level: 'error',
+                    event: 'http.request.failed',
+                    service: this.service,
+                    method,
+                    url: options.url,
+                    attempt,
+                    status: response.status,
+                    requestId,
+                    retriable: Boolean(error.options?.retriable)
+                });
+                if (attempt < this.maxRetries && isRetryableHttpStatus(response.status) && isRetryableMethod(method)) {
+                    const delayMs = backoff(attempt, this.retryBaseDelayMs);
+                    this.log({
+                        level: 'warn',
+                        event: 'http.request.retry',
+                        service: this.service,
+                        method,
+                        url: options.url,
+                        attempt,
+                        status: response.status,
+                        requestId,
+                        delayMs
+                    });
+                    await sleep(delayMs);
+                    continue;
+                }
+                throw error;
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                const mapped = mapTransportError(this.service, error);
+                this.log({
+                    level: 'error',
+                    event: 'http.request.transport_error',
+                    service: this.service,
+                    method,
+                    url: options.url,
+                    attempt,
+                    kind: mapped.kind,
+                    retriable: Boolean(mapped.options?.retriable)
+                });
+                if (attempt < this.maxRetries && mapped.options?.retriable && isRetryableMethod(method)) {
+                    const delayMs = backoff(attempt, this.retryBaseDelayMs);
+                    this.log({
+                        level: 'warn',
+                        event: 'http.request.retry',
+                        service: this.service,
+                        method,
+                        url: options.url,
+                        attempt,
+                        kind: mapped.kind,
+                        delayMs
+                    });
+                    await sleep(delayMs);
+                    continue;
+                }
+                throw mapped;
+            }
+        }
+        throw new errors_1.ExternalServiceError(this.service, 'unknown', 'Request failed after retries.', {
+            retriable: false
+        });
+    }
+    log(event) {
+        if (this.logger) {
+            this.logger(event);
+            return;
+        }
+        const line = JSON.stringify(event);
+        if (event.level === 'error') {
+            console.error(line);
+            return;
+        }
+        if (event.level === 'warn') {
+            console.warn(line);
+        }
+    }
+}
+exports.HttpClient = HttpClient;
+function mapHttpError(service, status, body, requestId) {
+    if (status === 401 || status === 403) {
+        return new errors_1.ExternalServiceError(service, 'auth', `Unauthorized (${status})`, {
+            status,
+            requestId,
+            body,
+            retriable: false
+        });
+    }
+    if (status === 404) {
+        return new errors_1.ExternalServiceError(service, 'not_found', 'Resource not found (404).', {
+            status,
+            requestId,
+            body,
+            retriable: false
+        });
+    }
+    if (status === 429) {
+        return new errors_1.ExternalServiceError(service, 'rate_limit', 'Rate limit reached (429).', {
+            status,
+            requestId,
+            body,
+            retriable: true
+        });
+    }
+    if (status >= 500) {
+        return new errors_1.ExternalServiceError(service, 'server', `Server error (${status}).`, {
+            status,
+            requestId,
+            body,
+            retriable: true
+        });
+    }
+    if (status >= 400) {
+        return new errors_1.ExternalServiceError(service, 'validation', `Request failed (${status}).`, {
+            status,
+            requestId,
+            body,
+            retriable: false
+        });
+    }
+    return new errors_1.ExternalServiceError(service, 'unknown', `Unexpected HTTP status (${status}).`, {
+        status,
+        requestId,
+        body,
+        retriable: false
+    });
+}
+function mapTransportError(service, error) {
+    if (error instanceof errors_1.ExternalServiceError) {
+        return error;
+    }
+    if (isAbortError(error)) {
+        return new errors_1.ExternalServiceError(service, 'timeout', 'Request timed out.', {
+            retriable: true,
+            cause: error
+        });
+    }
+    return new errors_1.ExternalServiceError(service, 'network', 'Network error during request.', {
+        retriable: true,
+        cause: error
+    });
+}
+function isAbortError(error) {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+    const maybe = error;
+    const name = (maybe.name ?? '').toLowerCase();
+    const message = (maybe.message ?? '').toLowerCase();
+    return name.includes('abort') || name.includes('timeout') || message.includes('aborted');
+}
+function isRetryableHttpStatus(status) {
+    return status === 429 || status === 502 || status === 503 || status === 504;
+}
+function isRetryableMethod(method) {
+    return method === 'GET' || method === 'HEAD' || method === 'OPTIONS';
+}
+function backoff(attempt, baseMs) {
+    const jitter = Math.floor(Math.random() * 40);
+    return baseMs * 2 ** attempt + jitter;
+}
+async function safeReadBody(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return '';
+    }
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/build/src/interface/mcp/create-mcp-server.js

@@ -12,7 +12,6 @@ const health_check_1 = require("../../application/use-cases/health-check");
 const list_labels_1 = require("../../application/use-cases/list-labels");
 const list_issues_1 = require("../../application/use-cases/list-issues");
 const update_issue_labels_1 = require("../../application/use-cases/update-issue-labels");
-const group_oauth_token_provider_1 = require("../../infrastructure/auth/group-oauth-token-provider");
 const gitlab_oauth_manager_1 = require("../../infrastructure/auth/gitlab-oauth-manager");
 const token_provider_1 = require("../../infrastructure/auth/token-provider");
 const gitlab_api_client_1 = require("../../infrastructure/gitlab/gitlab-api-client");
@@ -21,20 +20,16 @@ const register_tools_1 = require("./register-tools");
 function createMcpServer() {
     const config = (0, config_1.loadConfig)();
     const tokenProvider = config.gitlab.authMode === 'oauth'
-        ? new group_oauth_token_provider_1.GroupOAuthTokenProvider({
+        ? new gitlab_oauth_manager_1.GitLabOAuthManager({
             apiUrl: config.gitlab.apiUrl,
-            defaultProvider: new gitlab_oauth_manager_1.GitLabOAuthManager({
-                apiUrl: config.gitlab.apiUrl,
-                clientId: config.gitlab.oauth.clientId,
-                clientSecret: config.gitlab.oauth.clientSecret,
-                redirectUri: config.gitlab.oauth.redirectUri,
-                scopes: config.gitlab.oauth.scopes,
-                bootstrapAccessToken: config.gitlab.accessToken,
-                tokenStorePath: config.gitlab.oauth.tokenStorePath,
-                autoLogin: config.gitlab.oauth.autoLogin,
-                openBrowser: config.gitlab.oauth.openBrowser
-            }),
-            groupConfigs: config.gitlab.groupOAuthConfigs
+            clientId: config.gitlab.oauth.clientId,
+            clientSecret: config.gitlab.oauth.clientSecret,
+            redirectUri: config.gitlab.oauth.redirectUri,
+            scopes: config.gitlab.oauth.scopes,
+            bootstrapAccessToken: config.gitlab.accessToken,
+            tokenStorePath: config.gitlab.oauth.tokenStorePath,
+            autoLogin: config.gitlab.oauth.autoLogin,
+            openBrowser: config.gitlab.oauth.openBrowser
         })
         : new token_provider_1.StaticTokenProvider(config.gitlab.accessToken);
     const gitlabApiClient = new gitlab_api_client_1.GitLabApiClient({

package/build/src/shared/config.js

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfig = loadConfig;
+exports.resolveDefaultTokenStorePath = resolveDefaultTokenStorePath;
 const node_child_process_1 = require("node:child_process");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const zod_1 = require("zod");
-const DEFAULT_TOKEN_STORE_PATH = (0, node_path_1.join)((0, node_os_1.homedir)(), '.config', 'gitlab-mcp', 'token.json');
 const EnvSchema = zod_1.z.object({
     GITLAB_API_URL: zod_1.z.string().url().default('https://gitlab.com/api/v4'),
     GITLAB_AUTH_MODE: zod_1.z.enum(['oauth', 'pat']).default('oauth'),
@@ -14,7 +14,7 @@ const EnvSchema = zod_1.z.object({
     GITLAB_OAUTH_CLIENT_SECRET: zod_1.z.string().optional(),
     GITLAB_OAUTH_REDIRECT_URI: zod_1.z.string().optional(),
     GITLAB_OAUTH_SCOPES: zod_1.z.string().default('api'),
-    GITLAB_OAUTH_TOKEN_STORE_PATH: zod_1.z.string().default(DEFAULT_TOKEN_STORE_PATH),
+    GITLAB_OAUTH_TOKEN_STORE_PATH: zod_1.z.string().optional(),
     GITLAB_OAUTH_AUTO_LOGIN: zod_1.z
         .enum(['true', 'false'])
         .optional()
@@ -23,7 +23,6 @@ const EnvSchema = zod_1.z.object({
         .enum(['true', 'false'])
         .optional()
         .transform((value) => value !== 'false'),
-    GITLAB_GROUP_OAUTH_CONFIG_JSON: zod_1.z.string().optional(),
     GITLAB_PAT: zod_1.z.string().optional(),
     GITLAB_DEFAULT_PROJECT: zod_1.z.string().optional(),
     GITLAB_AUTO_RESOLVE_PROJECT_FROM_GIT: zod_1.z
@@ -57,6 +56,7 @@ function loadConfig() {
     const autoDetectedProject = env.GITLAB_AUTO_RESOLVE_PROJECT_FROM_GIT
         ? detectProjectFromGitRemote()
         : undefined;
+    const defaultTokenStorePath = env.GITLAB_OAUTH_TOKEN_STORE_PATH ?? resolveDefaultTokenStorePath(env.GITLAB_API_URL);
     return {
         gitlab: {
             apiUrl: env.GITLAB_API_URL,
@@ -67,16 +67,10 @@ function loadConfig() {
                 clientSecret: env.GITLAB_OAUTH_CLIENT_SECRET,
                 redirectUri: env.GITLAB_OAUTH_REDIRECT_URI,
                 scopes: splitCsv(env.GITLAB_OAUTH_SCOPES),
-                tokenStorePath: env.GITLAB_OAUTH_TOKEN_STORE_PATH,
+                tokenStorePath: defaultTokenStorePath,
                 autoLogin: env.GITLAB_OAUTH_AUTO_LOGIN,
                 openBrowser: env.GITLAB_OAUTH_OPEN_BROWSER
             },
-            groupOAuthConfigs: parseGroupOAuthConfigJson(env.GITLAB_GROUP_OAUTH_CONFIG_JSON, {
-                redirectUri: env.GITLAB_OAUTH_REDIRECT_URI,
-                scopes: splitCsv(env.GITLAB_OAUTH_SCOPES),
-                autoLogin: env.GITLAB_OAUTH_AUTO_LOGIN,
-                openBrowser: env.GITLAB_OAUTH_OPEN_BROWSER
-            }),
             defaultProject: env.GITLAB_DEFAULT_PROJECT,
             autoResolveProjectFromGit: env.GITLAB_AUTO_RESOLVE_PROJECT_FROM_GIT,
             autoDetectedProject
@@ -91,62 +85,9 @@ function loadConfig() {
         }
     };
 }
-function parseGroupOAuthConfigJson(raw, defaults) {
-    if (!raw) {
-        return {};
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new Error('GITLAB_GROUP_OAUTH_CONFIG_JSON must be valid JSON.');
-    }
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('GITLAB_GROUP_OAUTH_CONFIG_JSON must be an object map.');
-    }
-    const result = {};
-    for (const [groupKey, value] of Object.entries(parsed)) {
-        if (!value || typeof value !== 'object' || Array.isArray(value)) {
-            continue;
-        }
-        const rec = value;
-        result[groupKey] = {
-            clientId: toStringOrUndefined(rec.clientId ?? rec.client_id),
-            clientSecret: toStringOrUndefined(rec.clientSecret ?? rec.client_secret),
-            redirectUri: toStringOrUndefined(rec.redirectUri ?? rec.redirect_uri ?? defaults.redirectUri),
-            scopes: parseScopes(rec.scopes, defaults.scopes),
-            tokenStorePath: toStringOrUndefined(rec.tokenStorePath ?? rec.token_store_path) ??
-                (0, node_path_1.join)((0, node_os_1.homedir)(), '.config', 'gitlab-mcp', `${sanitizeForFilename(groupKey)}-token.json`),
-            autoLogin: toBooleanOrDefault(rec.autoLogin ?? rec.auto_login, defaults.autoLogin),
-            openBrowser: toBooleanOrDefault(rec.openBrowser ?? rec.open_browser, defaults.openBrowser),
-            bootstrapAccessToken: toStringOrUndefined(rec.bootstrapAccessToken ?? rec.bootstrap_access_token)
-        };
-    }
-    return result;
-}
-function parseScopes(value, fallback) {
-    if (typeof value === 'string') {
-        return splitCsv(value);
-    }
-    if (Array.isArray(value)) {
-        return value
-            .map((item) => (typeof item === 'string' ? item.trim() : ''))
-            .filter((item) => item.length > 0);
-    }
-    return fallback;
-}
-function toStringOrUndefined(value) {
-    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
-}
-function toBooleanOrDefault(value, fallback) {
-    if (typeof value === 'boolean') {
-        return value;
-    }
-    if (typeof value === 'string') {
-        return value !== 'false';
-    }
-    return fallback;
+function resolveDefaultTokenStorePath(apiUrl, filePrefix = 'token') {
+    const hostKey = sanitizeForFilename(new URL(apiUrl).host.toLowerCase());
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), '.config', 'gitlab-mcp', hostKey, `${filePrefix}.json`);
 }
 function sanitizeForFilename(value) {
     return value.replace(/[^a-zA-Z0-9._-]+/g, '_');

package/build/src/shared/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConfigurationError = exports.PolicyError = void 0;
+exports.ExternalServiceError = exports.ConfigurationError = exports.PolicyError = void 0;
 class PolicyError extends Error {
     constructor(message) {
         super(message);
@@ -15,3 +15,21 @@ class ConfigurationError extends Error {
     }
 }
 exports.ConfigurationError = ConfigurationError;
+class ExternalServiceError extends Error {
+    service;
+    kind;
+    message;
+    options;
+    constructor(service, kind, message, options) {
+        super(message);
+        this.service = service;
+        this.kind = kind;
+        this.message = message;
+        this.options = options;
+        this.name = 'ExternalServiceError';
+        if (options?.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
+exports.ExternalServiceError = ExternalServiceError;

package/docs/USER_GUIDE.md

@@ -1,6 +1,10 @@
 # User Guide
 
-Этот гайд для конечного пользователя: как подключить `gitlab-mcp-agent-server` в **Codex** и работать через OAuth с авто-рефрешем токена.
+Этот гайд для конечного пользователя: как подключить `gitlab-mcp-agent-server` в **Codex**.
+
+Основная модель: **multi-instance**.
+- Один блок MCP в `config.toml` = один GitLab instance.
+- Для `gitlab.com` и каждого self-hosted GitLab создаётся отдельный MCP-блок.
 
 ## 1. Подготовка GitLab OAuth Application
 
@@ -25,15 +29,16 @@
 
 ## 3. Конфиг Codex (`~/.codex/config.toml`)
 
-Минимальный рабочий блок:
+### 3.1 Один instance (минимально)
 
 ```toml
-[mcp_servers.gitlab]
+[mcp_servers.gitlab_com]
 command = "bash"
 args = ["-lc", """
 export NVM_DIR="$HOME/.nvm";
 [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh";
 
+export GITLAB_API_URL="https://gitlab.com/api/v4";
 export GITLAB_OAUTH_CLIENT_ID="<APPLICATION_ID>";
 export GITLAB_OAUTH_CLIENT_SECRET="<SECRET>";
 
@@ -41,10 +46,10 @@ npx -y gitlab-mcp-agent-server
 """]
 ```
 
-Рекомендованный расширенный блок:
+### 3.2 Несколько instances (рекомендуемая модель)
 
 ```toml
-[mcp_servers.gitlab]
+[mcp_servers.gitlab_com]
 command = "bash"
 args = ["-lc", """
 export NVM_DIR="$HOME/.nvm";
@@ -52,18 +57,28 @@ export NVM_DIR="$HOME/.nvm";
 
 export GITLAB_API_URL="https://gitlab.com/api/v4";
 export GITLAB_AUTH_MODE="oauth";
-export GITLAB_OAUTH_CLIENT_ID="<APPLICATION_ID>";
-export GITLAB_OAUTH_CLIENT_SECRET="<SECRET>";
+export GITLAB_OAUTH_CLIENT_ID="<GITLAB_COM_APP_ID>";
+export GITLAB_OAUTH_CLIENT_SECRET="<GITLAB_COM_APP_SECRET>";
 export GITLAB_OAUTH_REDIRECT_URI="http://127.0.0.1:8787/oauth/callback";
-export GITLAB_OAUTH_SCOPES="api";
-export GITLAB_OAUTH_TOKEN_STORE_PATH="$HOME/.config/gitlab-mcp/token.json";
 export GITLAB_OAUTH_AUTO_LOGIN="true";
-export GITLAB_OAUTH_OPEN_BROWSER="false";
-export GITLAB_GROUP_OAUTH_CONFIG_JSON='{"konoha7":{"clientId":"<ID_1>","clientSecret":"<SECRET_1>","redirectUri":"http://127.0.0.1:8787/oauth/callback"},"othergroup":{"clientId":"<ID_2>","clientSecret":"<SECRET_2>","redirectUri":"http://127.0.0.1:8788/oauth/callback"}}';
+export GITLAB_OAUTH_OPEN_BROWSER="true";
+
+npx -y gitlab-mcp-agent-server
+"""]
 
-# optional fallback if auto-detect from git remote is unavailable
-export GITLAB_DEFAULT_PROJECT="group/repo";
-export GITLAB_AUTO_RESOLVE_PROJECT_FROM_GIT="true";
+[mcp_servers.gitlab_work]
+command = "bash"
+args = ["-lc", """
+export NVM_DIR="$HOME/.nvm";
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh";
+
+export GITLAB_API_URL="https://gitlab.work.local/api/v4";
+export GITLAB_AUTH_MODE="oauth";
+export GITLAB_OAUTH_CLIENT_ID="<WORK_APP_ID>";
+export GITLAB_OAUTH_CLIENT_SECRET="<WORK_APP_SECRET>";
+export GITLAB_OAUTH_REDIRECT_URI="http://127.0.0.1:8788/oauth/callback";
+export GITLAB_OAUTH_AUTO_LOGIN="true";
+export GITLAB_OAUTH_OPEN_BROWSER="true";
 
 npx -y gitlab-mcp-agent-server
 """]
@@ -71,10 +86,13 @@ npx -y gitlab-mcp-agent-server
 
 После изменения `config.toml` перезапусти Codex.
 
-Как выбирается OAuth-конфиг при `GITLAB_GROUP_OAUTH_CONFIG_JSON`:
-1. Сервер берёт `resolved_project` (например `konoha7/subgroup/repo`).
-2. Находит самый длинный совпадающий group key.
-3. Использует соответствующие `clientId/clientSecret/redirectUri/tokenStorePath`.
+По умолчанию token store instance-aware:
+- `~/.config/gitlab-mcp/gitlab.com/token.json`
+- `~/.config/gitlab-mcp/gitlab.work.local/token.json`
+
+Для OAuth используется lock-файл на instance:
+- `<tokenStorePath>.oauth.lock`
+- если OAuth уже идёт в другом процессе, текущий процесс ждёт появления токена.
 
 ## 4. Что происходит при первом запуске
 
@@ -83,11 +101,10 @@ npx -y gitlab-mcp-agent-server
 3. Если `GITLAB_OAUTH_OPEN_BROWSER=true` и окружение GUI доступно, браузер откроется автоматически.
 4. Локальный URL `http://127.0.0.1:8787/` автоматически редиректит на GitLab OAuth.
 5. Если браузер не может быть открыт, сервер печатает URL авторизации в лог.
-6. После подтверждения в GitLab и callback на `http://127.0.0.1:8787/oauth/callback` токены сохраняются в `GITLAB_OAUTH_TOKEN_STORE_PATH`.
-
-Если `GITLAB_DEFAULT_PROJECT` не указан:
-1. сервер пытается автоматически определить проект из `git remote origin` в `cwd`;
-2. если не удалось, tool запросит `project` явно.
+6. После подтверждения в GitLab и callback на `http://127.0.0.1:8787/oauth/callback` токены сохраняются в token store для конкретного instance.
+7. В браузере показывается feedback-страница:
+   - `Success`: токен сохранен, можно вернуться в ИИ-агент;
+   - `Error`: показана причина и кнопка повторного запуска OAuth.
 
 ## 5. Автообновление токена
 
@@ -95,17 +112,32 @@ npx -y gitlab-mcp-agent-server
 1. Проверяет срок действия `access_token` перед API-вызовами.
 2. Выполняет refresh по `refresh_token`, если токен истекает.
 3. Перезаписывает token store файл новым токеном.
+4. Если refresh token отозван/протух, очищает token store и запускает OAuth заново (при `GITLAB_OAUTH_AUTO_LOGIN=true`).
 
 ## 6. Рекомендованные настройки для production
 
 1. Держи token store вне репозитория:
-   - пример: `/home/<user>/.config/gitlab-mcp/token.json`
+   - пример: `/home/<user>/.config/gitlab-mcp/gitlab.com/token.json`
 2. Ограничь права файла:
-   - `chmod 600 /home/<user>/.config/gitlab-mcp/token.json`
-3. Оставь `GITLAB_OAUTH_OPEN_BROWSER=false` для headless окружений.
-4. Для multi-repo режима лучше не задавать `GITLAB_DEFAULT_PROJECT`, чтобы проект брался из `git remote` текущего `cwd`.
+   - `chmod 600 /home/<user>/.config/gitlab-mcp/gitlab.com/token.json`
+3. Для headless окружений ставь `GITLAB_OAUTH_OPEN_BROWSER=false`.
+
+## 7. Сценарий пользовательского запроса
+
+Пример запроса: `Покажи мне все задачи, которые сейчас есть в проекте?`
 
-## 7. Быстрая проверка работоспособности
+1. Пользователь добавляет MCP-блок в `~/.codex/config.toml`.
+2. Codex поднимает сервер командой `npx -y gitlab-mcp-agent-server`.
+3. Codex вызывает tool `gitlab_list_issues`.
+4. Сервер резолвит проект в порядке:
+   - `project` из входа tool,
+   - `git remote origin` текущего `cwd`,
+   - `GITLAB_DEFAULT_PROJECT`.
+5. Если токена для этого instance нет, запускается OAuth flow.
+6. После callback токен сохраняется в token store этого instance.
+7. Сервер возвращает список issues.
+
+## 8. Быстрая проверка работоспособности
 
 1. Вызови `gitlab_list_labels`.
 2. Создай issue: `gitlab_create_issue`.
@@ -113,7 +145,7 @@ npx -y gitlab-mcp-agent-server
 4. Обнови labels: `gitlab_update_issue_labels`.
 5. Закрой issue: `gitlab_close_issue`.
 
-## 8. Troubleshooting
+## 9. Troubleshooting
 
 `The redirect URI included is not valid`:
 1. Проверь, что URI совпадает 1-в-1:
@@ -125,3 +157,20 @@ npx -y gitlab-mcp-agent-server
 1. Проверь scope `api`.
 2. Убедись, что `client_id`/`client_secret` от того же приложения.
 3. Удали token store файл и пройди OAuth заново.
+
+`Stored OAuth refresh token is invalid or expired`:
+1. Включи `GITLAB_OAUTH_AUTO_LOGIN=true`.
+2. Повтори запрос: сервер автоматически запустит OAuth и сохранит новый token.
+
+`OAuth flow is already running in another process for this instance`:
+1. Заверши OAuth в первом окне.
+2. Второе окно подождет и продолжит после появления токена.
+3. Если lock застрял после краша, удали stale lock:
+   - `<tokenStorePath>.oauth.lock`
+
+## 10. Advanced (необязательно)
+
+Если нужен тонкий контроль, можно использовать:
+1. `GITLAB_DEFAULT_PROJECT` для явного fallback проекта.
+2. `GITLAB_AUTO_RESOLVE_PROJECT_FROM_GIT` для автоопределения проекта из `git remote`.
+3. `GITLAB_OAUTH_TOKEN_STORE_PATH` для ручного override пути токена.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab-mcp-agent-server",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "MCP server for GitLab integration via OAuth",
   "main": "build/src/index.js",
   "bin": {

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

@@ -1,51 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GroupOAuthTokenProvider = void 0;
-exports.resolveOAuthGroupKey = resolveOAuthGroupKey;
-const errors_1 = require("../../shared/errors");
-const gitlab_oauth_manager_1 = require("./gitlab-oauth-manager");
-class GroupOAuthTokenProvider {
-    options;
-    groupProviders;
-    constructor(options) {
-        this.options = options;
-        this.groupProviders = Object.fromEntries(Object.entries(options.groupConfigs).map(([groupKey, cfg]) => {
-            return [
-                groupKey,
-                new gitlab_oauth_manager_1.GitLabOAuthManager({
-                    apiUrl: options.apiUrl,
-                    clientId: cfg.clientId,
-                    clientSecret: cfg.clientSecret,
-                    redirectUri: cfg.redirectUri,
-                    scopes: cfg.scopes,
-                    bootstrapAccessToken: cfg.bootstrapAccessToken,
-                    tokenStorePath: cfg.tokenStorePath,
-                    autoLogin: cfg.autoLogin,
-                    openBrowser: cfg.openBrowser
-                })
-            ];
-        }));
-    }
-    async getAccessToken(projectRef) {
-        const groupKey = resolveOAuthGroupKey(projectRef, Object.keys(this.groupProviders));
-        if (groupKey) {
-            const provider = this.groupProviders[groupKey];
-            if (provider) {
-                return provider.getAccessToken(projectRef);
-            }
-        }
-        if (this.options.defaultProvider) {
-            return this.options.defaultProvider.getAccessToken(projectRef);
-        }
-        throw new errors_1.ConfigurationError('No OAuth config matched this project and default OAuth config is not available.');
-    }
-}
-exports.GroupOAuthTokenProvider = GroupOAuthTokenProvider;
-function resolveOAuthGroupKey(projectRef, configuredGroups) {
-    if (typeof projectRef !== 'string' || projectRef.trim() === '') {
-        return undefined;
-    }
-    const normalized = projectRef.trim().replace(/^\/+/, '');
-    const sorted = [...configuredGroups].sort((a, b) => b.length - a.length);
-    return sorted.find((group) => normalized === group || normalized.startsWith(`${group}/`));
-}