@jswk1/gitlab-mcp 0.0.0-stage → 1.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,213 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# GitLab read-only MCP server
+
+Give your AI assistant GitLab issues, merge requests, discussions and attachments from a self-managed instance. The server reads GitLab; your assistant uses its own tools to inspect and edit your local repository.
+
+## Setup
+
+- **GitLab 17.4+** for attachment downloads. Older versions are untested.
+- **A personal access token with `read_api` scope**, belonging to the developer using the assistant. The token owner's GitLab permissions determine access, including confidential issues.
+- **Node.js 20.20+** for npm/local setup, or **Docker** for container setup.
+
+Choose one option below and add its configuration to your MCP client's settings. All options use **stdio**: the client starts the server and communicates over stdin/stdout. Run one server process per developer/client; there is no HTTP endpoint.
+
+### Option 1: npm package
+
+Configure your MCP client to run the npm package:
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "npx",
+      "args": ["--yes", "--package=@jswk1/gitlab-mcp@1.1.0", "gitlab-mcp"],
+      "env": {
+        "GITLAB_URL": "https://gitlab.example.internal",
+        "GITLAB_TOKEN": "YOUR_PERSONAL_READ_API_TOKEN"
+      }
+    }
+  }
+}
+```
+
+The first run downloads the package. Keep a pinned version for reproducible installs. If the package is unavailable, build locally or use Docker.
+
+### Option 2: local build over stdio
+
+From the repository root:
+
+```sh
+npm ci
+npm run build
+```
+
+Point your MCP client at the compiled entry point using an absolute path:
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "node",
+      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
+      "env": {
+        "GITLAB_URL": "https://gitlab.example.internal",
+        "GITLAB_TOKEN": "YOUR_PERSONAL_READ_API_TOKEN"
+      }
+    }
+  }
+}
+```
+
+To launch manually, copy `.env.example` to `.env`, fill in your credentials, then run `node --env-file=.env dist/index.js`. The process waits for MCP messages; it is not an interactive terminal application.
+
+### Option 3: Docker
+
+From the repository root:
+
+```sh
+npm run docker:build
+cp .env.example .env
+```
+
+Fill in `GITLAB_URL` and `GITLAB_TOKEN` in `.env`, then configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "docker",
+      "args": [
+        "run", "--rm", "-i",
+        "--env-file", "/absolute/path/to/gitlab-mcp/.env",
+        "gitlab-readonly-mcp"
+      ]
+    }
+  }
+}
+```
+
+Keep `-i`; do not add `-t` or `-d`. No ports or repository mounts are needed. The image runs as a non-root user and receives credentials at runtime.
+
+GitLab must be reachable from inside the container. On Docker Desktop, use `host.docker.internal` to reach GitLab on your host. On Linux Docker Engine, also add `--add-host=host.docker.internal:host-gateway` to the Docker arguments when using that hostname.
+
+After source updates, rebuild the image and restart your client's MCP connection to create a new container.
+
+## Workflows
+
+Ask your assistant to work on an issue or MR in your local repository. It can start with `gitlab_get_workflow`, passing `project`, `iid`, `target` (`issue` or `merge_request`), optional `profile`, optional `goal` to specify scope, and optional `mode` for developer/documentalist issue resolution.
+
+| Profile | Issue | Merge request |
+| --- | --- | --- |
+| `developer` (default) | Investigate and guide the user through a fix/feature, or implement automatically when selected | Review changed code for bugs, regressions and improvements |
+| `tester` | Inspect the latest related implementation and prepare prioritized manual test cases | Prepare a manual test plan for changed behavior |
+| `documentalist` | Guide documentation implementation, or edit automatically when selected, using merged/current implementation | Update local Markdown docs to match the implementation |
+| `business_analyst` (business analyst/designer) | Report on client requirements and issue status; reconcile external sheets | Summarize business/design impact for client reporting |
+
+Profiles apply per task and share the same tools and permissions. The workflow tool returns guidance; the assistant gathers evidence and performs local work. Tester workflows produce plans, not test execution. Implementation and documentation edits require a client with local repository access and editing tools.
+
+Developer and documentalist issue resolution offers **guided mode (recommended)** and **fully automated mode**. If the user asks to resolve, fix, implement or update an issue without choosing a mode, the assistant asks which they prefer and waits before making changes. A plain implementation request does not select automation. Explicit requests such as “automatically implement this issue” skip the question, as do explicit guided requests or an existing mode choice for the same task. Analysis-only, plan-only and draft-only requests keep their scope without a mode question.
+
+In guided mode, the user edits the code, tests or documentation. The assistant investigates, outlines the approach, then gives one manageable step at a time with relevant files, what to change, why, pitfalls and checks. It waits for the user's changes/results, reviews them and adapts the next step. In automated mode, the assistant performs the implementation and checks. Neither mode authorizes commits, pushes or GitLab writes.
+
+Clients can pass `mode: "guided"` or `mode: "automated"` to `gitlab_get_workflow`, `implement_issue`, `investigate_issue` or `update_documentation`. Omitting it (or passing `"ask"`) delegates the mode question and interpretation of explicit user intent to the host assistant. Workflow calls do not persist choices; the host carries the user's selection forward for the same task. Mode selection applies to developer/documentalist issue implementation; MR reviews, tester and reporting workflows retain their existing behavior.
+
+For aggregate reporting, select `profile: "business_analyst"`, `target: "report"`, `project` and a `goal`; omit `iid`. This mode does not require a source checkout. The assistant uses host file tools to generate actual CSV files with the requested columns (or returns CSV text if file tools are unavailable). External sheets require a user-provided file or an authorized host connector; this server does not connect to or update sheets itself.
+
+Client attribution must use an explicit label or supplied mapping. Reports follow all issue pages and filter `closed_at` locally with inclusive start and exclusive end dates in the agreed timezone. Current closed issues do not describe historical closure events for reopened issues. Milestone membership and closure dates are separate filters. Reports include source links, exact filters, retrieval time, totals and coverage limits. Client-facing exports omit confidential/internal content unless authorized, and CSV text cells are protected against spreadsheet formulas. Reconciliation preserves stable issue and external row identifiers and reports duplicates, missing rows and conflicts.
+
+Example requests:
+
+- “Guide me through fixing issue #123. I want to make the changes myself.”
+- “Automatically implement issue #123, including the relevant tests.”
+- “Read issue #123 in `group/project`, including comments and attachments, and fix the validation bug in this repository.”
+- “Review MR !456 in `group/project`. Return findings limited to changed code, ordered by severity.”
+- “Use the tester profile for issue #123 in `group/project` and prepare the critical manual test cases for the latest related branch.”
+- “Use the documentalist profile for MR !456 in `group/project` and update the affected Markdown docs.”
+- “Use the business analyst/designer profile: export issues closed for client X in Q3 2026 from `group/project`. Client X uses label `client::X`; use Europe/Warsaw time and include IID, title, milestone, closed date and URL.”
+- “Generate a CSV of closed client X issues in milestone `Release 2.0`, then reconcile it with this client sheet and report missing or conflicting rows.”
+
+Clients supporting MCP prompts can use these shortcuts:
+
+| Prompt | Purpose | Arguments |
+| --- | --- | --- |
+| `report_issues` | Generate reports/CSVs or reconcile sheets as business analyst/designer | `project`, `goal` |
+| `implement_issue` | Resolve an issue as developer in guided or automated mode | `project`, `iid`, optional `goal`, `mode` |
+| `investigate_issue` | Investigate or act on an issue | `project`, `iid`, optional `profile`, `goal`, `mode` |
+| `review_merge_request` | Review an MR using the selected profile | `project`, `iid`, optional `profile`, `goal` |
+| `prepare_test_plan` | Plan manual tests as tester | `project`, `iid`, `target`, optional `goal` |
+| `update_documentation` | Resolve documentation as documentalist; issues offer guided/automated modes | `project`, `iid`, `target`, optional `goal`, `mode` |
+| `draft_documentation` | Return documentation drafts without editing files | `project`, `iid`, `target` |
+
+## Available tools
+
+| Tool | Purpose |
+| --- | --- |
+| `gitlab_get_workflow` | Get task guidance for a profile and issue/MR or aggregate report |
+| `gitlab_current_user` | Identify the token owner |
+| `gitlab_list_projects` | Find accessible projects |
+| `gitlab_get_project` | Read project metadata and default branch |
+| `gitlab_list_branches` | Find branches and head commit metadata |
+| `gitlab_get_branch` | Resolve a branch's current head SHA and commit date |
+| `gitlab_compare_refs` | Compare branches or commits, including changes without an MR |
+| `gitlab_list_issues` | Search issues by text, labels, state, milestone title and update lower bound |
+| `gitlab_get_issue` | Read issue metadata, description and discovered uploads |
+| `gitlab_issue_related_merge_requests` | Find MRs associated with an issue |
+| `gitlab_get_discussions` | Read issue/MR threads, replies, review positions and uploads |
+| `gitlab_read_attachment` | Reuse cached analysis or read an upload by project, secret and filename |
+| `gitlab_save_attachment_summary` | Save completed host analysis in the local cache; never writes to GitLab |
+| `gitlab_list_merge_requests` | Search merge requests |
+| `gitlab_get_merge_request` | Read MR metadata, description, diff SHAs and pipeline summary |
+| `gitlab_get_merge_request_diffs` | Read changed files and unified diffs |
+| `gitlab_list_merge_request_commits` | Read MR commits |
+| `gitlab_repository_tree` | Browse repository paths when unavailable locally |
+| `gitlab_read_file` | Read repository text when unavailable locally |
+| `gitlab_prepare_review_comment` | Prepare a general or validated inline draft without posting |
+
+`project` accepts a numeric ID or `group/subgroup/repository` path. Issue/MR `iid` is the project-local number in its web URL. Paginated tools return `items` and `nextPage`; follow pages until `nextPage` is null for complete results. Default page size is 20, maximum 100. Ref comparisons do not paginate diffs; GitLab can omit or truncate diffs, so check `compare_timeout`, `collapsed` and `too_large` where returned.
+
+Issue reporting filters use the [GitLab Issues API](https://docs.gitlab.com/api/issues/). `milestone` is a title; `updated_after` is an update-time lower bound, not a closure-time filter.
+
+## Attachment cache
+
+Attachment downloads and analysis summaries persist locally across server restarts. The assistant first calls `gitlab_read_attachment`. If a summary exists for the requested `analysis_focus` (default `general`), the server returns that summary instead of sending the image/video back for interpretation. Otherwise it reuses cached bytes or downloads the upload once. Concurrent reads of the same upload share one download.
+
+After actually inspecting the attachment, the assistant calls `gitlab_save_attachment_summary` with the returned `sha256`, matching `analysis_focus`, `inspected: true`, factual `summary`, inspection `method`, `coverage` and `limitations`. The server stores the host's analysis; it does not run a vision/video model itself. Summaries are bound to the downloaded content hash. Video frames or transcripts must be marked partial with explicit limitations; an unsupported download alone does not count as inspection. The workflows tell the assistant to save and reuse these summaries during subsequent resolution steps.
+
+- `reuse_summary: false` reopens the cached content for more detailed inspection without downloading again.
+- A different `analysis_focus` keeps a separate summary for a different question (up to 10 scopes per upload).
+- `refresh: true` downloads a fresh copy and invalidates previous summaries, even if the bytes are unchanged.
+- `output: "resource"` returns cached raw bytes for a capable host/parser instead of a summary.
+
+The default directory is `~/.cache/gitlab-mcp/attachments`. Entries expire for reuse after seven days and the cache retains at most 256 uploads across server processes, evicting older files when new entries are saved. Each upload remains subject to `GITLAB_MAX_BYTES`. Cache files contain private attachment content and summaries, use owner-only file permissions, and never store the token. Entries are isolated by GitLab instance, token, project and upload identity; token rotation starts a separate cache. Cached reads require a live authenticated project-access check, so they cannot be used offline. This check validates project access, not whether an individual upload has since been deleted; use refresh when fresh attachment availability matters. Remove the cache directory with the server stopped to clear all stored content. If disk caching is unavailable, downloads still use a bounded in-memory cache; a failed summary persistence request returns an error.
+
+For Docker, persist the cache by adding these arguments before the image name in the existing configuration:
+
+```json
+"--mount", "type=volume,src=gitlab-mcp-cache,dst=/home/node/.cache/gitlab-mcp"
+```
+
+Without a volume, Docker's `--rm` removes cached content when the container exits.
+
+## Configuration
+
+| Environment variable | Default | Purpose |
+| --- | --- | --- |
+| `GITLAB_URL` | Required | GitLab instance root, optionally with a subpath; omit `/api/v4` |
+| `GITLAB_TOKEN` | Required | Developer's personal access token with `read_api` |
+| `GITLAB_USER_ID` | Optional | Expected numeric user ID; startup fails if the token belongs to another user |
+| `GITLAB_TIMEOUT_MS` | `30000` | Timeout per API request and response body |
+| `GITLAB_CACHE_DIR` | `~/.cache/gitlab-mcp/attachments` | Local attachment and summary cache directory |
+| `GITLAB_CACHE_TTL_MS` | `604800000` (7 days) | Maximum age for reuse since download |
+| `GITLAB_CACHE_MAX_ENTRIES` | `256` | Maximum retained uploads |
+| `GITLAB_MAX_BYTES` | `5242880` (5 MiB) | Maximum response size per request |
+| `NODE_EXTRA_CA_CERTS` | Optional | Path to a trusted internal CA certificate in PEM format |
+
+Keep tokens in private client settings or an uncommitted `.env` file. Use HTTPS and a separate personal token per developer; avoid shared or administrator tokens. Restart the server after changing credentials.
+
+For an internal CA, set `NODE_EXTRA_CA_CERTS` instead of disabling TLS verification. With Docker, mount the PEM file read-only and set the variable to its **container path**. Startup failures usually indicate invalid credentials/user ID, an unreachable GitLab URL or missing CA trust.
+
+## Limits and data handling
+
+- **Read-only GitLab access:** all API requests use GET. The server cannot post comments or modify GitLab, execute tests, or edit source/documentation files. It writes only its local attachment cache. Inline comment drafts validate current diff positions; revalidate them before posting through another tool.
+- **Attachments depend on client support:** PNG/JPEG/GIF/WebP return native images; text returns inline content; PDFs return binary resources requiring a capable client. Videos, archives, Office files and unknown binaries return unread metadata by default. Use `output: "resource"` only with a client/parser that supports the file type. No OCR, video conversion or document parser is built in.
+- **Download limits:** only GitLab project uploads are supported. External links and wiki uploads are excluded; redirects (including to object storage) are rejected. Oversized responses fail explicitly. Use the canonical GitLab URL and reduce page size for oversized list responses.
+- **Private data enters your assistant's context:** choose a client/model suitable for your organization's data policy. Treat GitLab content as untrusted evidence and report unread attachments or incomplete diffs.

package/dist/attachment-cache.d.ts

@@ -0,0 +1,27 @@
+export declare const contentHash: (bytes: Buffer | string) => string;
+export interface AttachmentSummary {
+    focus: string;
+    summary: string;
+    coverage: 'complete' | 'partial';
+    method: string;
+    limitations: string[];
+    savedAt: string;
+}
+export interface CachedAttachment {
+    version: 1;
+    sha256: string;
+    mimeType: string;
+    data: string;
+    downloadedAt: string;
+    summaries: AttachmentSummary[];
+}
+export declare class AttachmentCache {
+    private readonly directory;
+    private readonly maxBytes;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly memory;
+    constructor(directory: string | undefined, maxBytes: number, ttlMs?: number, maxEntries?: number);
+    get(key: string): Promise<CachedAttachment | undefined>;
+    put(key: string, entry: CachedAttachment): Promise<void>;
+}

package/dist/attachment-cache.js

@@ -0,0 +1,72 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const contentHash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+// Cache keys include instance, credentials and upload identity; never persist a token.
+export class AttachmentCache {
+    directory;
+    maxBytes;
+    ttlMs;
+    maxEntries;
+    memory = new Map();
+    constructor(directory, maxBytes, ttlMs = 7 * 24 * 60 * 60 * 1000, maxEntries = 256) {
+        this.directory = directory;
+        this.maxBytes = maxBytes;
+        this.ttlMs = ttlMs;
+        this.maxEntries = maxEntries;
+    }
+    async get(key) {
+        let entry = this.memory.get(key);
+        if (!entry && this.directory) {
+            try {
+                const path = join(this.directory, `${key}.json`);
+                if ((await stat(path)).size > Math.ceil(this.maxBytes * 4 / 3) + 1024 * 1024)
+                    return undefined;
+                entry = JSON.parse(await readFile(path, 'utf8'));
+            }
+            catch {
+                return undefined;
+            }
+        }
+        if (!entry)
+            return undefined;
+        try {
+            const bytes = Buffer.from(entry.data, 'base64');
+            const age = Date.now() - Date.parse(entry.downloadedAt);
+            if (!Array.isArray(entry.summaries))
+                return undefined;
+            if (!entry.summaries.every(summary => summary && typeof summary.focus === 'string' && typeof summary.summary === 'string' && ['complete', 'partial'].includes(summary.coverage) && typeof summary.method === 'string' && typeof summary.savedAt === 'string' && Array.isArray(summary.limitations) && summary.limitations.every(value => typeof value === 'string')))
+                return undefined;
+            if (entry.version !== 1 || !Number.isFinite(age) || age < 0 || age >= this.ttlMs || bytes.length > this.maxBytes || contentHash(bytes) !== entry.sha256 || typeof entry.mimeType !== 'string' || !Array.isArray(entry.summaries))
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+        return entry;
+    }
+    async put(key, entry) {
+        this.memory.delete(key);
+        this.memory.set(key, entry);
+        while (this.memory.size > this.maxEntries)
+            this.memory.delete(this.memory.keys().next().value);
+        if (this.directory) {
+            await mkdir(this.directory, { recursive: true, mode: 0o700 });
+            const path = join(this.directory, `${key}.json`);
+            const temporary = `${path}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temporary, JSON.stringify(entry), { mode: 0o600, flag: 'wx' });
+                await rename(temporary, path);
+            }
+            finally {
+                await unlink(temporary).catch(() => { });
+            }
+            // Bound on-disk retention, including entries from earlier server processes.
+            const files = (await readdir(this.directory)).filter(name => /^[a-f\d]{64}\.json$/.test(name));
+            const dated = await Promise.all(files.map(async (name) => ({ name, time: (await stat(join(this.directory, name)).catch(() => ({ mtimeMs: 0 }))).mtimeMs })));
+            dated.sort((a, b) => b.time - a.time);
+            await Promise.all(dated.slice(this.maxEntries).map(file => unlink(join(this.directory, file.name)).catch(() => { })));
+        }
+    }
+}
+//# sourceMappingURL=attachment-cache.js.map

