@daghis/teamcity-mcp 0.1.2

package/docs/mcp-tools-mode-matrix.md

@@ -0,0 +1,68 @@
+# TeamCity MCP — Tools Mode Matrix
+
+Legend: Dev = developer-focused (PRs/builds/logs/trigger, read-only config). Full = all tools.
+
+| Category | Tool | Dev | Full |
+|---|---|---|---|
+| Basic | `ping` | Yes | Yes |
+| Projects | `list_projects` | Yes | Yes |
+| Projects | `get_project` | Yes | Yes |
+| Projects | `list_project_hierarchy` | Yes | Yes |
+| Projects | `create_project` | No | Yes |
+| Projects | `update_project_settings` | No | Yes |
+| Projects | `delete_project` | No | Yes |
+| Builds | `list_builds` | Yes | Yes |
+| Builds | `get_build` | Yes | Yes |
+| Builds | `get_build_status` | Yes | Yes |
+| Builds | `fetch_build_log` | Yes | Yes |
+| Builds | `get_build_results` | Yes | Yes |
+| Builds | `analyze_build_problems` | Yes | Yes |
+| Builds | `trigger_build` | Yes | Yes |
+| Builds | `cancel_queued_build` | Yes | Yes |
+| Build Configs | `list_build_configs` | Yes | Yes |
+| Build Configs | `get_build_config` | Yes | Yes |
+| Build Configs | `create_build_config` | No | Yes |
+| Build Configs | `clone_build_config` | No | Yes |
+| Build Configs | `update_build_config` | No | Yes |
+| Build Configs | `set_build_configs_paused` | No | Yes |
+| Steps & Triggers | `manage_build_steps` | No | Yes |
+| Steps & Triggers | `manage_build_triggers` | No | Yes |
+| Parameters | `list_parameters` | Yes | Yes |
+| Parameters | `add_parameter` | No | Yes |
+| Parameters | `update_parameter` | No | Yes |
+| Parameters | `delete_parameter` | No | Yes |
+| VCS | `list_vcs_roots` | Yes | Yes |
+| VCS | `get_vcs_root` | Yes | Yes |
+| VCS | `create_vcs_root` | No | Yes |
+| VCS | `add_vcs_root_to_build` | No | Yes |
+| Agents | `list_agents` | Yes | Yes |
+| Agents | `list_agent_pools` | Yes | Yes |
+| Agents | `authorize_agent` | No | Yes |
+| Agents | `assign_agent_to_pool` | No | Yes |
+| Agents | `get_agent_enabled_info` | Yes | Yes |
+| Agents | `set_agent_enabled` | No | Yes |
+| Agents | `bulk_set_agents_enabled` | No | Yes |
+| Compatibility | `get_compatible_agents_for_build_type` | Yes | Yes |
+| Compatibility | `count_compatible_agents_for_build_type` | Yes | Yes |
+| Compatibility | `get_compatible_agents_for_queued_build` | Yes | Yes |
+| Compatibility | `get_compatible_build_types_for_agent` | Yes | Yes |
+| Compatibility | `get_incompatible_build_types_for_agent` | Yes | Yes |
+| Queue | `list_queued_builds` | Yes | Yes |
+| Queue | `move_queued_build_to_top` | No | Yes |
+| Queue | `reorder_queued_builds` | No | Yes |
+| Queue | `cancel_queued_builds_for_build_type` | No | Yes |
+| Queue | `cancel_queued_builds_by_locator` | No | Yes |
+| Queue | `pause_queue_for_pool` | No | Yes |
+| Queue | `resume_queue_for_pool` | No | Yes |
+| Server | `get_server_info` | Yes | Yes |
+| Server | `check_teamcity_connection` | Yes | Yes |
+| Server | `check_availability_guard` | Yes | Yes |
+| Server | `get_server_metrics` | No | Yes |
+| Server | `list_server_health_items` | No | Yes |
+| Server | `get_server_health_item` | No | Yes |
+| Tests | `list_test_failures` | Yes | Yes |
+| Tests | `get_test_details` | Yes | Yes |
+| Branches | `list_branches` | Yes | Yes |
+
+Notes
+- Dev mode excludes TeamCity administration and agent/pool management tools to reduce surface and context size, while keeping all read operations and developer workflows (including `trigger_build`).

package/docs/mcp-tools-reference.md

