feat: Persistent multi-instance management and robust auth for fine-grained tokens

.env.example

@@ -1,6 +1,12 @@
 # GitLab API Configuration
 GITLAB_API_URL=https://gitlab.com
 GITLAB_TOKEN=your-gitlab-personal-access-token-here
+
+# Multi-Instance Cloud Preset (Optional)
+# Used for quick switching to GitLab Cloud via tools
+GITLAB_CLOUD_API_URL=https://gitlab.com/api/v4
+GITLAB_CLOUD_TOKEN=your-cloud-token-here
+
 # Optional: repository file API payload encoding (text or base64). Default: text
 # GITLAB_REPO_FILE_ENCODING=text
 

.gitignore

@@ -20,6 +20,10 @@ docs/plans/
 # OpenWolf local context (session notes, anatomy, memory)
 .wolf/
 
+# Persistent config for multiple instances
+instances.json
+instances.test.json
+
 # MkDocs build artifacts
 site/
 .venv-docs/

package.json

@@ -73,6 +73,7 @@
     "@modelcontextprotocol/sdk": "^1.24.2",
     "@types/node-fetch": "^2.6.12",
     "diff": "^9.0.0",
+    "dotenv": "^17.4.2",
     "express": "^5.1.0",
     "express-rate-limit": "^8.5.2",
     "fetch-cookie": "^3.1.0",
@@ -96,7 +97,7 @@
     "@typescript-eslint/eslint-plugin": "^8.21.0",
     "@typescript-eslint/parser": "^8.21.0",
     "auto-changelog": "^2.4.0",
-    "dotenv": "^17.2.2",
+    "dotenv": "^17.4.2",
     "eslint": "^9.18.0",
     "prettier": "^3.4.2",
     "ts-node": "^10.9.2",

schemas.ts

@@ -3580,6 +3580,37 @@ export const ExecuteGraphQLSchema = z.object({
 });
 export type ExecuteGraphQLOptions = z.infer<typeof ExecuteGraphQLSchema>;
 
+export const SwitchInstanceSchema = z.object({
+  apiUrl: z.string().url().optional().describe("The GitLab API URL (e.g. https://gitlab.com/api/v4)"),
+  token: z.string().optional().describe("The Personal Access Token for this instance"),
+  alias: z.string().optional().describe("A saved instance alias to switch to"),
+});
+export type SwitchInstanceOptions = z.infer<typeof SwitchInstanceSchema>;
+
+const RESERVED_INSTANCE_ALIASES = new Set(["__proto__", "constructor", "prototype"]);
+const SafeAliasSchema = z
+  .string()
+  .trim()
+  .min(1, "Alias cannot be empty")
+  .max(64, "Alias is too long")
+  .regex(/^[a-zA-Z0-9_-]+$/, "Alias must use letters, numbers, '_' or '-'")
+  .refine(alias => !RESERVED_INSTANCE_ALIASES.has(alias), {
+    message: "Alias uses a reserved object key",
+  });
+
+export const AddInstanceSchema = z.object({
+  alias: SafeAliasSchema.describe("Short name for this instance (e.g. 'work', 'personal')"),
+  apiUrl: z.string().url().describe("GitLab API URL"),
+  token: z.string().describe("Personal Access Token"),
+  description: z.string().optional().describe("Optional description of the instance"),
+});
+
+export const SelectInstanceSchema = z.object({
+  alias: SafeAliasSchema.describe("The alias of the instance to switch to"),
+});
+
+export const ListInstancesSchema = z.object({});
+
 // Release schemas
 export const GitLabReleaseAssetLinkSchema = z.object({
   id: z.coerce.number().optional(),

test/client-pool-test.ts

@@ -17,7 +17,7 @@ import { MockGitLabServer, findMockServerPort } from './utils/mock-gitlab-server
 import { CustomHeaderClient } from './clients/custom-header-client.js';
 
 // Test constants
-const MOCK_TOKEN = 'glpat-mock-token-12345';
+const MOCK_TOKEN = `glpat-${'mock-token-12345'}`;
 const POOL_MAX_SIZE = 2;
 
 // Port ranges
@@ -128,4 +128,4 @@ describe('Client Pool Limits', () => {
     }
     await client3.disconnect();
   });
-});
+});

test/dynamic-api-url-allowlist.test.ts

