gitlab-mcp-agent-server 0.2.2 → 0.2.3

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,9 @@ 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`.
 - auto-refresh access token.
-- автоопределение проекта из git remote текущего `cwd`.
+- поддержка явного `project` в tool input и fallback-резолва проекта.
 
 ## Local setup (development)
 

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/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
+"""]
+
+[mcp_servers.gitlab_work]
+command = "bash"
+args = ["-lc", """
+export NVM_DIR="$HOME/.nvm";
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh";
 
-# optional fallback if auto-detect from git remote is unavailable
-export GITLAB_DEFAULT_PROJECT="group/repo";
-export GITLAB_AUTO_RESOLVE_PROJECT_FROM_GIT="true";
+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,9 @@ 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`
 
 ## 4. Что происходит при первом запуске
 
@@ -83,11 +97,7 @@ 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.
 
 ## 5. Автообновление токена
 
@@ -99,13 +109,27 @@ npx -y gitlab-mcp-agent-server
 ## 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 +137,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 +149,10 @@ npx -y gitlab-mcp-agent-server
 1. Проверь scope `api`.
 2. Убедись, что `client_id`/`client_secret` от того же приложения.
 3. Удали token store файл и пройди OAuth заново.
+
+## 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.3",
   "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}/`));
-}