gitlab-mcp-agent-server 0.2.3 → 0.2.5

package/README.md

@@ -17,6 +17,7 @@ MCP server for GitLab integration (TypeScript + Node.js).
 Остальное работает по дефолту:
 - OAuth auto-login при отсутствии токена.
 - instance-aware token store в `~/.config/gitlab-mcp/<gitlab-host>/token.json`.
+- OAuth-flow lock на instance (`<tokenStorePath>.oauth.lock`) для исключения гонки callback-порта.
 - auto-refresh access token.
 - поддержка явного `project` в tool input и fallback-резолва проекта.
 

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 = 15 * 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. Complete OAuth in the first window or remove stale lock: ${lockFilePath}`);
+    }
     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);
@@ -72,6 +124,7 @@ class GitLabOAuthManager {
         authorizeUrl.searchParams.set('state', state);
         const localEntryUrl = `${redirect.protocol}//${redirect.host}/`;
         const code = await new Promise((resolve, reject) => {
+            let settled = false;
             const server = (0, node_http_1.createServer)((req, res) => {
                 if (!req.url) {
                     return;
@@ -93,25 +146,50 @@ 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();
+                    settled = true;
                     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();
+                    settled = true;
                     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();
+                settled = true;
                 resolve(authCode);
             });
             server.on('error', (error) => {
+                settled = true;
                 reject(new Error(`OAuth callback server failed on ${redirect.hostname}:${resolvePort(redirect)}: ${error.message}`));
             });
             server.listen(resolvePort(redirect), redirect.hostname, () => {
@@ -123,6 +201,14 @@ class GitLabOAuthManager {
                     console.error(authorizeUrl.toString());
                 }
             });
+            const timeoutMs = 20_000;
+            setTimeout(() => {
+                if (settled) {
+                    return;
+                }
+                server.close();
+                reject(new Error(`OAuth was not completed in time. Open ${localEntryUrl} to continue, or use ${authorizeUrl.toString()}`));
+            }, timeoutMs);
         });
         const tokenResponse = await fetch(`${this.oauthBaseUrl}/oauth/token`, {
             method: 'POST',
@@ -206,19 +292,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 +432,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/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

@@ -90,6 +90,10 @@ npx -y gitlab-mcp-agent-server
 - `~/.config/gitlab-mcp/gitlab.com/token.json`
 - `~/.config/gitlab-mcp/gitlab.work.local/token.json`
 
+Для OAuth используется lock-файл на instance:
+- `<tokenStorePath>.oauth.lock`
+- если OAuth уже идёт в другом процессе, текущий процесс ждёт появления токена.
+
 ## 4. Что происходит при первом запуске
 
 1. Агент вызывает любой GitLab tool (например `gitlab_list_labels`).
@@ -98,6 +102,9 @@ npx -y gitlab-mcp-agent-server
 4. Локальный URL `http://127.0.0.1:8787/` автоматически редиректит на GitLab OAuth.
 5. Если браузер не может быть открыт, сервер печатает URL авторизации в лог.
 6. После подтверждения в GitLab и callback на `http://127.0.0.1:8787/oauth/callback` токены сохраняются в token store для конкретного instance.
+7. В браузере показывается feedback-страница:
+   - `Success`: токен сохранен, можно вернуться в ИИ-агент;
+   - `Error`: показана причина и кнопка повторного запуска OAuth.
 
 ## 5. Автообновление токена
 
@@ -105,6 +112,7 @@ 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
 
@@ -150,6 +158,21 @@ npx -y gitlab-mcp-agent-server
 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`
+
+`gitlab_list_issues`/другой tool уходит в timeout после удаления token:
+1. Проверь stale lock и удали его:
+   - `rm -f ~/.config/gitlab-mcp/<gitlab-host>/token.json.oauth.lock`
+2. Повтори запрос и заверши OAuth в браузере в течение окна авторизации.
+
 ## 10. Advanced (необязательно)
 
 Если нужен тонкий контроль, можно использовать:

package/package.json

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