@daghis/teamcity-mcp 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.13.0](https://github.com/Daghis/teamcity-mcp/compare/teamcity-mcp-v1.12.1...teamcity-mcp-v1.13.0) (2025-12-22)
+
+
+### Features
+
+* add CLI argument support for Windows workaround ([#320](https://github.com/Daghis/teamcity-mcp/issues/320)) ([#326](https://github.com/Daghis/teamcity-mcp/issues/326)) ([cc05a4d](https://github.com/Daghis/teamcity-mcp/commit/cc05a4dd19c1d7e1f547cdd35bb910035141909d))
+
+## [1.12.1](https://github.com/Daghis/teamcity-mcp/compare/teamcity-mcp-v1.12.0...teamcity-mcp-v1.12.1) (2025-12-22)
+
+
+### Bug Fixes
+
+* handle queued builds in get_build and get_build_status ([#324](https://github.com/Daghis/teamcity-mcp/issues/324)) ([4cb2dab](https://github.com/Daghis/teamcity-mcp/commit/4cb2dabfc9161e07708a899622d78b886742459d))
+
 ## [1.12.0](https://github.com/Daghis/teamcity-mcp/compare/teamcity-mcp-v1.11.20...teamcity-mcp-v1.12.0) (2025-12-06)
 
 

package/README.md

@@ -85,10 +85,40 @@ npx -y @daghis/teamcity-mcp
   - `claude mcp add [-s user] teamcity -- npx -y @daghis/teamcity-mcp`
 - With env vars (if not using .env):
   - `claude mcp add [-s user] teamcity -- env TEAMCITY_URL="https://teamcity.example.com" TEAMCITY_TOKEN="tc_<your_token>" MCP_MODE=dev npx -y @daghis/teamcity-mcp`
+- With CLI arguments (recommended for Windows):
+  - `claude mcp add [-s user] teamcity -- npx -y @daghis/teamcity-mcp --url "https://teamcity.example.com" --token "tc_<your_token>" --mode dev`
 - Context usage (Opus 4.1, estimates):
   - Dev (default): ~14k tokens for MCP tools
   - Full (`MCP_MODE=full`): ~26k tokens for MCP tools
 
+### Windows Users
+
+On Windows, Claude Code's MCP configuration may not properly merge environment variables. Use CLI arguments as a workaround:
+
+```json
+{
+  "mcpServers": {
+    "teamcity": {
+      "command": "npx",
+      "args": ["-y", "@daghis/teamcity-mcp", "--url", "https://teamcity.example.com", "--token", "YOUR_TOKEN"]
+    }
+  }
+}
+```
+
+Or use a config file for better security (token not visible in process list):
+
+```json
+{
+  "mcpServers": {
+    "teamcity": {
+      "command": "npx",
+      "args": ["-y", "@daghis/teamcity-mcp", "--config", "C:\\path\\to\\teamcity.env"]
+    }
+  }
+}
+```
+
 ## Configuration
 
 Environment is validated centrally with Zod. Supported variables and defaults:

package/dist/index.js

@@ -221,6 +221,12 @@ var build_status_manager_exports = {};
 __export(build_status_manager_exports, {
   BuildStatusManager: () => BuildStatusManager
 });
+function isAxios404(error3) {
+  return error3 != null && typeof error3 === "object" && "response" in error3 && error3.response?.status === 404;
+}
+function isAxios403(error3) {
+  return error3 != null && typeof error3 === "object" && "response" in error3 && error3.response?.status === 403;
+}
 var BuildStatusManager;
 var init_build_status_manager = __esm({
   "src/teamcity/build-status-manager.ts"() {
@@ -235,7 +241,11 @@ var init_build_status_manager = __esm({
         this.cache = /* @__PURE__ */ new Map();
       }
       /**
-       * Get build status by ID or number
+       * Get build status by ID or number.
+       * Uses 3-step fallback to handle builds in queue and race conditions:
+       * 1. Try builds endpoint
+       * 2. On 404, try build queue (build may be queued)
+       * 3. On 404 again, retry builds endpoint (build may have left queue between checks)
        */
       async getBuildStatus(options) {
         if (!options.buildId && !options.buildNumber) {
@@ -252,41 +262,93 @@ var init_build_status_manager = __esm({
           }
         }
         try {
-          let buildData;
-          if (options.buildId) {
-            const response = await this.client.builds.getBuild(
-              `id:${options.buildId}`,
-              this.getFieldSelection(options)
-            );
-            buildData = response.data;
-          } else {
-            const locator = this.buildLocator(options);
-            const response = await this.client.builds.getBuild(
-              locator,
-              this.getFieldSelection(options)
-            );
-            buildData = response.data;
-          }
-          if (buildData == null) {
-            throw new BuildNotFoundError("Build data is undefined");
-          }
-          const result = this.transformBuildResponse(buildData, options);
-          if (result.state === "finished" || result.state === "canceled") {
-            this.setCachedResult(cacheKey, result);
-          }
-          return result;
+          return await this.getBuildStatusFromBuildsEndpoint(options, cacheKey);
         } catch (error3) {
-          if (error3 != null && typeof error3 === "object" && "response" in error3 && error3.response?.status === 404) {
-            throw new BuildNotFoundError(`Build not found: ${options.buildId ?? options.buildNumber}`);
+          if (!isAxios404(error3) || !options.buildId) {
+            this.handleBuildStatusError(error3, options);
           }
-          if (error3 != null && typeof error3 === "object" && "response" in error3 && error3.response?.status === 403) {
-            throw new BuildAccessDeniedError(
-              `Access denied to build: ${options.buildId ?? options.buildNumber}`
-            );
+        }
+        const buildId = options.buildId;
+        try {
+          return await this.getQueuedBuildStatus(buildId);
+        } catch (queueError) {
+          if (!isAxios404(queueError)) {
+            this.handleBuildStatusError(queueError, options);
           }
-          throw error3;
+        }
+        try {
+          return await this.getBuildStatusFromBuildsEndpoint(options, cacheKey);
+        } catch (error3) {
+          this.handleBuildStatusError(error3, options);
         }
       }
+      /**
+       * Get build status from the builds endpoint
+       */
+      async getBuildStatusFromBuildsEndpoint(options, cacheKey) {
+        let buildData;
+        if (options.buildId) {
+          const response = await this.client.builds.getBuild(
+            `id:${options.buildId}`,
+            this.getFieldSelection(options)
+          );
+          buildData = response.data;
+        } else {
+          const locator = this.buildLocator(options);
+          const response = await this.client.builds.getBuild(locator, this.getFieldSelection(options));
+          buildData = response.data;
+        }
+        if (buildData == null) {
+          throw new BuildNotFoundError("Build data is undefined");
+        }
+        const result = this.transformBuildResponse(buildData, options);
+        if (result.state === "finished" || result.state === "canceled") {
+          this.setCachedResult(cacheKey, result);
+        }
+        return result;
+      }
+      /**
+       * Get build status from the build queue
+       */
+      async getQueuedBuildStatus(buildId) {
+        const response = await this.client.modules.buildQueue.getQueuedBuild(
+          `id:${buildId}`,
+          "id,number,state,status,buildTypeId,branchName,webUrl,queuedDate,waitReason"
+        );
+        const queuedBuild = response.data;
+        if (queuedBuild == null) {
+          throw new BuildNotFoundError("Queued build data is undefined");
+        }
+        const result = {
+          buildId: String(queuedBuild.id),
+          buildNumber: queuedBuild.number,
+          buildTypeId: queuedBuild.buildTypeId,
+          state: "queued",
+          status: void 0,
+          percentageComplete: 0,
+          branchName: queuedBuild.branchName,
+          webUrl: queuedBuild.webUrl,
+          waitReason: queuedBuild.waitReason
+        };
+        if (queuedBuild.queuedDate) {
+          result.queuedDate = this.parseDate(queuedBuild.queuedDate);
+        }
+        return result;
+      }
+      /**
+       * Handle and re-throw build status errors with appropriate error types
+       */
+      handleBuildStatusError(error3, options) {
+        if (isAxios404(error3)) {
+          throw new BuildNotFoundError(`Build not found: ${options.buildId ?? options.buildNumber}`);
+        }
+        if (isAxios403(error3)) {
+          throw new BuildAccessDeniedError(
+            `Access denied to build: ${options.buildId ?? options.buildNumber}`
+          );
+        }
+        throw error3;
+      }
       /**
        * Get build status using custom locator
        */
@@ -679,6 +741,185 @@ async function startServerLifecycle(server, transport) {
   });
 }
 
+// src/utils/cli-args.ts
+var import_fs = require("fs");
+var import_path = require("path");
+function parseCliArgs(argv) {
+  const result = {
+    help: false,
+    version: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === void 0) continue;
+    if (arg === "--help" || arg === "-h") {
+      result.help = true;
+      continue;
+    }
+    if (arg === "--version" || arg === "-v") {
+      result.version = true;
+      continue;
+    }
+    if (arg.startsWith("--url=")) {
+      result.url = arg.slice("--url=".length);
+      continue;
+    }
+    if (arg.startsWith("--token=")) {
+      result.token = arg.slice("--token=".length);
+      continue;
+    }
+    if (arg.startsWith("--mode=")) {
+      const mode = arg.slice("--mode=".length);
+      if (mode === "dev" || mode === "full") {
+        result.mode = mode;
+      } else if (mode.length > 0) {
+        process.stderr.write(
+          `Warning: Invalid mode '${mode}'. Valid values are 'dev' or 'full'.
+`
+        );
+      }
+      continue;
+    }
+    if (arg.startsWith("--config=")) {
+      result.config = arg.slice("--config=".length);
+      continue;
+    }
+    const nextArg = argv[i + 1];
+    if (nextArg !== void 0 && !nextArg.startsWith("-")) {
+      if (arg === "--url") {
+        result.url = nextArg;
+        i++;
+        continue;
+      }
+      if (arg === "--token") {
+        result.token = nextArg;
+        i++;
+        continue;
+      }
+      if (arg === "--mode") {
+        if (nextArg === "dev" || nextArg === "full") {
+          result.mode = nextArg;
+        } else {
+          process.stderr.write(
+            `Warning: Invalid mode '${nextArg}'. Valid values are 'dev' or 'full'.
+`
+          );
+        }
+        i++;
+        continue;
+      }
+      if (arg === "--config") {
+        result.config = nextArg;
+        i++;
+        continue;
+      }
+    }
+  }
+  return result;
+}
+function getVersion() {
+  try {
+    const possiblePaths = [
+      (0, import_path.join)(__dirname, "../package.json"),
+      // bundled: dist/ -> package.json
+      (0, import_path.join)(__dirname, "../../package.json")
+      // source: src/utils/ -> package.json
+    ];
+    for (const packagePath of possiblePaths) {
+      try {
+        const packageJson = JSON.parse((0, import_fs.readFileSync)(packagePath, "utf-8"));
+        if (packageJson.version) {
+          return packageJson.version;
+        }
+      } catch {
+      }
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function getHelpText() {
+  const version = getVersion();
+  return `teamcity-mcp v${version}
+Model Context Protocol server for TeamCity CI/CD integration
+
+USAGE:
+  teamcity-mcp [OPTIONS]
+
+OPTIONS:
+  --url <url>         TeamCity server URL (e.g., https://tc.example.com)
+  --token <token>     TeamCity API token for authentication
+  --mode <dev|full>   Tool exposure mode: dev (limited) or full (all tools)
+  --config <path>     Path to .env format configuration file
+
+  -h, --help          Show this help message
+  -v, --version       Show version number
+
+CONFIGURATION PRECEDENCE (highest to lowest):
+  1. CLI arguments (--url, --token, --mode)
+  2. Config file (--config)
+  3. Environment variables (TEAMCITY_URL, TEAMCITY_TOKEN, MCP_MODE)
+  4. .env file in current directory
+
+SECURITY WARNING:
+  Avoid using --token on the command line when possible. The token value
+  is visible in process lists and may be logged in shell history. For
+  production use, prefer environment variables or a config file with
+  restricted permissions (chmod 600).
+
+EXAMPLES:
+  # Using CLI arguments
+  teamcity-mcp --url https://tc.example.com --token tc_abc123
+
+  # Using a config file
+  teamcity-mcp --config /path/to/teamcity.env
+
+  # Override config file with CLI arg
+  teamcity-mcp --config prod.env --mode dev
+
+CONFIG FILE FORMAT (.env):
+  TEAMCITY_URL=https://tc.example.com
+  TEAMCITY_TOKEN=tc_abc123
+  MCP_MODE=dev
+
+For more information, visit: https://github.com/Daghis/teamcity-mcp
+`;
+}
+
+// src/utils/env-file.ts
+var import_dotenv2 = require("dotenv");
+var import_fs2 = require("fs");
+function loadEnvFile(filepath) {
+  try {
+    const content = (0, import_fs2.readFileSync)(filepath, "utf-8");
+    const values = (0, import_dotenv2.parse)(content);
+    return {
+      success: true,
+      values
+    };
+  } catch (err) {
+    const error3 = err instanceof Error ? err : new Error(String(err));
+    const errno = err;
+    if (errno.code === "ENOENT") {
+      return {
+        success: false,
+        error: `Config file not found: ${filepath}`
+      };
+    }
+    if (errno.code === "EACCES") {
+      return {
+        success: false,
+        error: `Permission denied reading config file: ${filepath}`
+      };
+    }
+    return {
+      success: false,
+      error: `Failed to read config file: ${error3.message}`
+    };
+  }
+}
+
 // src/server.ts
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
 var import_types = require("@modelcontextprotocol/sdk/types.js");
@@ -954,7 +1195,7 @@ function debug2(message, meta) {
 // package.json
 var package_default = {
   name: "@daghis/teamcity-mcp",
-  version: "1.12.0",
+  version: "1.13.0",
   description: "Model Control Protocol server for TeamCity CI/CD integration with AI coding assistants",
   mcpName: "io.github.Daghis/teamcity",
   main: "dist/index.js",
@@ -1040,7 +1281,7 @@ var package_default = {
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/morgan": "^1.9.9",
-    "@types/node": "^24.10.0",
+    "@types/node": "^25.0.2",
     "@typescript-eslint/eslint-plugin": "^8.46.3",
     "@typescript-eslint/parser": "^8.46.3",
     "axios-retry": "^4.5.0",
@@ -38578,6 +38819,7 @@ var TeamCityAPI = class _TeamCityAPI {
 
 // src/tools.ts
 var isReadableStream = (value) => typeof value === "object" && value !== null && typeof value.pipe === "function";
+var isAxios4042 = (error3) => (0, import_axios36.isAxiosError)(error3) && error3.response?.status === 404;
 var sanitizeFileName = (artifactName) => {
   const base = (0, import_node_path.basename)(artifactName || "artifact");
   const safeBase = base.replace(/[^a-zA-Z0-9._-]/g, "_") || "artifact";
@@ -39001,7 +39243,7 @@ var DEV_TOOLS = [
   },
   {
     name: "get_build",
-    description: "Get details of a specific build",
+    description: "Get details of a specific build (works for both queued and running/finished builds)",
     inputSchema: {
       type: "object",
       properties: {
@@ -39016,6 +39258,18 @@ var DEV_TOOLS = [
         schema,
         async (typed) => {
           const adapter = createAdapterFromTeamCityAPI(TeamCityAPI.getInstance());
+          try {
+            const build2 = await adapter.getBuild(typed.buildId);
+            return json(build2);
+          } catch (error3) {
+            if (!isAxios4042(error3)) throw error3;
+          }
+          try {
+            const qb = await adapter.modules.buildQueue.getQueuedBuild(`id:${typed.buildId}`);
+            return json({ ...qb.data, state: "queued" });
+          } catch (queueError) {
+            if (!isAxios4042(queueError)) throw queueError;
+          }
           const build = await adapter.getBuild(typed.buildId);
           return json(build);
         },
@@ -39233,21 +39487,19 @@ var DEV_TOOLS = [
             if (typeof result.queuePosition === "number") {
               enrich.canMoveToTop = result.queuePosition > 1;
             }
-            if (typed.includeQueueTotals) {
-              try {
-                const countResp = await adapter.modules.buildQueue.getAllQueuedBuilds(
-                  void 0,
-                  "count"
-                );
-                enrich.totalQueued = countResp.data.count;
-              } catch {
-              }
+            try {
+              const countResp = await adapter.modules.buildQueue.getAllQueuedBuilds(
+                void 0,
+                "count"
+              );
+              enrich.totalQueued = countResp.data.count;
+            } catch {
             }
-            if (typed.includeQueueReason) {
+            if (!result.waitReason) {
               try {
                 const targetBuildId = typed.buildId ?? result.buildId;
                 if (targetBuildId) {
-                  const qb = await adapter.modules.buildQueue.getQueuedBuild(targetBuildId);
+                  const qb = await adapter.modules.buildQueue.getQueuedBuild(`id:${targetBuildId}`);
                   enrich.waitReason = qb.data.waitReason;
                 }
               } catch {
@@ -43316,7 +43568,39 @@ function createSimpleServer() {
 }
 
 // src/index.ts
+var cliArgs = parseCliArgs(process.argv.slice(2));
+if (cliArgs.help) {
+  process.stderr.write(getHelpText());
+  process.exit(0);
+}
+if (cliArgs.version) {
+  process.stderr.write(`teamcity-mcp v${getVersion()}
+`);
+  process.exit(0);
+}
+if (cliArgs.config) {
+  const configResult = loadEnvFile(cliArgs.config);
+  if (!configResult.success) {
+    process.stderr.write(`Error: ${configResult.error}
+`);
+    process.exit(1);
+  }
+  if (configResult.values) {
+    for (const [key, value] of Object.entries(configResult.values)) {
+      process.env[key] ||= value;
+    }
+  }
+}
 dotenv2.config({ quiet: true });
+if (cliArgs.url) {
+  process.env["TEAMCITY_URL"] = cliArgs.url;
+}
+if (cliArgs.token) {
+  process.env["TEAMCITY_TOKEN"] = cliArgs.token;
+}
+if (cliArgs.mode) {
+  process.env["MCP_MODE"] = cliArgs.mode;
+}
 var activeServer = null;
 var lifecyclePromise = null;
 var shuttingDown = false;
@@ -43355,7 +43639,7 @@ async function main() {
       process.stderr.write(`${e.message}
 `);
       process.stderr.write(
-        "Please set TEAMCITY_URL and TEAMCITY_TOKEN in your environment or .env file.\n"
+        "Please configure TEAMCITY_URL and TEAMCITY_TOKEN via:\n  - CLI arguments: --url <url> --token <token>\n  - Config file: --config <path>\n  - Environment variables\n  - .env file\nRun with --help for more information.\n"
       );
       process.exit(1);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daghis/teamcity-mcp",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Model Control Protocol server for TeamCity CI/CD integration with AI coding assistants",
   "mcpName": "io.github.Daghis/teamcity",
   "main": "dist/index.js",
@@ -86,7 +86,7 @@
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/morgan": "^1.9.9",
-    "@types/node": "^24.10.0",
+    "@types/node": "^25.0.2",
     "@typescript-eslint/eslint-plugin": "^8.46.3",
     "@typescript-eslint/parser": "^8.46.3",
     "axios-retry": "^4.5.0",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://github.com/Daghis/teamcity-mcp",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@daghis/teamcity-mcp",
-      "version": "1.12.0",
+      "version": "1.13.0",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {