gitlab-mcp-agent-server 0.1.0

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

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitLabApiClient = void 0;
+const errors_1 = require("../../shared/errors");
+class GitLabApiClient {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async listProjects() {
+        const data = await this.request('/projects?simple=true&membership=true');
+        return data.map(mapProject);
+    }
+    async createIssue(input) {
+        const projectPath = encodeProjectRef(input.project);
+        const body = {
+            title: input.title,
+            description: input.description,
+            labels: input.labels?.join(','),
+            assignee_ids: input.assigneeIds
+        };
+        const data = await this.request(`/projects/${projectPath}/issues`, {
+            method: 'POST',
+            body: JSON.stringify(body)
+        });
+        return mapIssue(data);
+    }
+    async getIssue(input) {
+        const projectPath = encodeProjectRef(input.project);
+        const data = await this.request(`/projects/${projectPath}/issues/${input.issueIid}`);
+        return mapIssue(data);
+    }
+    async closeIssue(input) {
+        const projectPath = encodeProjectRef(input.project);
+        const data = await this.request(`/projects/${projectPath}/issues/${input.issueIid}`, {
+            method: 'PUT',
+            body: JSON.stringify({ state_event: 'close' })
+        });
+        return mapIssue(data);
+    }
+    async updateIssueLabels(input) {
+        const projectPath = encodeProjectRef(input.project);
+        const data = await this.request(`/projects/${projectPath}/issues/${input.issueIid}`, {
+            method: 'PUT',
+            body: JSON.stringify({ labels: input.labels.join(',') })
+        });
+        return mapIssue(data);
+    }
+    async listLabels(input) {
+        const projectPath = encodeProjectRef(input.project);
+        const query = input.search
+            ? `/projects/${projectPath}/labels?search=${encodeURIComponent(input.search)}`
+            : `/projects/${projectPath}/labels`;
+        const data = await this.request(query);
+        return data.map(mapLabel);
+    }
+    async listIssues(input) {
+        const projectPath = encodeProjectRef(input.project);
+        const query = new URLSearchParams();
+        if (input.state) {
+            query.set('state', input.state);
+        }
+        if (input.search) {
+            query.set('search', input.search);
+        }
+        if (input.labels && input.labels.length > 0) {
+            query.set('labels', input.labels.join(','));
+        }
+        if (input.perPage) {
+            query.set('per_page', String(input.perPage));
+        }
+        if (input.page) {
+            query.set('page', String(input.page));
+        }
+        const querySuffix = query.size > 0 ? `?${query.toString()}` : '';
+        const data = await this.request(`/projects/${projectPath}/issues${querySuffix}`);
+        return data.map(mapIssue);
+    }
+    async createLabel(input) {
+        const projectPath = encodeProjectRef(input.project);
+        const data = await this.request(`/projects/${projectPath}/labels`, {
+            method: 'POST',
+            body: JSON.stringify({
+                name: input.name,
+                color: input.color ?? '#1f75cb',
+                description: input.description
+            })
+        });
+        return mapLabel(data);
+    }
+    async request(path, init) {
+        const token = await this.options.tokenProvider.getAccessToken();
+        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}`);
+        }
+        return (await response.json());
+    }
+}
+exports.GitLabApiClient = GitLabApiClient;
+function mapProject(project) {
+    return {
+        id: project.id,
+        name: project.name,
+        pathWithNamespace: project.path_with_namespace
+    };
+}
+function mapIssue(issue) {
+    return {
+        id: issue.id,
+        iid: issue.iid,
+        projectId: issue.project_id,
+        title: issue.title,
+        description: issue.description,
+        state: issue.state,
+        labels: issue.labels,
+        webUrl: issue.web_url,
+        updatedAt: issue.updated_at,
+        closedAt: issue.closed_at
+    };
+}
+function mapLabel(label) {
+    return {
+        name: label.name,
+        color: label.color,
+        description: label.description
+    };
+}
+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/interface/mcp/create-mcp-server.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpServer = createMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const issue_workflow_policy_1 = require("../../application/policies/issue-workflow-policy");
+const project_resolver_1 = require("../../application/services/project-resolver");
+const close_issue_1 = require("../../application/use-cases/close-issue");
+const create_issue_1 = require("../../application/use-cases/create-issue");
+const ensure_labels_1 = require("../../application/use-cases/ensure-labels");
+const get_issue_1 = require("../../application/use-cases/get-issue");
+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 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");
+const config_1 = require("../../shared/config");
+const register_tools_1 = require("./register-tools");
+function createMcpServer() {
+    const config = (0, config_1.loadConfig)();
+    const tokenProvider = config.gitlab.authMode === 'oauth'
+        ? 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
+        })
+        : new token_provider_1.StaticTokenProvider(config.gitlab.accessToken);
+    const gitlabApiClient = new gitlab_api_client_1.GitLabApiClient({
+        apiUrl: config.gitlab.apiUrl,
+        tokenProvider
+    });
+    const server = new mcp_js_1.McpServer({
+        name: 'gitlab-mcp-server',
+        version: '0.1.0'
+    });
+    const projectResolver = new project_resolver_1.ProjectResolver(config);
+    const issueWorkflowPolicy = new issue_workflow_policy_1.IssueWorkflowPolicy(config);
+    (0, register_tools_1.registerTools)(server, {
+        config,
+        projectResolver,
+        issueWorkflowPolicy,
+        healthCheckUseCase: new health_check_1.HealthCheckUseCase(),
+        createIssueUseCase: new create_issue_1.CreateIssueUseCase(gitlabApiClient),
+        getIssueUseCase: new get_issue_1.GetIssueUseCase(gitlabApiClient),
+        closeIssueUseCase: new close_issue_1.CloseIssueUseCase(gitlabApiClient),
+        updateIssueLabelsUseCase: new update_issue_labels_1.UpdateIssueLabelsUseCase(gitlabApiClient),
+        listIssuesUseCase: new list_issues_1.ListIssuesUseCase(gitlabApiClient),
+        listLabelsUseCase: new list_labels_1.ListLabelsUseCase(gitlabApiClient),
+        ensureLabelsUseCase: new ensure_labels_1.EnsureLabelsUseCase(gitlabApiClient)
+    });
+    return server;
+}

package/build/src/interface/mcp/register-tools.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTools = registerTools;
+const zod_1 = require("zod");
+const errors_1 = require("../../shared/errors");
+function registerTools(server, deps) {
+    server.registerTool('health_check', {
+        title: 'Health Check',
+        description: 'Returns server status.',
+        inputSchema: {
+            ping: zod_1.z.string().optional()
+        }
+    }, async ({ ping }) => {
+        return runTool(async () => deps.healthCheckUseCase.execute({ ping }));
+    });
+    server.registerTool('gitlab_create_issue', {
+        title: 'GitLab Create Issue',
+        description: 'Create an issue in a GitLab project.',
+        inputSchema: {
+            project: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+            title: zod_1.z.string().min(1),
+            description: zod_1.z.string().optional(),
+            labels: zod_1.z.array(zod_1.z.string()).optional(),
+            assignee_ids: zod_1.z.array(zod_1.z.number()).optional()
+        }
+    }, async ({ project, title, description, labels, assignee_ids }) => {
+        return runTool(async () => {
+            deps.issueWorkflowPolicy.assertActionAllowed('create');
+            deps.issueWorkflowPolicy.assertLabelsAllowed(labels ?? []);
+            const resolvedProject = deps.projectResolver.resolveProject(project);
+            const issue = await deps.createIssueUseCase.execute({
+                project: resolvedProject,
+                title,
+                description,
+                labels,
+                assigneeIds: assignee_ids
+            });
+            return { resolved_project: resolvedProject, issue };
+        });
+    });
+    server.registerTool('gitlab_get_issue', {
+        title: 'GitLab Get Issue',
+        description: 'Get issue details by issue IID.',
+        inputSchema: {
+            project: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+            issue_iid: zod_1.z.number().int().positive()
+        }
+    }, async ({ project, issue_iid }) => {
+        return runTool(async () => {
+            deps.issueWorkflowPolicy.assertEnabled();
+            const resolvedProject = deps.projectResolver.resolveProject(project);
+            const issue = await deps.getIssueUseCase.execute({
+                project: resolvedProject,
+                issueIid: issue_iid
+            });
+            return { resolved_project: resolvedProject, issue };
+        });
+    });
+    server.registerTool('gitlab_close_issue', {
+        title: 'GitLab Close Issue',
+        description: 'Close an issue by issue IID.',
+        inputSchema: {
+            project: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+            issue_iid: zod_1.z.number().int().positive()
+        }
+    }, async ({ project, issue_iid }) => {
+        return runTool(async () => {
+            deps.issueWorkflowPolicy.assertActionAllowed('close');
+            const resolvedProject = deps.projectResolver.resolveProject(project);
+            const issue = await deps.closeIssueUseCase.execute({
+                project: resolvedProject,
+                issueIid: issue_iid
+            });
+            return { resolved_project: resolvedProject, issue };
+        });
+    });
+    server.registerTool('gitlab_update_issue_labels', {
+        title: 'GitLab Update Issue Labels',
+        description: 'Update labels on an issue.',
+        inputSchema: {
+            project: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+            issue_iid: zod_1.z.number().int().positive(),
+            mode: zod_1.z.enum(['replace', 'add', 'remove']),
+            labels: zod_1.z.array(zod_1.z.string()).min(1)
+        }
+    }, async ({ project, issue_iid, mode, labels }) => {
+        return runTool(async () => {
+            deps.issueWorkflowPolicy.assertActionAllowed('label_update');
+            deps.issueWorkflowPolicy.assertLabelsAllowed(labels);
+            const resolvedProject = deps.projectResolver.resolveProject(project);
+            const stateLabels = deps.config.issueWorkflow.allowedLabels;
+            const issue = await deps.updateIssueLabelsUseCase.execute({
+                project: resolvedProject,
+                issueIid: issue_iid,
+                mode,
+                labels,
+                autoRemovePreviousStateLabels: deps.config.issueWorkflow.autoRemovePreviousStateLabels,
+                stateLabels
+            });
+            return { resolved_project: resolvedProject, issue };
+        });
+    });
+    server.registerTool('gitlab_list_issues', {
+        title: 'GitLab List Issues',
+        description: 'List issues in a project.',
+        inputSchema: {
+            project: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+            state: zod_1.z.enum(['opened', 'closed', 'all']).optional(),
+            search: zod_1.z.string().optional(),
+            labels: zod_1.z.array(zod_1.z.string()).optional(),
+            per_page: zod_1.z.number().int().min(1).max(100).optional(),
+            page: zod_1.z.number().int().min(1).optional()
+        }
+    }, async ({ project, state, search, labels, per_page, page }) => {
+        return runTool(async () => {
+            deps.issueWorkflowPolicy.assertEnabled();
+            if (labels) {
+                deps.issueWorkflowPolicy.assertLabelsAllowed(labels);
+            }
+            const resolvedProject = deps.projectResolver.resolveProject(project);
+            const issues = await deps.listIssuesUseCase.execute({
+                project: resolvedProject,
+                state,
+                search,
+                labels,
+                perPage: per_page,
+                page
+            });
+            return { resolved_project: resolvedProject, issues };
+        });
+    });
+    server.registerTool('gitlab_list_labels', {
+        title: 'GitLab List Labels',
+        description: 'List labels for a project.',
+        inputSchema: {
+            project: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+            search: zod_1.z.string().optional()
+        }
+    }, async ({ project, search }) => {
+        return runTool(async () => {
+            deps.issueWorkflowPolicy.assertEnabled();
+            const resolvedProject = deps.projectResolver.resolveProject(project);
+            const labels = await deps.listLabelsUseCase.execute({
+                project: resolvedProject,
+                search
+            });
+            return { resolved_project: resolvedProject, labels };
+        });
+    });
+    server.registerTool('gitlab_ensure_labels', {
+        title: 'GitLab Ensure Labels',
+        description: 'Create missing labels in a project.',
+        inputSchema: {
+            project: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+            labels: zod_1.z
+                .array(zod_1.z.object({
+                name: zod_1.z.string().min(1),
+                color: zod_1.z.string().optional(),
+                description: zod_1.z.string().optional()
+            }))
+                .min(1)
+        }
+    }, async ({ project, labels }) => {
+        return runTool(async () => {
+            deps.issueWorkflowPolicy.assertActionAllowed('label_update');
+            deps.issueWorkflowPolicy.assertLabelsAllowed(labels.map((label) => label.name));
+            const resolvedProject = deps.projectResolver.resolveProject(project);
+            const result = await deps.ensureLabelsUseCase.execute({
+                project: resolvedProject,
+                labels
+            });
+            return { resolved_project: resolvedProject, ...result };
+        });
+    });
+}
+async function runTool(execute) {
+    try {
+        const data = await execute();
+        return asJsonResult({ ok: true, data });
+    }
+    catch (error) {
+        const message = error instanceof errors_1.PolicyError
+            ? error.message
+            : error instanceof Error
+                ? error.message
+                : 'Unexpected tool error';
+        return asJsonResult({ ok: false, error: message });
+    }
+}
+function asJsonResult(payload) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(payload)
+            }
+        ]
+    };
+}

package/build/src/shared/config.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+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'),
+    GITLAB_OAUTH_ACCESS_TOKEN: zod_1.z.string().optional(),
+    GITLAB_OAUTH_CLIENT_ID: zod_1.z.string().optional(),
+    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_AUTO_LOGIN: zod_1.z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value !== 'false'),
+    GITLAB_OAUTH_OPEN_BROWSER: zod_1.z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value !== 'false'),
+    GITLAB_PAT: zod_1.z.string().optional(),
+    GITLAB_DEFAULT_PROJECT: zod_1.z.string().optional(),
+    GITLAB_AUTO_RESOLVE_PROJECT_FROM_GIT: zod_1.z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value !== 'false'),
+    ISSUE_WORKFLOW_ENABLED: zod_1.z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value !== 'false'),
+    ISSUE_WORKFLOW_ALLOW_CREATE: zod_1.z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value !== 'false'),
+    ISSUE_WORKFLOW_ALLOW_CLOSE: zod_1.z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value !== 'false'),
+    ISSUE_WORKFLOW_ALLOW_LABEL_UPDATE: zod_1.z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value !== 'false'),
+    ISSUE_WORKFLOW_ALLOWED_LABELS: zod_1.z.string().optional(),
+    ISSUE_WORKFLOW_AUTO_REMOVE_PREVIOUS_STATE_LABELS: zod_1.z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value !== 'false')
+});
+function loadConfig() {
+    const env = EnvSchema.parse(process.env);
+    const autoDetectedProject = env.GITLAB_AUTO_RESOLVE_PROJECT_FROM_GIT
+        ? detectProjectFromGitRemote()
+        : undefined;
+    return {
+        gitlab: {
+            apiUrl: env.GITLAB_API_URL,
+            authMode: env.GITLAB_AUTH_MODE,
+            accessToken: resolveAccessToken(env),
+            oauth: {
+                clientId: env.GITLAB_OAUTH_CLIENT_ID,
+                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,
+                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
+        },
+        issueWorkflow: {
+            enabled: env.ISSUE_WORKFLOW_ENABLED,
+            allowCreate: env.ISSUE_WORKFLOW_ALLOW_CREATE,
+            allowClose: env.ISSUE_WORKFLOW_ALLOW_CLOSE,
+            allowLabelUpdate: env.ISSUE_WORKFLOW_ALLOW_LABEL_UPDATE,
+            allowedLabels: splitCsv(env.ISSUE_WORKFLOW_ALLOWED_LABELS),
+            autoRemovePreviousStateLabels: env.ISSUE_WORKFLOW_AUTO_REMOVE_PREVIOUS_STATE_LABELS
+        }
+    };
+}
+function resolveAccessToken(env) {
+    if (env.GITLAB_AUTH_MODE === 'oauth') {
+        return env.GITLAB_OAUTH_ACCESS_TOKEN;
+    }
+    return env.GITLAB_PAT;
+}
+function splitCsv(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function detectProjectFromGitRemote() {
+    try {
+        const origin = (0, node_child_process_1.execSync)('git config --get remote.origin.url', {
+            stdio: ['ignore', 'pipe', 'ignore']
+        })
+            .toString()
+            .trim();
+        return parseProjectPathFromRemote(origin);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseProjectPathFromRemote(remote) {
+    const sshMatch = remote.match(/^[^@]+@[^:]+:(.+?)(?:\.git)?$/);
+    if (sshMatch?.[1]) {
+        return sshMatch[1];
+    }
+    const httpsMatch = remote.match(/^https?:\/\/[^/]+\/(.+?)(?:\.git)?$/);
+    if (httpsMatch?.[1]) {
+        return httpsMatch[1];
+    }
+    return undefined;
+}

package/build/src/shared/errors.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigurationError = exports.PolicyError = void 0;
+class PolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PolicyError';
+    }
+}
+exports.PolicyError = PolicyError;
+class ConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigurationError';
+    }
+}
+exports.ConfigurationError = ConfigurationError;

package/docs/README.md

@@ -0,0 +1,16 @@
+# Docs
+
+Документация разделена на два блока:
+
+- `docs/agent/` — настройки ИИ-агента (роли, правила, запреты, commit policy).
+- `docs/architecture/` — архитектурные решения и структура модулей.
+- `docs/tasks/` — задачи для агента и статус выполнения.
+- `docs/agent/context7-policy.md` — регламент использования актуальной документации.
+- `docs/agent/stack-decision.md` — выбранный стек и решение по framework.
+- `docs/architecture/issue-tools-v0.md` — контракт MCP tools для issue/labels workflow.
+- `docs/architecture/auth-strategy.md` — стратегия аутентификации (OAuth-first).
+- `docs/USER_GUIDE.md` — инструкция для конечного пользователя.
+- `docs/GITHUB_DESCRIPTION.md` — тексты для оформления GitHub-репозитория.
+- `docs/RELEASE_CHECKLIST.md` — чеклист первого релиза (GitHub + npm).
+
+Точка входа для агента: `AGENTS.md` в корне репозитория.