@daghis/teamcity-mcp 2.11.0 → 2.12.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.12.1](https://github.com/Daghis/teamcity-mcp/compare/teamcity-mcp-v2.12.0...teamcity-mcp-v2.12.1) (2026-05-12)
+
+
+### Bug Fixes
+
+* **tools:** mark download_* as readOnly and idempotent ([#507](https://github.com/Daghis/teamcity-mcp/issues/507)) ([0a09663](https://github.com/Daghis/teamcity-mcp/commit/0a09663a5ff39e82f9b471e1aa7102ffc4d68163))
+
+## [2.12.0](https://github.com/Daghis/teamcity-mcp/compare/teamcity-mcp-v2.11.0...teamcity-mcp-v2.12.0) (2026-05-03)
+
+
+### Features
+
+* **http:** forward TEAMCITY_HEADER_* env vars on every request ([#492](https://github.com/Daghis/teamcity-mcp/issues/492)) ([c406511](https://github.com/Daghis/teamcity-mcp/commit/c4065111e2e8c6e807ec9a4383cbbe8d280ca00e))
+
 ## [2.11.0](https://github.com/Daghis/teamcity-mcp/compare/teamcity-mcp-v2.10.0...teamcity-mcp-v2.11.0) (2026-05-03)
 
 

package/README.md

@@ -47,6 +47,24 @@ See the [Tools Mode Matrix](docs/mcp-tools-mode-matrix.md) for the complete list
 - Performance-conscious: fast startup with minimal overhead
 - Clean codebase with clear module boundaries
 
+## Choosing between teamcity-mcp and the built-in MCP
+
+TeamCity 2026.1 ships with a built-in MCP endpoint at `<server-url>/app/mcp` exposing three tools: build log retrieval, a generic REST GET, and a build trigger (forced to `personal=true`). It is server-resident, requires no install, and is a sensible default for read-and-rerun workflows.
+
+teamcity-mcp is a different shape: an 87-tool typed surface focused on AI-driven workflows that need writes, multi-server support, or pre-2026.1 compatibility.
+
+| Use case                                                              | Recommendation                                                                             |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Read build logs, trigger builds, simple read flows                    | Built-in (TeamCity 2026.1+) — zero install                                                 |
+| Manage parameters, agents, queue, mutes, build configs, VCS roots     | teamcity-mcp                                                                               |
+| TeamCity server older than 2026.1                                     | teamcity-mcp                                                                               |
+| Multi-server / multi-tenant deployment                                | teamcity-mcp (HTTP transport — [PR #491](https://github.com/Daghis/teamcity-mcp/pull/491)) |
+| Typed tool surface for better agent reliability on chained operations | teamcity-mcp                                                                               |
+
+Both can coexist. The built-in is a good first stop; teamcity-mcp is the power tool for everything the built-in doesn't reach.
+
+For the design reasoning, see [docs/strategy.md](docs/strategy.md) and [docs/non-goals.md](docs/non-goals.md).
+
 ## Installation
 
 ### Prerequisites
@@ -110,7 +128,14 @@ On Windows, Claude Code's MCP configuration [may not properly merge environment
   "mcpServers": {
     "teamcity": {
       "command": "npx",
-      "args": ["-y", "@daghis/teamcity-mcp", "--url", "https://teamcity.example.com", "--token", "YOUR_TOKEN"]
+      "args": [
+        "-y",
+        "@daghis/teamcity-mcp",
+        "--url",
+        "https://teamcity.example.com",
+        "--token",
+        "YOUR_TOKEN"
+      ]
     }
   }
 }
@@ -156,6 +181,14 @@ MCP_MODE=dev
 # TEAMCITY_KEEP_ALIVE=true
 # TEAMCITY_COMPRESSION=true
 
+# Extra headers attached to every TeamCity request — useful when TeamCity
+# sits behind a reverse proxy that gates access on custom headers (e.g.
+# Cloudflare Zero Trust service tokens). One env var per header; the part
+# after `TEAMCITY_HEADER_` is used verbatim as the HTTP header name.
+# Example (note the literal hyphens — most shells need quoting):
+# TEAMCITY_HEADER_CF-Access-Client-Id=<id>
+# TEAMCITY_HEADER_CF-Access-Client-Secret=<secret>
+
 # Retry
 # TEAMCITY_RETRY_ENABLED=true
 # TEAMCITY_MAX_RETRIES=3
@@ -351,4 +384,4 @@ This repository has GitHub secret scanning and push protection enabled. See [SEC
 
 ---
 
-Built with ❤️ for developers who love efficient CI/CD workflows
+Built with ❤️ for developers who love efficient CI/CD workflows

package/dist/index.js

@@ -691,6 +691,17 @@ function setServerInstance(server) {
 function getServerInstance() {
   return serverInstance;
 }
+var HEADER_ENV_PREFIX = "TEAMCITY_HEADER_";
+function getTeamCityExtraHeaders() {
+  const headers = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.startsWith(HEADER_ENV_PREFIX) || value === void 0) continue;
+    const headerName = key.slice(HEADER_ENV_PREFIX.length);
+    if (headerName === "") continue;
+    headers[headerName] = value;
+  }
+  return Object.keys(headers).length > 0 ? headers : void 0;
+}
 function getTeamCityUrl() {
   const config2 = getConfig();
   if (!config2.teamcity?.url || config2.teamcity.url.length === 0) {
@@ -1205,7 +1216,7 @@ function debug2(message, meta) {
 // package.json
 var package_default = {
   name: "@daghis/teamcity-mcp",
-  version: "2.11.0",
+  version: "2.12.1",
   description: "Model Control Protocol server for TeamCity CI/CD integration with AI coding assistants",
   mcpName: "io.github.Daghis/teamcity",
   main: "dist/index.js",
@@ -1269,7 +1280,7 @@ var package_default = {
     url: "https://github.com/Daghis/teamcity-mcp/issues"
   },
   dependencies: {
-    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     axios: "^1.15.0",
     "axios-retry": "^4.5.0",
     dotenv: "17.4.2",
@@ -38459,6 +38470,7 @@ var TeamCityAPI = class _TeamCityAPI {
       baseURL: basePath,
       timeout,
       headers: {
+        ...config2.extraHeaders ?? {},
         Authorization: `Bearer ${config2.token}`,
         Accept: "application/json",
         "Content-Type": "application/json"
@@ -38487,6 +38499,7 @@ var TeamCityAPI = class _TeamCityAPI {
       baseOptions: {
         timeout,
         headers: {
+          ...config2.extraHeaders ?? {},
           Authorization: `Bearer ${config2.token}`,
           Accept: "application/json"
         }
@@ -38569,7 +38582,8 @@ var TeamCityAPI = class _TeamCityAPI {
     if (this.instance == null) {
       const envConfig = this.normalizeConfig({
         baseUrl: getTeamCityUrl(),
-        token: getTeamCityToken()
+        token: getTeamCityToken(),
+        extraHeaders: getTeamCityExtraHeaders()
       });
       this.instance = new _TeamCityAPI(envConfig);
       this.instanceConfig = envConfig;
@@ -38800,15 +38814,34 @@ var TeamCityAPI = class _TeamCityAPI {
     return {
       baseUrl: config2.baseUrl.replace(/\/$/, ""),
       token: config2.token,
-      timeout: config2.timeout
+      timeout: config2.timeout,
+      extraHeaders: normalizeExtraHeaders(config2.extraHeaders)
     };
   }
   static configsEqual(a, b) {
     if (a == null || b == null) {
       return false;
     }
-    return a.baseUrl === b.baseUrl && a.token === b.token && a.timeout === b.timeout;
+    return a.baseUrl === b.baseUrl && a.token === b.token && a.timeout === b.timeout && extraHeadersEqual(a.extraHeaders, b.extraHeaders);
+  }
+};
+var normalizeExtraHeaders = (headers) => {
+  if (headers == null) {
+    return void 0;
   }
+  const entries = Object.entries(headers);
+  if (entries.length === 0) {
+    return void 0;
+  }
+  return Object.fromEntries(entries.sort(([a], [b]) => a.localeCompare(b)));
+};
+var extraHeadersEqual = (a, b) => {
+  if (a === b) return true;
+  if (a == null || b == null) return a == null && b == null;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((key) => a[key] === b[key]);
 };
 
 // src/tools.ts
@@ -41511,9 +41544,9 @@ var DEV_TOOLS = [
   {
     name: "download_build_artifact",
     annotations: {
-      readOnlyHint: false,
+      readOnlyHint: true,
       destructiveHint: false,
-      idempotentHint: false,
+      idempotentHint: true,
       openWorldHint: true
     },
     description: "Download a single build artifact, with base64, text, or streaming output. Returns the artifact bytes or stream metadata; returns 404 if the build or path is unknown.",
@@ -41579,9 +41612,9 @@ var DEV_TOOLS = [
   {
     name: "download_build_artifacts",
     annotations: {
-      readOnlyHint: false,
+      readOnlyHint: true,
       destructiveHint: false,
-      idempotentHint: false,
+      idempotentHint: true,
       openWorldHint: true
     },
     description: "Download multiple build artifacts, with base64, text, or streaming output. Returns per-artifact payloads or stream metadata; returns 404 if the build or any path is unknown.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daghis/teamcity-mcp",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "description": "Model Control Protocol server for TeamCity CI/CD integration with AI coding assistants",
   "mcpName": "io.github.Daghis/teamcity",
   "main": "dist/index.js",
@@ -64,7 +64,7 @@
     "url": "https://github.com/Daghis/teamcity-mcp/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "axios": "^1.15.0",
     "axios-retry": "^4.5.0",
     "dotenv": "17.4.2",

package/server.json

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