@@ -0,0 +1,203 @@
+# TeamCity MCP Server — Tool Reference
+
+This document lists all Model Context Protocol (MCP) tools exposed by the TeamCity MCP server in this repository, including arguments, required fields, defaults, and mode availability.
+
+- Server name: `teamcity-mcp`
+- Modes: `dev` (default) and `full` via env `MCP_MODE`
+  - `dev` mode: read‑only and safe operations
+  - `full` mode: includes write/modify operations in addition to all `dev` tools
+- Capabilities: tools only (no prompts/resources)
+
+## Conventions
+- Many list APIs support pagination: `pageSize`, `maxPages`, and `all` (fetches pages until `maxPages`). Defaults: `pageSize` ≈ 100 when not specified.
+- Where supported by TeamCity, list APIs accept `locator` (server-side filtering) and `fields` (server-side projection) to minimize payloads.
+- Unless stated, tools are available in both `dev` and `full` modes.
+- Types: strings unless noted; booleans are explicitly typed; integers are bounded in validations.
+
+## Tools
+
+### Basic
+- `ping` — Test MCP server connectivity
+  - Args: `message?: string`
+  - Mode: dev, full
+
+### Projects
+- `list_projects` — List TeamCity projects (paginated)
+  - Args: `locator?: string`, `parentProjectId?: string`, `pageSize?: number`, `maxPages?: number`, `all?: boolean`, `fields?: string`
+- `get_project` — Get project details
+  - Args: `projectId: string`
+- `create_project` — Create a new project
+  - Args: `name: string`, `id: string`, `parentProjectId?: string` (defaults `_Root`), `description?: string`
+  - Mode: full
+- `delete_project` — Delete a project
+  - Args: `projectId: string`
+  - Mode: full
+- `update_project_settings` — Update project fields
+  - Args: `projectId: string`, `name?: string`, `description?: string`, `archived?: boolean`
+  - Mode: full
+- `list_project_hierarchy` — Parent/child tree (limited depth)
+  - Args: `rootProjectId?: string` (defaults `_Root`)
+
+### Builds
+- `list_builds` — List builds (paginated)
+  - Args: `locator?: string`, `projectId?: string`, `buildTypeId?: string`, `status?: 'SUCCESS'|'FAILURE'|'ERROR'`, `pageSize?: number`, `maxPages?: number`, `all?: boolean`, `fields?: string`, `count?: number` (deprecated)
+- `get_build` — Get build details
+  - Args: `buildId: string`
+- `trigger_build` — Trigger a build
+  - Args: `buildTypeId: string`, `branchName?: string`, `comment?: string`
+- `cancel_queued_build` — Cancel a queued build
+  - Args: `buildId: string`
+  - Mode: full
+- `get_build_status` — Build status with optional queue context
+  - Args: `buildId: string`, `includeTests?: boolean`, `includeProblems?: boolean`, `includeQueueTotals?: boolean` (adds totalQueued; extra call when queued), `includeQueueReason?: boolean` (adds waitReason; extra call when queued)
+- `fetch_build_log` — Build log by lines (pagination/tail)
+  - Args: `buildId?: string`, `buildNumber?: string|number` (with optional `buildTypeId` to disambiguate), `buildTypeId?: string`, `page?: number`, `pageSize?: number`, `startLine?: number`, `lineCount?: number`, `tail?: boolean`
+- `get_build_results` — Rich results (tests, artifacts, stats, changes, deps)
+  - Args: `buildId: string`, `includeArtifacts?: boolean`, `includeStatistics?: boolean`, `includeChanges?: boolean`, `includeDependencies?: boolean`, `artifactFilter?: string`, `maxArtifactSize?: number`
+- `analyze_build_problems` — Problems + failing tests summary
+  - Args: `buildId: string`
+
+### Build Configurations
+- `list_build_configs` — List build configurations (paginated)
+  - Args: `locator?: string`, `projectId?: string`, `pageSize?: number`, `maxPages?: number`, `all?: boolean`, `fields?: string`
+- `get_build_config` — Get build configuration details
+  - Args: `buildTypeId: string`
+- `create_build_config` — Create a build configuration
+  - Args: `projectId: string`, `name: string`, `id: string`, `description?: string`
+  - Mode: full
+- `clone_build_config` — Clone a build configuration
+  - Args: `sourceBuildTypeId: string`, `name: string`, `id: string`, `projectId?: string`
+  - Mode: full
+- `update_build_config` — Update build configuration fields
+  - Args: `buildTypeId: string`, `name?: string`, `description?: string`, `paused?: boolean`, `artifactRules?: string`
+  - Mode: full
+- `set_build_configs_paused` — Batch pause/unpause build configurations; optionally cancel queued
+  - Args: `buildTypeIds: string[]`, `paused: boolean`, `cancelQueued?: boolean`
+  - Mode: full
+
+### Build Steps & Triggers
+- `manage_build_steps` — Add/update/delete build steps
+  - Args: `buildTypeId: string`, `action: 'add'|'update'|'delete'`, `stepId?: string` (update/delete), `name?: string` (add), `type?: string` (add), `properties?: Record<string, unknown>`
+  - Mode: full
+- `manage_build_triggers` — Add/delete triggers
+  - Args: `buildTypeId: string`, `action: 'add'|'delete'`, `triggerId?: string` (delete), `type?: string` (add), `properties?: Record<string, unknown>`
+  - Mode: full
+
+### Parameters
+- `list_parameters` — List build configuration parameters
+  - Args: `buildTypeId: string`
+- `add_parameter` — Add a parameter
+  - Args: `buildTypeId: string`, `name: string`, `value: string`
+  - Mode: full
+- `update_parameter` — Update a parameter
+  - Args: `buildTypeId: string`, `name: string`, `value: string`
+  - Mode: full
+- `delete_parameter` — Delete a parameter
+  - Args: `buildTypeId: string`, `name: string`
+  - Mode: full
+
+### Version Control (VCS)
+- `list_vcs_roots` — List VCS roots (paginated)
+  - Args: `projectId?: string`, `pageSize?: number`, `maxPages?: number`, `all?: boolean`, `fields?: string`
+- `get_vcs_root` — Get VCS root details + properties
+  - Args: `id: string`
+- `create_vcs_root` — Create a VCS root
+  - Args: `projectId: string`, `name: string`, `id: string`, `vcsName: string`, `url: string`, `branch?: string` (default `refs/heads/master`)
+  - Mode: full
+- `add_vcs_root_to_build` — Attach VCS root to a build config
+  - Args: `buildTypeId: string`, `vcsRootId: string`, `checkoutRules?: string`
+  - Mode: full
+
+### Agents
+- `list_agents` — List build agents (paginated)
+  - Args: `locator?: string`, `pageSize?: number`, `maxPages?: number`, `all?: boolean`, `fields?: string`
+- `list_agent_pools` — List agent pools (paginated)
+  - Args: `pageSize?: number`, `maxPages?: number`, `all?: boolean`, `fields?: string`
+- `authorize_agent` — Authorize/unauthorize an agent
+  - Args: `agentId: string`, `authorize: boolean`
+  - Mode: full
+- `assign_agent_to_pool` — Assign an agent to a pool
+  - Args: `agentId: string`, `poolId: string` (parsed as integer)
+  - Mode: full
+- `get_incompatible_build_types_for_agent` — Build types incompatible with an agent
+  - Args: `agentId: string`
+  - Mode: dev, full
+- `get_compatible_agents_for_build_type` — Agents compatible with a build type
+  - Args: `buildTypeId: string`, `includeDisabled?: boolean`
+  - Mode: dev, full
+- `count_compatible_agents_for_build_type` — Count of compatible agents (optionally only enabled)
+  - Args: `buildTypeId: string`, `includeDisabled?: boolean`
+  - Mode: dev, full
+- `get_compatible_agents_for_queued_build` — Agents compatible with a queued/running build
+  - Args: `buildId: string`, `includeDisabled?: boolean`
+  - Mode: dev, full
+
+### Tests
+- `list_test_failures` — List failing tests for a build (paginated)
+  - Args: `buildId: string`, `pageSize?: number`, `maxPages?: number`, `all?: boolean`, `fields?: string`
+- `get_test_details` — Detailed test occurrence data
+  - Args: `buildId: string`, `testNameId?: string`
+
+### Branches
+- `list_branches` — Unique branches across recent builds
+  - Args: `projectId?: string`, `buildTypeId?: string`
+  - Notes: one of `projectId` or `buildTypeId` is required
+
+## Environment & Setup
+- Configure via `.env` (copy from `.env.example`): `TEAMCITY_URL`, `TEAMCITY_TOKEN`, `MCP_MODE`
+- Switch tool surface by setting `MCP_MODE=dev|full`
+- Server reports tools via MCP `tools/list` and executes via `tools/call`
+### Queue
+- `list_queued_builds` — List queued builds (paginated)
+  - Args: `locator?: string`, `pageSize?: number`, `maxPages?: number`, `all?: boolean`, `fields?: string`
+  
+### Queue Maintenance (full)
+- `move_queued_build_to_top` — Move a queued build to the top
+  - Args: `buildId: string`
+- `reorder_queued_builds` — Reorder queued builds by explicit sequence
+  - Args: `buildIds: string[]`
+- `cancel_queued_builds_for_build_type` — Cancel all queued builds for a build type
+  - Args: `buildTypeId: string`
+- `cancel_queued_builds_by_locator` — Cancel queued builds by queue locator
+  - Args: `locator: string`
+- `pause_queue_for_pool` — Disable all agents in a pool; optionally cancel queued for a build type
+  - Args: `poolId: string`, `cancelQueuedForBuildTypeId?: string`, `comment?: string`, `until?: string`
+- `resume_queue_for_pool` — Re-enable all agents in a pool
+  - Args: `poolId: string`
+
+### Server Health & Metrics
+- `get_server_info` — Returns `/app/rest/server`
+- `get_server_metrics` — Returns `/app/rest/server/metrics`
+- `list_server_health_items` — Returns `/app/rest/health`
+- `get_server_health_item` — Returns `/app/rest/health/{locator}`
+- `check_availability_guard` — Returns `{ ok, criticalCount, warningCount, items }`
+- `check_teamcity_connection` — Returns `{ ok }`
+
+### Availability & Compatibility
+- `set_agent_enabled` (full)
+  - Args: `agentId: string`, `enabled: boolean`, `comment?: string`, `until?: string`
+  - Returns: `{ success, action, agentId, enabled }`
+- `bulk_set_agents_enabled` (full)
+  - Args: `enabled: boolean`, `poolId?: string`, `locator?: string`, `comment?: string`, `until?: string`, `includeDisabled?: boolean`
+  - Returns: `{ success, action, total, succeeded, failed, results, locator?, poolId? }`
+- `get_agent_enabled_info` — Agent enabled status with comment/switch time
+  - Args: `agentId: string`
+- `get_compatible_build_types_for_agent` — Build types compatible with an agent
+  - Args: `agentId: string`
+- `get_incompatible_build_types_for_agent` — Build types incompatible with an agent
+  - Args: `agentId: string`
+- `get_compatible_agents_for_build_type` — Agents compatible with a build type
+  - Args: `buildTypeId: string`, `includeDisabled?: boolean`
+- `count_compatible_agents_for_build_type` — Count only
+  - Args: `buildTypeId: string`, `includeDisabled?: boolean`
+- `get_compatible_agents_for_queued_build` — Agents compatible with a queued/running build
+  - Args: `buildId: string`, `includeDisabled?: boolean`
+
+## Mode Summary
+- Dev mode tools: all tools not explicitly marked with Mode: full
+- Full mode adds write operations: `cancel_queued_build`, `create_*`, `clone_*`, `update_*`, `add_*`, `delete_*`, `authorize_agent`, `assign_agent_to_pool`, `manage_build_steps`, `manage_build_triggers`, `set_build_configs_paused`, `move_queued_build_to_top`, `reorder_queued_builds`, `cancel_queued_builds_for_build_type`, `cancel_queued_builds_by_locator`, `pause_queue_for_pool`, `resume_queue_for_pool`
+
+### Write API response shape (standardized)
+- All write tools return JSON with at least: `{ success: boolean, action: string, ...identifiers }`.
+- Identifiers echo the target of the action: e.g., `{ id }`, `{ buildId }`, `{ agentId }`, `{ buildTypeId, name }`, `{ locator }`.
+- When applicable, counts are included: `{ canceled, updated, succeeded, failed }`.