package/dist/attachment-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-cache.js","sourceRoot":"","sources":["../src/attachment-cache.ts"],"names":[],"mappings":"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"}

package/dist/attachments.d.ts

@@ -0,0 +1 @@
+export declare function uploadMimeType(bytes: Buffer, filename: string, contentType: string | null): string;

package/dist/attachments.js

@@ -0,0 +1,28 @@
+import { extname } from 'node:path';
+// GitLab/proxies may serve uploads with a generic download Content-Type.
+// Prefer recognizable bytes, then the filename, only for generic headers.
+export function uploadMimeType(bytes, filename, contentType) {
+    const declared = contentType?.split(';')[0]?.trim().toLowerCase();
+    if (declared && !['application/octet-stream', 'binary/octet-stream', 'application/binary'].includes(declared))
+        return declared;
+    if (bytes.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')))
+        return 'image/png';
+    if (bytes.length >= 3 && bytes.subarray(0, 3).equals(Buffer.from('ffd8ff', 'hex')))
+        return 'image/jpeg';
+    if (['GIF87a', 'GIF89a'].includes(bytes.toString('ascii', 0, 6)))
+        return 'image/gif';
+    if (bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP')
+        return 'image/webp';
+    if (bytes.toString('ascii', 0, 5) === '%PDF-')
+        return 'application/pdf';
+    const types = {
+        '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif', '.webp': 'image/webp', '.pdf': 'application/pdf',
+        '.mp4': 'video/mp4', '.m4v': 'video/mp4', '.mov': 'video/quicktime',
+        '.webm': 'video/webm', '.avi': 'video/x-msvideo', '.mkv': 'video/x-matroska',
+        '.txt': 'text/plain', '.log': 'text/plain', '.md': 'text/markdown',
+        '.csv': 'text/csv', '.json': 'application/json', '.xml': 'application/xml',
+    };
+    return types[extname(filename).toLowerCase()] ?? 'application/octet-stream';
+}
+//# sourceMappingURL=attachments.js.map

package/dist/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,yEAAyE;AACzE,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,QAAgB,EAAE,WAA0B;IACxF,MAAM,QAAQ,GAAG,WAAW,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClE,IAAI,QAAQ,IAAI,CAAC,CAAC,0BAA0B,EAAE,qBAAqB,EAAE,oBAAoB,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC/H,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,WAAW,CAAC;IAC5F,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,YAAY,CAAC;IACxG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,WAAW,CAAC;IACrF,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,MAAM;QAAE,OAAO,YAAY,CAAC;IAC/G,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO;QAAE,OAAO,iBAAiB,CAAC;IACxE,MAAM,KAAK,GAA2B;QACpC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY;QAChE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,iBAAiB;QACrE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,iBAAiB;QACnE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,kBAAkB;QAC5E,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe;QAClE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,iBAAiB;KAC3E,CAAC;IACF,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,0BAA0B,CAAC;AAC9E,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export interface Config {
+    baseUrl: string;
+    token: string;
+    expectedUserId?: number;
+    timeoutMs: number;
+    maxBytes: number;
+    cacheDir?: string;
+    cacheTtlMs?: number;
+    cacheMaxEntries?: number;
+}
+export declare function readConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,28 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+function integer(value, fallback, name) {
+    const parsed = value === undefined ? fallback : Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`${name} must be a positive integer`);
+    return parsed;
+}
+export function readConfig(env = process.env) {
+    if (!env.GITLAB_URL || !env.GITLAB_TOKEN?.trim())
+        throw new Error('GITLAB_URL and GITLAB_TOKEN are required');
+    const url = new URL(env.GITLAB_URL);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error('GITLAB_URL must be an HTTP(S) instance URL without credentials, query, or fragment');
+    }
+    if (/[\r\n]/.test(env.GITLAB_TOKEN))
+        throw new Error('Invalid GITLAB_TOKEN');
+    return {
+        baseUrl: url.href.replace(/\/$/, ''), token: env.GITLAB_TOKEN.trim(),
+        expectedUserId: env.GITLAB_USER_ID === undefined ? undefined : integer(env.GITLAB_USER_ID, 1, 'GITLAB_USER_ID'),
+        timeoutMs: integer(env.GITLAB_TIMEOUT_MS, 30000, 'GITLAB_TIMEOUT_MS'),
+        cacheDir: env.GITLAB_CACHE_DIR || join(homedir(), '.cache', 'gitlab-mcp', 'attachments'),
+        cacheTtlMs: integer(env.GITLAB_CACHE_TTL_MS, 7 * 24 * 60 * 60 * 1000, 'GITLAB_CACHE_TTL_MS'),
+        cacheMaxEntries: integer(env.GITLAB_CACHE_MAX_ENTRIES, 256, 'GITLAB_CACHE_MAX_ENTRIES'),
+        maxBytes: integer(env.GITLAB_MAX_BYTES, 5 * 1024 * 1024, 'GITLAB_MAX_BYTES'),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAajC,SAAS,OAAO,CAAC,KAAyB,EAAE,QAAgB,EAAE,IAAY;IACxE,MAAM,MAAM,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,6BAA6B,CAAC,CAAC;IACxG,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,IAAI,CAAC,GAAG,CAAC,UAAU,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9G,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACpC,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAC1G,MAAM,IAAI,KAAK,CAAC,oFAAoF,CAAC,CAAC;IACxG,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC7E,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE;QACpE,cAAc,EAAE,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,EAAE,gBAAgB,CAAC;QAC/G,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,KAAK,EAAE,mBAAmB,CAAC;QACrE,QAAQ,EAAE,GAAG,CAAC,gBAAgB,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,CAAC;QACxF,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,qBAAqB,CAAC;QAC5F,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,GAAG,EAAE,0BAA0B,CAAC;QACvF,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,kBAAkB,CAAC;KAC7E,CAAC;AACJ,CAAC"}

package/dist/gitlab.d.ts

@@ -0,0 +1,42 @@
+import type { Config } from './config.js';
+import { type AttachmentSummary } from './attachment-cache.js';
+export declare const segment: (value: string | number) => string;
+export declare const projectPath: (project: string) => string;
+export type Query = Record<string, string | number | boolean | undefined>;
+export interface Page<T> {
+    items: T[];
+    nextPage: number | null;
+}
+export interface Upload {
+    path: string;
+    secret: string;
+    filename: string;
+}
+export declare function findUploads(text: string): Upload[];
+export declare class GitLabError extends Error {
+}
+export declare class GitLabClient {
+    private readonly config;
+    private readonly fetcher;
+    private readonly attachmentCache;
+    private readonly pendingUploads;
+    constructor(config: Config, fetcher?: typeof fetch);
+    private attachmentKey;
+    private request;
+    json<T = unknown>(path: string, query?: Query): Promise<T>;
+    page<T = unknown>(path: string, query?: Query): Promise<Page<T>>;
+    identity(): Promise<{
+        id: number;
+        username: string;
+        name: string;
+    }>;
+    upload(project: string, secret: string, filename: string, refresh?: boolean): Promise<{
+        bytes: Buffer;
+        mimeType: string;
+        sha256: string;
+        downloadedAt: string;
+        summaries: AttachmentSummary[];
+        cached: boolean;
+    }>;
+    saveAttachmentSummary(project: string, secret: string, filename: string, sha256: string, summary: Omit<AttachmentSummary, 'savedAt'>): Promise<AttachmentSummary>;
+}