@daghis/teamcity-mcp 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.5.0](https://github.com/Daghis/teamcity-mcp/compare/v1.4.0...v1.5.0) (2025-09-20)
+
+
+### Features
+
+* **teamcity:** add streaming artifact downloads ([#161](https://github.com/Daghis/teamcity-mcp/issues/161)) ([b50b773](https://github.com/Daghis/teamcity-mcp/commit/b50b773ebee6f5cc85f4c53c98fef525e7098fe9)), closes [#151](https://github.com/Daghis/teamcity-mcp/issues/151)
+
 ## [1.4.0](https://github.com/Daghis/teamcity-mcp/compare/v1.3.5...v1.4.0) (2025-09-20)
 
 

package/dist/index.js

@@ -758,9 +758,9 @@ var TeamCityLogger = class _TeamCityLogger {
    */
   ensureLogDirectory(directory) {
     try {
-      const fs = require("fs");
-      if (fs.existsSync(directory) === false) {
-        fs.mkdirSync(directory, { recursive: true });
+      const fs2 = require("fs");
+      if (fs2.existsSync(directory) === false) {
+        fs2.mkdirSync(directory, { recursive: true });
       }
     } catch (error2) {
       this.winston?.warn?.("Failed to create log directory, using current directory", { error: error2 });
@@ -921,6 +921,11 @@ function debug(message, meta) {
 }
 
 // src/tools.ts
+var import_node_crypto = require("node:crypto");
+var import_node_fs = require("node:fs");
+var import_node_os = require("node:os");
+var import_node_path = require("node:path");
+var import_promises = require("node:stream/promises");
 var import_axios35 = require("axios");
 var import_zod4 = require("zod");
 
@@ -931,6 +936,318 @@ var ResolutionTypeEnum = {
   AtTime: "atTime"
 };
 
+// src/teamcity/utils/build-locator.ts
+var toBuildLocator = (buildId) => buildId.includes(":") ? buildId : `id:${buildId}`;
+
+// src/teamcity/artifact-manager.ts
+var ArtifactManager = class _ArtifactManager {
+  client;
+  cache = /* @__PURE__ */ new Map();
+  static cacheTtlMs = 6e4;
+  // 1 minute
+  static defaultLimit = 100;
+  static maxLimit = 1e3;
+  constructor(client) {
+    this.client = client;
+  }
+  getBaseUrl() {
+    const baseUrl = this.client.getApiConfig().baseUrl;
+    return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  }
+  /**
+   * List artifacts for a build
+   */
+  async listArtifacts(buildId, options = {}) {
+    const cacheKey = this.getCacheKey(buildId, options);
+    if (!options.forceRefresh) {
+      const cached = this.getFromCache(cacheKey);
+      if (cached) {
+        return cached;
+      }
+    }
+    try {
+      const buildLocator = toBuildLocator(buildId);
+      const response = await this.client.modules.builds.getFilesListOfBuild(
+        buildLocator,
+        void 0,
+        void 0,
+        "file(name,fullName,size,modificationTime,href,children(file(name,fullName,size,modificationTime,href)))"
+      );
+      const baseUrl = this.getBaseUrl();
+      let artifacts = this.parseArtifacts(
+        response.data ?? {},
+        buildId,
+        options.includeNested,
+        baseUrl
+      );
+      artifacts = this.applyFilters(artifacts, options);
+      if (options.limit ?? options.offset) {
+        artifacts = this.paginate(
+          artifacts,
+          options.offset ?? 0,
+          options.limit ?? _ArtifactManager.defaultLimit
+        );
+      }
+      this.cacheResult(cacheKey, artifacts);
+      return artifacts;
+    } catch (error2) {
+      const err = error2;
+      if (err.response?.status === 401) {
+        throw new Error("Authentication failed: Invalid TeamCity token");
+      }
+      if (err.response?.status === 404) {
+        throw new Error(`Build not found: ${buildId}`);
+      }
+      const errMsg = err.message ?? String(error2);
+      throw new Error(`Failed to fetch artifacts: ${errMsg}`);
+    }
+  }
+  /**
+   * Download a specific artifact
+   */
+  async downloadArtifact(buildId, artifactPath, options = {}) {
+    const artifacts = await this.listArtifacts(buildId);
+    const artifact = artifacts.find((a) => a.path === artifactPath || a.name === artifactPath);
+    if (!artifact) {
+      throw new Error(`Artifact not found: ${artifactPath}`);
+    }
+    if (options.maxSize && artifact.size > options.maxSize) {
+      throw new Error(
+        `Artifact size exceeds maximum allowed size: ${artifact.size} > ${options.maxSize}`
+      );
+    }
+    try {
+      const encoding = options.encoding ?? "buffer";
+      const normalizedPath = artifact.path.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+      const buildLocator = toBuildLocator(buildId);
+      const artifactRequestPath = `content/${normalizedPath}`;
+      if (encoding === "text") {
+        const response2 = await this.client.modules.builds.downloadFileOfBuild(
+          artifactRequestPath,
+          buildLocator,
+          void 0,
+          void 0,
+          { responseType: "text" }
+        );
+        const axiosResponse2 = response2;
+        const { data, headers } = axiosResponse2;
+        if (typeof data !== "string") {
+          throw new Error("Artifact download returned a non-text payload when text was expected");
+        }
+        const mimeType = typeof headers?.["content-type"] === "string" ? headers["content-type"] : void 0;
+        return {
+          name: artifact.name,
+          path: artifact.path,
+          size: artifact.size,
+          content: data,
+          mimeType
+        };
+      }
+      if (encoding === "stream") {
+        const response2 = await this.client.modules.builds.downloadFileOfBuild(
+          artifactRequestPath,
+          buildLocator,
+          void 0,
+          void 0,
+          { responseType: "stream" }
+        );
+        const axiosResponse2 = response2;
+        const stream = axiosResponse2.data;
+        if (!this.isReadableStream(stream)) {
+          throw new Error(
+            "Artifact download returned a non-stream payload when stream was requested"
+          );
+        }
+        const mimeType = typeof axiosResponse2.headers?.["content-type"] === "string" ? axiosResponse2.headers["content-type"] : void 0;
+        return {
+          name: artifact.name,
+          path: artifact.path,
+          size: artifact.size,
+          content: stream,
+          mimeType
+        };
+      }
+      const response = await this.client.modules.builds.downloadFileOfBuild(
+        artifactRequestPath,
+        buildLocator,
+        void 0,
+        void 0,
+        { responseType: "arraybuffer" }
+      );
+      const axiosResponse = response;
+      const buffer = this.ensureBinaryBuffer(axiosResponse.data);
+      let content;
+      if (encoding === "base64") {
+        content = buffer.toString("base64");
+      } else {
+        content = buffer;
+      }
+      return {
+        name: artifact.name,
+        path: artifact.path,
+        size: artifact.size,
+        content,
+        mimeType: typeof axiosResponse.headers?.["content-type"] === "string" ? axiosResponse.headers["content-type"] : void 0
+      };
+    } catch (error2) {
+      const errMsg = error2 instanceof Error ? error2.message : "Unknown error";
+      throw new Error(`Failed to download artifact: ${errMsg}`);
+    }
+  }
+  /**
+   * Download multiple artifacts
+   */
+  async downloadMultipleArtifacts(buildId, artifactPaths, options = {}) {
+    if (options.encoding === "stream") {
+      throw new Error("Streaming downloads are only supported when requesting a single artifact");
+    }
+    const downloadOptions = { encoding: "base64", ...options };
+    const results = await Promise.allSettled(
+      artifactPaths.map((path) => this.downloadArtifact(buildId, path, downloadOptions))
+    );
+    return results.map((result, index) => {
+      if (result.status === "fulfilled") {
+        return result.value;
+      } else {
+        const fallbackName = artifactPaths[index] ?? "unknown";
+        return {
+          name: fallbackName,
+          path: fallbackName,
+          size: 0,
+          error: result.reason.message
+        };
+      }
+    });
+  }
+  /**
+   * Parse artifacts from API response
+   */
+  parseArtifacts(data, buildId, includeNested, baseUrl) {
+    const artifacts = [];
+    const files = data.file ?? [];
+    for (const file of files) {
+      if (file.children && includeNested) {
+        const nested = this.parseArtifacts(file.children, buildId, includeNested, baseUrl);
+        artifacts.push(...nested);
+      } else if (!file.children) {
+        artifacts.push({
+          name: file.name ?? "",
+          path: file.fullName ?? file.name ?? "",
+          size: file.size ?? 0,
+          modificationTime: file.modificationTime ?? "",
+          downloadUrl: `${baseUrl}/app/rest/builds/id:${buildId}/artifacts/content/${file.fullName ?? file.name ?? ""}`,
+          isDirectory: false
+        });
+      }
+    }
+    return artifacts;
+  }
+  ensureBinaryBuffer(payload) {
+    if (Buffer.isBuffer(payload)) {
+      return payload;
+    }
+    if (payload instanceof ArrayBuffer) {
+      return Buffer.from(payload);
+    }
+    throw new Error("Artifact download returned unexpected binary payload type");
+  }
+  isReadableStream(value) {
+    if (value == null || typeof value !== "object") {
+      return false;
+    }
+    const candidate = value;
+    return typeof candidate.pipe === "function";
+  }
+  /**
+   * Apply filters to artifacts
+   */
+  applyFilters(artifacts, options) {
+    let filtered = artifacts;
+    if (options.nameFilter) {
+      const regex = this.globToRegex(options.nameFilter);
+      filtered = filtered.filter((a) => regex.test(a.name));
+    }
+    if (options.pathFilter) {
+      const regex = this.globToRegex(options.pathFilter);
+      filtered = filtered.filter((a) => regex.test(a.path));
+    }
+    if (options.extension) {
+      const ext = options.extension.startsWith(".") ? options.extension : `.${options.extension}`;
+      filtered = filtered.filter((a) => a.name.endsWith(ext));
+    }
+    if (options.minSize !== void 0) {
+      const minSize = options.minSize;
+      filtered = filtered.filter((a) => a.size >= minSize);
+    }
+    if (options.maxSize !== void 0) {
+      const maxSize = options.maxSize;
+      filtered = filtered.filter((a) => a.size <= maxSize);
+    }
+    return filtered;
+  }
+  /**
+   * Convert glob pattern to regex
+   */
+  globToRegex(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+  }
+  /**
+   * Paginate results
+   */
+  paginate(artifacts, offset, limit) {
+    const effectiveLimit = Math.min(limit, _ArtifactManager.maxLimit);
+    return artifacts.slice(offset, offset + effectiveLimit);
+  }
+  /**
+   * Generate cache key
+   */
+  getCacheKey(buildId, options) {
+    const { forceRefresh: _forceRefresh, ...cacheOptions } = options;
+    return `${buildId}:${JSON.stringify(cacheOptions)}`;
+  }
+  /**
+   * Get from cache if valid
+   */
+  getFromCache(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      return null;
+    }
+    const age = Date.now() - entry.timestamp;
+    if (age > _ArtifactManager.cacheTtlMs) {
+      this.cache.delete(key);
+      return null;
+    }
+    return entry.artifacts;
+  }
+  /**
+   * Cache artifacts
+   */
+  cacheResult(key, artifacts) {
+    this.cache.set(key, {
+      artifacts,
+      timestamp: Date.now()
+    });
+    this.cleanCache();
+  }
+  /**
+   * Remove expired cache entries
+   */
+  cleanCache() {
+    const now = Date.now();
+    const expired = [];
+    for (const [key, entry] of this.cache.entries()) {
+      if (now - entry.timestamp > _ArtifactManager.cacheTtlMs) {
+        expired.push(key);
+      }
+    }
+    for (const key of expired) {
+      this.cache.delete(key);
+    }
+  }
+};
+
 // src/teamcity/build-configuration-update-manager.ts
 var BuildConfigurationUpdateManager = class {
   client;
@@ -1317,9 +1634,6 @@ var BuildConfigurationUpdateManager = class {
   }
 };
 
-// src/teamcity/utils/build-locator.ts
-var toBuildLocator = (buildId) => buildId.includes(":") ? buildId : `id:${buildId}`;
-
 // src/teamcity/build-results-manager.ts
 var BuildResultsManager = class _BuildResultsManager {
   client;
@@ -1802,7 +2116,7 @@ function createAdapterFromTeamCityAPI(api, options = {}) {
     listTestFailures: (buildId) => api.listTestFailures(buildId),
     builds: buildApi,
     listBuildArtifacts: (buildId, options2) => api.listBuildArtifacts(buildId, options2),
-    downloadArtifactContent: (buildId, artifactPath) => api.downloadBuildArtifact(buildId, artifactPath),
+    downloadArtifactContent: (buildId, artifactPath, requestOptions) => api.downloadBuildArtifact(buildId, artifactPath, requestOptions),
     getBuildStatistics: (buildId, fields) => api.getBuildStatistics(buildId, fields),
     listChangesForBuild: (buildId, fields) => api.listChangesForBuild(buildId, fields),
     listSnapshotDependencies: (buildId) => api.listSnapshotDependencies(buildId),
@@ -36371,13 +36685,15 @@ var TeamCityAPI = class _TeamCityAPI {
       options?.logBuildUsage
     );
   }
-  async downloadBuildArtifact(buildId, artifactPath) {
+  async downloadBuildArtifact(buildId, artifactPath, options) {
     const normalizedPath = artifactPath.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+    const requestOptions = {
+      ...options ?? {},
+      responseType: options?.responseType ?? "arraybuffer"
+    };
     return this.axiosInstance.get(
       `/app/rest/builds/id:${buildId}/artifacts/content/${normalizedPath}`,
-      {
-        responseType: "arraybuffer"
-      }
+      requestOptions
     );
   }
   async getBuildStatistics(buildId, fields) {
@@ -37972,6 +38288,95 @@ var DEV_TOOLS = [
       );
     }
   },
+  {
+    name: "download_build_artifact",
+    description: "Download a single artifact with optional streaming output",
+    inputSchema: {
+      type: "object",
+      properties: {
+        buildId: { type: "string", description: "Build ID" },
+        artifactPath: { type: "string", description: "Artifact path or name" },
+        encoding: {
+          type: "string",
+          description: "Response encoding: 'base64' (default), 'text', or 'stream'",
+          enum: ["base64", "text", "stream"],
+          default: "base64"
+        },
+        maxSize: {
+          type: "number",
+          description: "Maximum artifact size (bytes) allowed before aborting"
+        },
+        outputPath: {
+          type: "string",
+          description: "Optional absolute path to write streamed content; defaults to a temp file when streaming"
+        }
+      },
+      required: ["buildId", "artifactPath"]
+    },
+    handler: async (args) => {
+      const schema = import_zod4.z.object({
+        buildId: import_zod4.z.string().min(1),
+        artifactPath: import_zod4.z.string().min(1),
+        encoding: import_zod4.z.enum(["base64", "text", "stream"]).default("base64"),
+        maxSize: import_zod4.z.number().int().positive().optional(),
+        outputPath: import_zod4.z.string().min(1).optional()
+      });
+      const isReadableStream = (value) => typeof value === "object" && value !== null && typeof value.pipe === "function";
+      const toTempFilePath = (artifactName) => {
+        const base = (0, import_node_path.basename)(artifactName || "artifact");
+        const safeStem = base.replace(/[^a-zA-Z0-9._-]/g, "_") || "artifact";
+        const ext = (0, import_node_path.extname)(safeStem);
+        const stemWithoutExt = ext ? safeStem.slice(0, -ext.length) : safeStem;
+        const finalStem = stemWithoutExt || "artifact";
+        const fileName = `${finalStem}-${(0, import_node_crypto.randomUUID)()}${ext}`;
+        return (0, import_node_path.join)((0, import_node_os.tmpdir)(), fileName);
+      };
+      return runTool(
+        "download_build_artifact",
+        schema,
+        async (typed) => {
+          const adapter = createAdapterFromTeamCityAPI(TeamCityAPI.getInstance());
+          const manager = new ArtifactManager(adapter);
+          const artifact = await manager.downloadArtifact(typed.buildId, typed.artifactPath, {
+            encoding: typed.encoding,
+            maxSize: typed.maxSize
+          });
+          if (typed.encoding === "stream") {
+            const stream = artifact.content;
+            if (!isReadableStream(stream)) {
+              throw new Error("Streaming download did not return a readable stream");
+            }
+            const targetPath = typed.outputPath ?? toTempFilePath(artifact.name);
+            await import_node_fs.promises.mkdir((0, import_node_path.dirname)(targetPath), { recursive: true });
+            await (0, import_promises.pipeline)(stream, (0, import_node_fs.createWriteStream)(targetPath));
+            const stats = await import_node_fs.promises.stat(targetPath);
+            return json({
+              name: artifact.name,
+              path: artifact.path,
+              size: artifact.size,
+              mimeType: artifact.mimeType,
+              encoding: "stream",
+              outputPath: targetPath,
+              bytesWritten: stats.size
+            });
+          }
+          const payloadContent = artifact.content;
+          if (typeof payloadContent !== "string") {
+            throw new Error(`Expected ${typed.encoding} artifact content as string`);
+          }
+          return json({
+            name: artifact.name,
+            path: artifact.path,
+            size: artifact.size,
+            mimeType: artifact.mimeType,
+            encoding: typed.encoding,
+            content: payloadContent
+          });
+        },
+        args
+      );
+    }
+  },
   {
     name: "get_test_details",
     description: "Get detailed information about test failures",