package/examples/list-build-configs-usage.ts

@@ -0,0 +1,276 @@
+/**
+ * Example usage of the ListBuildConfigs MCP tool
+ * Demonstrates various filtering and query patterns
+ */
+
+import { listBuildConfigsTool } from '@/tools/list-build-configs';
+
+// Example 1: Basic listing of all build configurations
+async function listAllConfigurations() {
+  const result = await listBuildConfigsTool.handler({});
+  
+  if (result.success && result.data) {
+    console.log(`Found ${result.data.totalCount} build configurations`);
+    result.data.buildConfigs.forEach(config => {
+      console.log(`- ${config.name} (${config.id})`);
+    });
+  }
+}
+
+// Example 2: Filter by specific project
+async function listProjectConfigurations(projectId: string) {
+  const result = await listBuildConfigsTool.handler({
+    projectId,
+    includeProjectHierarchy: true
+  });
+  
+  if (result.success && result.data) {
+    console.log(`Build configurations in project ${projectId}:`);
+    result.data.buildConfigs.forEach(config => {
+      const path = config.projectHierarchy
+        ?.map(p => p.name)
+        .join(' > ') || '';
+      console.log(`- ${config.name} (Path: ${path})`);
+    });
+  }
+}
+
+// Example 3: Search for deployment configurations
+async function findDeploymentConfigs() {
+  const result = await listBuildConfigsTool.handler({
+    namePattern: '*Deploy*',
+    statusFilter: {
+      paused: false,
+      lastBuildStatus: 'SUCCESS'
+    },
+    sortBy: 'lastModified',
+    sortOrder: 'desc'
+  });
+  
+  if (result.success && result.data) {
+    console.log('Active deployment configurations (recently successful):');
+    result.data.buildConfigs.forEach(config => {
+      console.log(`- ${config.name} (Last: ${config.lastBuildDate})`);
+    });
+  }
+}
+
+// Example 4: Find configurations using specific VCS repository
+async function findConfigsByRepository(repoUrl: string) {
+  const result = await listBuildConfigsTool.handler({
+    vcsRootFilter: {
+      url: repoUrl,
+      vcsName: 'git'
+    },
+    includeVcsRoots: true
+  });
+  
+  if (result.success && result.data) {
+    console.log(`Configurations using repository ${repoUrl}:`);
+    result.data.buildConfigs.forEach(config => {
+      const vcsInfo = config.vcsRoots
+        ?.map(vcs => `${vcs.name} (${vcs.branch})`)
+        .join(', ') || 'No VCS';
+      console.log(`- ${config.name}: ${vcsInfo}`);
+    });
+  }
+}
+
+// Example 5: Paginated retrieval for large datasets
+async function paginateThroughConfigs() {
+  let offset = 0;
+  const limit = 50;
+  let hasMore = true;
+  const allConfigs = [];
+  
+  while (hasMore) {
+    const result = await listBuildConfigsTool.handler({
+      pagination: { limit, offset }
+    });
+    
+    if (result.success && result.data) {
+      allConfigs.push(...result.data.buildConfigs);
+      hasMore = result.data.hasMore;
+      offset += limit;
+      
+      console.log(`Fetched ${result.data.buildConfigs.length} configs (total: ${allConfigs.length})`);
+    } else {
+      break;
+    }
+  }
+  
+  return allConfigs;
+}
+
+// Example 6: Get grouped view by project
+async function getProjectGroupedView() {
+  const result = await listBuildConfigsTool.handler({
+    viewMode: 'project-grouped',
+    includeParameters: true
+  });
+  
+  if (result.success && result.data && result.data.groupedByProject) {
+    Object.entries(result.data.groupedByProject).forEach(([projectId, group]) => {
+      console.log(`\nProject: ${group.projectName} (${projectId})`);
+      console.log(`  Configurations: ${group.buildConfigs.length}`);
+      
+      group.buildConfigs.forEach(config => {
+        const params = config.parameters 
+          ? Object.keys(config.parameters).length 
+          : 0;
+        console.log(`  - ${config.name} (${params} parameters)`);
+      });
+    });
+  }
+}
+
+// Example 7: Complex compound filtering
+async function advancedFiltering() {
+  const result = await listBuildConfigsTool.handler({
+    projectIds: ['Frontend', 'Backend', 'Mobile'],
+    namePattern: '*CI*',
+    vcsRootFilter: {
+      branch: 'main'
+    },
+    statusFilter: {
+      hasRecentActivity: true,
+      activeSince: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) // Last week
+    },
+    sortBy: 'name',
+    sortOrder: 'asc',
+    includeVcsRoots: true,
+    includeParameters: true,
+    pagination: {
+      limit: 25,
+      offset: 0
+    }
+  });
+  
+  if (result.success && result.data) {
+    console.log(`Found ${result.data.buildConfigs.length} CI configurations active in the last week`);
+    
+    result.data.buildConfigs.forEach(config => {
+      console.log(`\n${config.name} (${config.projectName})`);
+      console.log(`  Last build: ${config.lastBuildDate}`);
+      console.log(`  Status: ${config.lastBuildStatus}`);
+      
+      if (config.vcsRoots && config.vcsRoots.length > 0) {
+        console.log(`  VCS: ${config.vcsRoots.map(v => v.name).join(', ')}`);
+      }
+      
+      if (config.parameters && Object.keys(config.parameters).length > 0) {
+        console.log(`  Parameters: ${Object.keys(config.parameters).join(', ')}`);
+      }
+    });
+  }
+}
+
+// Example 8: Find inactive or problematic configurations
+async function findProblematicConfigs() {
+  const result = await listBuildConfigsTool.handler({
+    statusFilter: {
+      lastBuildStatus: 'FAILURE',
+      paused: false
+    },
+    sortBy: 'lastModified',
+    sortOrder: 'desc'
+  });
+  
+  if (result.success && result.data) {
+    console.log('Configurations with recent failures:');
+    result.data.buildConfigs.forEach(config => {
+      console.log(`- ${config.name} (${config.projectName}) - Last: ${config.lastBuildDate}`);
+    });
+  }
+  
+  // Also check for paused configurations
+  const pausedResult = await listBuildConfigsTool.handler({
+    statusFilter: {
+      paused: true
+    }
+  });
+  
+  if (pausedResult.success && pausedResult.data) {
+    console.log('\nPaused configurations:');
+    pausedResult.data.buildConfigs.forEach(config => {
+      console.log(`- ${config.name} (${config.projectName})`);
+    });
+  }
+}
+
+// Example 9: Export configuration list to CSV
+async function exportToCSV() {
+  const result = await listBuildConfigsTool.handler({
+    includeVcsRoots: true,
+    includeParameters: true
+  });
+  
+  if (result.success && result.data) {
+    const csv = ['ID,Name,Project,Description,VCS Count,Parameter Count'];
+    
+    result.data.buildConfigs.forEach(config => {
+      const vcsCount = config.vcsRoots?.length || 0;
+      const paramCount = config.parameters ? Object.keys(config.parameters).length : 0;
+      const description = config.description?.replace(/,/g, ';') || '';
+      
+      csv.push(`${config.id},${config.name},${config.projectName},"${description}",${vcsCount},${paramCount}`);
+    });
+    
+    console.log(csv.join('\n'));
+  }
+}
+
+// Example 10: Monitor configuration changes
+async function monitorChanges(intervalMs = 60000) {
+  let previousConfigs = new Map();
+  
+  const checkForChanges = async () => {
+    const result = await listBuildConfigsTool.handler({
+      sortBy: 'lastModified',
+      sortOrder: 'desc',
+      limit: 100
+    });
+    
+    if (result.success && result.data) {
+      const currentConfigs = new Map(
+        result.data.buildConfigs.map(c => [c.id, c])
+      );
+      
+      // Find new configurations
+      currentConfigs.forEach((config, id) => {
+        if (!previousConfigs.has(id)) {
+          console.log(`NEW: ${config.name} (${id})`);
+        }
+      });
+      
+      // Find removed configurations
+      previousConfigs.forEach((config, id) => {
+        if (!currentConfigs.has(id)) {
+          console.log(`REMOVED: ${config.name} (${id})`);
+        }
+      });
+      
+      previousConfigs = currentConfigs;
+    }
+  };
+  
+  // Initial check
+  await checkForChanges();
+  
+  // Set up monitoring
+  setInterval(checkForChanges, intervalMs);
+}
+
+// Export all examples
+export {
+  listAllConfigurations,
+  listProjectConfigurations,
+  findDeploymentConfigs,
+  findConfigsByRepository,
+  paginateThroughConfigs,
+  getProjectGroupedView,
+  advancedFiltering,
+  findProblematicConfigs,
+  exportToCSV,
+  monitorChanges
+};