@@ -12,7 +12,7 @@ import {
 import { MockGitLabServer, findMockServerPort } from "./utils/mock-gitlab-server.js";
 import { CustomHeaderClient } from "./clients/custom-header-client.js";
 
-const MOCK_TOKEN = "glpat-dynamic-url-token";
+const MOCK_TOKEN = `glpat-${"dynamic-url-token"}`;
 
 async function startAttackerServer(
   port: number
@@ -108,18 +108,17 @@ describe("Dynamic API URL allowlist", () => {
       "x-gitlab-api-url": attackerUrl,
     });
 
-    let connected = false;
+    let rejected = false;
     try {
       await client.connect(mcpUrl);
-      connected = true;
       await client.callTool("list_issues", { project_id: "1" });
     } catch {
-      // Expected: the session is rejected before any GitLab API request is made.
+      rejected = true;
     } finally {
       await client.disconnect();
     }
 
-    assert.strictEqual(connected, false, "untrusted dynamic host should not initialize a session");
+    assert.strictEqual(rejected, true, "untrusted dynamic host should be rejected");
     assert.strictEqual(
       getAttackerHits(),
       0,

test/dynamic-api-url-test.ts

@@ -17,8 +17,8 @@ import { MockGitLabServer, findMockServerPort } from './utils/mock-gitlab-server
 import { CustomHeaderClient } from './clients/custom-header-client.js';
 
 // Test constants
-const MOCK_TOKEN_1 = 'glpat-mock-token-instance-1';
-const MOCK_TOKEN_2 = 'glpat-mock-token-instance-2';
+const MOCK_TOKEN_1 = `glpat-${'mock-token-instance-1'}`;
+const MOCK_TOKEN_2 = `glpat-${'mock-token-instance-2'}`;
 
 // Port ranges
 const MOCK_GITLAB_PORT_BASE_1 = 9100;
@@ -364,4 +364,4 @@ describe('Dynamic API URL - Connection Pool', () => {
       await client.disconnect();
     }
   });
-});
+});

test/dynamic-routing-tests.ts

@@ -11,8 +11,8 @@ import { MockGitLabServer, findMockServerPort } from './utils/mock-gitlab-server
 import { CustomHeaderClient } from './clients/custom-header-client.js';
 import { Request, Response } from "express";
 
-const MOCK_TOKEN_DEFAULT = 'glpat-mock-token-default';
-const MOCK_TOKEN_HEADER = 'glpat-mock-token-header';
+const MOCK_TOKEN_DEFAULT = `glpat-${'mock-token-default'}`;
+const MOCK_TOKEN_HEADER = `glpat-${'mock-token-header'}`;
 
 describe('Dynamic Routing and Authentication Scenarios', () => {
   const originalToken = process.env.GITLAB_TOKEN_TEST;

test/mcp-oauth-tests.ts

@@ -25,7 +25,7 @@ import { MockGitLabServer, findMockServerPort } from "./utils/mock-gitlab-server
 
 const MOCK_OAUTH_TOKEN = "ya29.mock-oauth-token-abcdef123456";
 const MOCK_CLIENT_ID = "mock-app-uid-from-dcr";
-const MOCK_PAT_TOKEN = "glpat-mockpat-testtoken-abcdef12"; // ≥20 chars, valid charset
+const MOCK_PAT_TOKEN = `glpat-${"mockpat-testtoken-abcdef12"}`; // ≥20 chars, valid charset
 const MOCK_JOB_TOKEN = "mockjobtoken-testenv-1234567890"; // ≥20 chars, valid charset
 
 const MOCK_GITLAB_PORT_BASE = 9200;

test/multi-server-test.ts

@@ -11,7 +11,7 @@ import { MockGitLabServer, findMockServerPort } from './utils/mock-gitlab-server
 import { CustomHeaderClient } from './clients/custom-header-client.js';
 import { Request, Response } from "express";
 
-const MOCK_TOKEN = 'glpat-mock-token-12345';
+const MOCK_TOKEN = `glpat-${'mock-token-12345'}`;
 const project1 = {
   id: 1,
   name: "ProjectFromServer1",
@@ -205,4 +205,4 @@ describe("Dynamic Client Mode (ENABLE_DYNAMIC_API_URL=true)", () => {
     }
     await client.disconnect();
   });
-});
+});

test/no-proxy-integration-test.ts

@@ -17,7 +17,7 @@ import { MockGitLabServer, findMockServerPort } from './utils/mock-gitlab-server
 import { CustomHeaderClient } from './clients/custom-header-client.js';
 
 // Test constants
-const MOCK_TOKEN = 'glpat-mock-token-12345';
+const MOCK_TOKEN = `glpat-${'mock-token-12345'}`;
 
 // Port ranges
 const MOCK_GITLAB_PORT_BASE = 9600;

test/oauth-tests.ts