package/jest.ci.config.js

@@ -0,0 +1,14 @@
+/** @type {import('jest').Config} */
+const base = require('./jest.config.js');
+
+module.exports = {
+  ...base,
+  // Ignore integration and e2e tests in CI unit run
+  testPathIgnorePatterns: [
+    ...(base.testPathIgnorePatterns || []),
+    '/tests/e2e/',
+    '/tests/integration/',
+  ],
+  // Disable coverage thresholds per-shard; thresholds are validated via overall reporting (Codecov)
+  coverageThreshold: undefined,
+};

package/jest.config.js

@@ -0,0 +1,108 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src', '<rootDir>/tests'],
+  testEnvironmentOptions: {
+    NODE_ENV: 'test',
+  },
+  // Load .env before any other setup so tests see env vars
+  setupFiles: ['dotenv/config', '<rootDir>/jest.setup.js'],
+  testMatch: [
+    '**/__tests__/**/*.test.ts',
+    '**/*.test.ts',
+    '**/__tests__/**/*.{ts,tsx,js}',
+    '**/?(*.)+(spec|test).{ts,tsx,js}'
+  ],
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: {
+        esModuleInterop: true,
+        allowJs: true,
+        strict: false,
+        noUnusedLocals: false,
+        noUnusedParameters: false
+      }
+    }]
+  },
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/**/*.test.{ts,tsx}',
+    '!src/**/__tests__/**',
+    '!src/types/**',
+    // Exclude pure type definitions and barrels
+    '!src/teamcity/types/**',
+    '!src/tools/index.ts',
+    '!**/*.test.ts',
+    '!**/*.spec.ts',
+    '!src/teamcity-client/**/*',
+    // Temporarily exclude TeamCity managers pending coverage backfill
+    '!src/teamcity/**/*.ts',
+    // Exclude entrypoints, barrels, generated or integration-only adapters
+    '!src/index.ts',
+    '!src/swagger/index.ts',
+    '!src/teamcity/index.ts',
+    '!src/teamcity/client.ts',
+    '!src/teamcity/config.ts',
+    // Exclude integration-heavy direct API wrapper from unit coverage
+    '!src/api-client.ts',
+    // Temporarily exclude complex managers pending dedicated tests
+    '!src/teamcity/build-config-manager.ts',
+    '!src/teamcity/build-configuration-clone-manager.ts',
+    '!src/teamcity/build-configuration-update-manager.ts',
+    // Temporarily exclude swagger and middleware layers from coverage thresholds
+    '!src/swagger/**/*.ts',
+    '!src/middleware/**/*.ts',
+    '!src/errors/index.ts',
+    '!src/config/index.ts',
+    '!src/tools.ts',
+    '!src/formatters/*.ts'
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html', 'json-summary'],
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 69,
+      lines: 80,
+      statements: 80,
+    },
+  },
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+    '^@/tools/(.*)$': '<rootDir>/src/tools/$1',
+    '^@/utils/(.*)$': '<rootDir>/src/utils/$1',
+    '^@/types/(.*)$': '<rootDir>/src/types/$1',
+    '^@/config/(.*)$': '<rootDir>/src/config/$1',
+    '^@/middleware/(.*)$': '<rootDir>/src/middleware/$1',
+    '^@/mcp/(.*)$': '<rootDir>/src/mcp/$1',
+    '^@modelcontextprotocol/sdk/server/index\\.js$': '<rootDir>/tests/__mocks__/@modelcontextprotocol/sdk/server/index.js',
+    '^@modelcontextprotocol/sdk/server/stdio\\.js$': '<rootDir>/tests/__mocks__/@modelcontextprotocol/sdk/server/stdio.js',
+    '^@modelcontextprotocol/sdk/types\\.js$': '<rootDir>/tests/__mocks__/@modelcontextprotocol/sdk/types.js'
+  },
+  transformIgnorePatterns: [
+    'node_modules/(?!(@modelcontextprotocol)/)'
+  ],
+  extensionsToTreatAsEsm: ['.ts'],
+  setupFilesAfterEnv: ['<rootDir>/tests/setup.ts'],
+  testTimeout: 10000,
+  verbose: true,
+  clearMocks: true,
+  restoreMocks: true,
+  // Allow Jest to exit naturally; avoid forced-exit warnings
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+    '/dist/',
+    '/coverage/'
+  ],
+  testPathIgnorePatterns: [
+    '/node_modules/',
+    '/dist/'
+  ],
+  watchPathIgnorePatterns: [
+    '/node_modules/',
+    '/dist/',
+    '/coverage/'
+  ]
+};