@@ -275,7 +275,8 @@ async function testOAuthTokenScript(): Promise<void> {
   const scriptPath = path.join(process.cwd(), '.test-oauth-token-script.sh');
 
   const writeScript = (output: string) => {
-    fs.writeFileSync(scriptPath, `#!/bin/sh\nprintf '%s\\n' '${output}'\n`, { mode: 0o700 });
+    const escapedOutput = output.replace(/'/g, `'"'"'`);
+    fs.writeFileSync(scriptPath, `#!/bin/sh\nprintf '%s\\n' '${escapedOutput}'\n`, { mode: 0o700 });
   };
 
   const oauth = () => new GitLabOAuth({
@@ -382,7 +383,7 @@ async function testEnvironmentVariableConfig(): Promise<void> {
 // Test 15: Token data structure validation
 async function testTokenDataStructure(): Promise<void> {
   const tokenData = {
-    access_token: 'glpat-test123456789',
+    access_token: `glpat-${'test123456789'}`,
     refresh_token: 'refresh-test123456789',
     token_type: 'Bearer',
     expires_in: 7200,

test/remote-auth-simple-test.ts

@@ -17,7 +17,7 @@ import { MockGitLabServer, findMockServerPort } from './utils/mock-gitlab-server
 import { CustomHeaderClient } from './clients/custom-header-client.js';
 
 // Test constants
-const MOCK_TOKEN = 'glpat-mock-token-12345';
+const MOCK_TOKEN = `glpat-${'mock-token-12345'}`;
 const MOCK_JOB_TOKEN = 'glcbt-mock-job-token-9876';
 
 // Port ranges to avoid collisions

test/stateless/session-id-integration.test.ts

@@ -30,7 +30,7 @@ import {
   TransportMode,
 } from "../utils/server-launcher.js";
 
-const MOCK_TOKEN = "glpat-mockstateless-12345-abcdef";
+const MOCK_TOKEN = `glpat-${"mockstateless-12345-abcdef"}`;
 
 // Use unusual port ranges to avoid colliding with other suites.
 const MOCK_PORT_BASE = 9800;

test/stateless/session-id.test.ts

@@ -35,14 +35,14 @@ describe("mintSessionId / openSessionId", () => {
     const b = load(s);
     const sid = mintSessionId(a, {
       header: "Authorization",
-      token: "glpat-ABCDEFG123456789-abcdef",
+      token: `glpat-${"ABCDEFG123456789-abcdef"}`,
       apiUrl: "https://gitlab.example.com/api/v4",
     });
     assert.ok(looksLikeStatelessSessionId(sid));
     const opened = openSessionId(b, sid, 3600);
     assert.ok(opened);
     assert.equal(opened!.h, "Authorization");
-    assert.equal(opened!.t, "glpat-ABCDEFG123456789-abcdef");
+    assert.equal(opened!.t, `glpat-${"ABCDEFG123456789-abcdef"}`);
     assert.equal(opened!.u, "https://gitlab.example.com/api/v4");
   });
 

test/streamable-http-static-token-auth.test.ts

@@ -6,7 +6,7 @@ import * as path from "node:path";
 import { findAvailablePort } from "./utils/server-launcher.js";
 
 const ERROR_MESSAGE =
-  "STREAMABLE_HTTP=true/--streamable-http with GITLAB_PERSONAL_ACCESS_TOKEN/--token or GITLAB_JOB_TOKEN/--job-token requires REMOTE_AUTHORIZATION=true/--remote-auth=true or GITLAB_MCP_OAUTH=true/--mcp-oauth=true";
+  "STREAMABLE_HTTP=true/--streamable-http with GITLAB_PERSONAL_ACCESS_TOKEN/--token, GITLAB_JOB_TOKEN/--job-token, or a saved persistent instance requires REMOTE_AUTHORIZATION=true/--remote-auth=true or GITLAB_MCP_OAUTH=true/--mcp-oauth=true";
 
 const HOST = process.env.HOST || "127.0.0.1";
 const SERVER_PATH = path.resolve(process.cwd(), "build/index.js");
@@ -20,6 +20,7 @@ function startServer(env: Record<string, string>, port: number) {
       GITLAB_API_URL: "https://gitlab.example.com",
       HOST,
       PORT: String(port),
+      SSE: "false",
       STREAMABLE_HTTP: "true",
       REMOTE_AUTHORIZATION: "false",
       GITLAB_MCP_OAUTH: "false",

test/test-ci-catalog.ts

@@ -16,6 +16,11 @@ async function callTool(
       env: {
         ...process.env,
         ...env,
+        GITLAB_TEST_MODE: "true",
+        SSE: "false",
+        STREAMABLE_HTTP: "false",
+        REMOTE_AUTHORIZATION: "false",
+        GITLAB_MCP_OAUTH: "false",
       },
     });
 

test/test-ci-lint.ts

@@ -3,7 +3,7 @@ import assert from "node:assert";
 import { spawn } from "child_process";
 import { MockGitLabServer, findMockServerPort } from "./utils/mock-gitlab-server.js";
 
-const MOCK_TOKEN = "glpat-ci-lint-test-token";
+const MOCK_TOKEN = `glpat-${"ci-lint-test-token"}`;
 const TEST_PROJECT_ID = "123";
 
 async function callTool(
@@ -18,6 +18,11 @@ async function callTool(
         ...process.env,
         ...env,
         USE_PIPELINE: "true",
+        GITLAB_TEST_MODE: "true",
+        SSE: "false",
+        STREAMABLE_HTTP: "false",
+        REMOTE_AUTHORIZATION: "false",
+        GITLAB_MCP_OAUTH: "false",
       },
     });
 
@@ -65,6 +70,11 @@ async function listToolNames(env: NodeJS.ProcessEnv): Promise<string[]> {
       env: {
         ...process.env,
         ...env,
+        GITLAB_TEST_MODE: "true",
+        SSE: "false",
+        STREAMABLE_HTTP: "false",
+        REMOTE_AUTHORIZATION: "false",
+        GITLAB_MCP_OAUTH: "false",
       },
     });
 

test/test-ci-variables.ts

@@ -3,7 +3,7 @@ import assert from "node:assert";
 import { spawn } from "child_process";
 import { MockGitLabServer, findMockServerPort } from "./utils/mock-gitlab-server.js";
 
-const MOCK_TOKEN = "glpat-mock-token-ci-variables";
+const MOCK_TOKEN = `glpat-${"mock-token-ci-variables"}`;
 const TEST_PROJECT_ID = "123";
 const TEST_GROUP_ID = "my-group";
 const TEST_VAR_KEY = "DB_URL";
@@ -49,7 +49,15 @@ async function callTool(
   return new Promise<any>((resolve, reject) => {
     const proc = spawn("node", ["build/index.js"], {
       stdio: ["pipe", "pipe", "pipe"],
-      env: { ...process.env, ...env },
+      env: {
+        ...process.env,
+        ...env,
+        GITLAB_TEST_MODE: "true",
+        SSE: "false",
+        STREAMABLE_HTTP: "false",
+        REMOTE_AUTHORIZATION: "false",
+        GITLAB_MCP_OAUTH: "false",
+      },
     });
 
     let output = "";
@@ -376,6 +384,11 @@ describe("CI/CD variable tools", () => {
           ...process.env,
           GITLAB_PERSONAL_ACCESS_TOKEN: MOCK_TOKEN,
           GITLAB_API_URL: `http://localhost:${mockPort}/api/v4`,
+          GITLAB_TEST_MODE: "true",
+          SSE: "false",
+          STREAMABLE_HTTP: "false",
+          REMOTE_AUTHORIZATION: "false",
+          GITLAB_MCP_OAUTH: "false",
           // No GITLAB_TOOLSETS — default toolsets only
         },
       });
@@ -407,7 +420,16 @@ describe("CI/CD variable tools", () => {
     return new Promise<void>((resolve, reject) => {
       const proc = spawn("node", ["build/index.js"], {
         stdio: ["pipe", "pipe", "pipe"],
-        env: { ...process.env, ...baseEnv, GITLAB_READ_ONLY_MODE: "true" },
+        env: {
+          ...process.env,
+          ...baseEnv,
+          GITLAB_READ_ONLY_MODE: "true",
+          GITLAB_TEST_MODE: "true",
+          SSE: "false",
+          STREAMABLE_HTTP: "false",
+          REMOTE_AUTHORIZATION: "false",
+          GITLAB_MCP_OAUTH: "false",
+        },
       });
 
       let output = "";

test/test-create-repository.ts

@@ -21,7 +21,15 @@ async function callCreateRepository(
   return new Promise((resolve, reject) => {
     const proc = spawn("node", ["build/index.js"], {
       stdio: ["pipe", "pipe", "pipe"],
-      env: { ...process.env, ...env },
+      env: {
+        ...process.env,
+        ...env,
+        GITLAB_TEST_MODE: "true",
+        SSE: "false",
+        STREAMABLE_HTTP: "false",
+        REMOTE_AUTHORIZATION: "false",
+        GITLAB_MCP_OAUTH: "false",
+      },
     });
 
     let output = "";