@daghis/teamcity-mcp 0.1.2

package/.commitlintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+};

package/.eslintignore

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+coverage/
+*.js
+*.mjs
+*.cjs
+scripts/
+.husky/
+tests/*.js
+jest.config.js
+.eslintrc.js
+
+# Auto-generated TeamCity API client files
+src/teamcity-client/**/*
+# Keep only the index file for imports
+!src/teamcity-client/index.ts

package/.eslintrc.js

@@ -0,0 +1,166 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+    project: ['./tsconfig.json', './tsconfig.build.json'],
+    tsconfigRootDir: __dirname,
+    // Suppress noisy parser warning when multiple tsconfig projects are used
+    noWarnOnMultipleProjects: true,
+  },
+  env: {
+    node: true,
+    es2022: true,
+    jest: true,
+  },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier',
+  ],
+  plugins: [
+    '@typescript-eslint',
+    'import',
+  ],
+  rules: {
+    // Code Quality Rules
+    'no-console': 'error', // Enforce winston logger usage
+    'no-debugger': 'error',
+    'no-alert': 'error',
+    'no-var': 'error',
+    'prefer-const': 'error',
+    'prefer-arrow-callback': 'error',
+    
+    // TypeScript Rules
+    '@typescript-eslint/no-unused-vars': ['error', { 
+      argsIgnorePattern: '^_',
+      varsIgnorePattern: '^_' 
+    }],
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/strict-boolean-expressions': ['error', {
+      allowString: true,
+      allowNumber: true,
+      allowNullableObject: true,
+      allowNullableBoolean: true,
+      allowNullableString: true,
+      allowNullableNumber: true,
+      allowAny: false,
+    }],
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-non-null-assertion': 'warn',
+    '@typescript-eslint/prefer-nullish-coalescing': 'warn',
+    '@typescript-eslint/prefer-optional-chain': 'warn',
+    
+    // Naming Conventions
+    '@typescript-eslint/naming-convention': [
+      'error',
+      {
+        selector: 'interface',
+        format: ['PascalCase'],
+      },
+      {
+        selector: 'typeAlias',
+        format: ['PascalCase'],
+      },
+      {
+        selector: 'enum',
+        format: ['PascalCase'],
+      },
+      {
+        selector: 'variable',
+        format: ['camelCase', 'UPPER_CASE', 'PascalCase'],
+        leadingUnderscore: 'allow',
+      },
+      {
+        selector: 'function',
+        format: ['camelCase'],
+      },
+      {
+        selector: 'method',
+        format: ['camelCase'],
+      },
+      {
+        selector: 'classProperty',
+        format: ['camelCase'],
+        leadingUnderscore: 'allow',
+      },
+      {
+        selector: 'parameter',
+        format: ['camelCase'],
+        leadingUnderscore: 'allow',
+      },
+    ],
+    
+    // Import Rules
+    'import/order': 'off', // Let Prettier handle import ordering
+    'import/no-duplicates': 'error',
+    'import/no-unused-modules': 'error',
+    'import/first': 'error',
+    'import/newline-after-import': 'error',
+    'import/no-default-export': 'off', // Allow default exports
+    
+    // Code Style
+    'object-shorthand': 'error',
+    'prefer-template': 'error',
+    'no-useless-concat': 'error',
+    'no-useless-return': 'error',
+    'no-duplicate-imports': 'error',
+    'sort-imports': 'off', // Let Prettier handle import sorting
+    
+    // Error Prevention
+    'no-implicit-coercion': 'error',
+    'no-param-reassign': 'error',
+    'no-return-assign': 'error',
+    'no-throw-literal': 'error',
+    'prefer-promise-reject-errors': 'error',
+    
+    // Performance
+    'no-await-in-loop': 'warn',
+    'require-atomic-updates': 'error',
+  },
+  overrides: [
+    {
+      files: ['**/*.test.ts', '**/*.test.tsx', '**/*.spec.ts', '**/*.spec.tsx'],
+      env: {
+        jest: true,
+      },
+      rules: {
+        // Enforce strict typing in tests as well
+        '@typescript-eslint/no-explicit-any': 'error',
+        '@typescript-eslint/no-non-null-assertion': 'warn',
+        '@typescript-eslint/strict-boolean-expressions': 'error',
+        '@typescript-eslint/no-floating-promises': 'error',
+        '@typescript-eslint/no-misused-promises': 'error',
+        // Tests mutate process.env frequently; avoid noisy false positives
+        'require-atomic-updates': 'off',
+        'no-console': 'off', // Allow console in tests
+      },
+    },
+    {
+      files: ['scripts/**/*.ts', 'scripts/**/*.js'],
+      rules: {
+        'no-console': 'off', // Allow console in scripts
+      },
+    },
+    {
+      files: ['jest.config.js', '*.config.js'],
+      env: {
+        node: true,
+      },
+      rules: {
+        '@typescript-eslint/no-require-imports': 'off',
+        'import/no-default-export': 'off',
+      },
+    },
+  ],
+  settings: {
+    'import/resolver': {
+      typescript: {
+        alwaysTryTypes: true,
+        project: ['./tsconfig.json', './tsconfig.build.json'],
+      },
+    },
+  },
+};

package/.github/settings.yml

@@ -0,0 +1,7 @@
+repository:
+  allow_merge_commit: false
+  allow_rebase_merge: false
+  allow_squash_merge: true
+  delete_branch_on_merge: true
+  squash_merge_commit_title: PR_TITLE
+  squash_merge_commit_message: PR_BODY

package/.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - 'release-please--*'
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint (no fix)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+      - run: npm ci
+      - run: npm run lint:check
+
+  format:
+    name: Format check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+      - run: npm ci
+      - run: npm run format:check
+
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+      - run: npm ci
+      - run: npm run typecheck
+
+  tests:
+    name: Tests with coverage (unit) – shard ${{ matrix.shard }}/4
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+      - run: npm ci
+      - name: Run tests with coverage (unit-only + JUnit)
+        env:
+          JEST_JUNIT_OUTPUT: ./coverage/junit-${{ matrix.shard }}.xml
+          JEST_JUNIT_CLASSNAME: "{filepath}"
+        run: npm run test:coverage:ci -- --reporters=default --reporters=jest-junit --shard=${{ matrix.shard }}/4 --passWithNoTests
+      - name: Upload coverage to Codecov
+        if: success()
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/lcov.info
+          flags: unittests
+          name: codecov-coverage
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage/junit-${{ matrix.shard }}.xml
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-shard-${{ matrix.shard }}
+          path: coverage/
+          if-no-files-found: ignore
+
+  aggregate:
+    name: Lint, Typecheck, Test (Node 20)
+    runs-on: ubuntu-latest
+    needs: [lint, format, typecheck, tests]
+    if: always()
+    steps:
+      - name: Evaluate job results
+        run: |
+          echo "lint: ${{ needs.lint.result }}"
+          echo "format: ${{ needs.format.result }}"
+          echo "typecheck: ${{ needs.typecheck.result }}"
+          echo "tests: ${{ needs.tests.result }}"
+          if [ "${{ needs.lint.result }}" != "success" ] || \
+             [ "${{ needs.format.result }}" != "success" ] || \
+             [ "${{ needs.typecheck.result }}" != "success" ] || \
+             [ "${{ needs.tests.result }}" != "success" ]; then
+            echo "One or more jobs failed";
+            exit 1;
+          fi

package/.github/workflows/codeql.yml

@@ -0,0 +1,35 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  schedule:
+    - cron: '0 3 * * 1'
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (JavaScript/TypeScript)
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: javascript-typescript
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+

package/.github/workflows/commitlint.yml

@@ -0,0 +1,20 @@
+name: Commitlint
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: wagoid/commitlint-github-action@v5
+        with:
+          configFile: .commitlintrc.js
+          commitDepth: 1

package/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_run:
+    workflows: ["Release Please"]
+    types: [completed]
+
+permissions:
+  contents: read
+  id-token: write # for npm provenance
+
+jobs:
+  publish:
+    if: >-
+      ${{ github.event_name == 'release' ||
+          (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') }}
+    name: Publish package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+          scope: '@daghis'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Verify package contents
+        run: npm pack --dry-run
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: 'true'
+        run: |
+          npm publish --access public --provenance

package/.github/workflows/release-please.yml

@@ -0,0 +1,21 @@
+name: Release Please
+
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: release-please
+      cancel-in-progress: true
+    steps:
+      - name: Release Please
+        uses: googleapis/release-please-action@v4
+        with:
+          release-type: node

package/.nvmrc

@@ -0,0 +1 @@
+20.10.0

package/.prettierignore

@@ -0,0 +1,22 @@
+node_modules/
+dist/
+coverage/
+*.min.js
+*.min.css
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+.husky/
+.git/
+.next/
+.cache/
+build/
+*.log
+.DS_Store
+.env*
+!.env.example
+
+# Auto-generated TeamCity API client files
+src/teamcity-client/**/*
+# Keep only the index file for imports
+!src/teamcity-client/index.ts

package/.prettierrc

@@ -0,0 +1,28 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "requirePragma": false,
+  "insertPragma": false,
+  "proseWrap": "preserve",
+  "htmlWhitespaceSensitivity": "css",
+  "endOfLine": "lf",
+  "embeddedLanguageFormatting": "auto",
+  "plugins": ["@trivago/prettier-plugin-sort-imports"],
+  "importOrder": [
+    "^node:",
+    "<THIRD_PARTY_MODULES>",
+    "^@/(.*)$",
+    "^[./]"
+  ],
+  "importOrderSeparation": true,
+  "importOrderSortSpecifiers": true
+}

package/AGENTS.md

@@ -0,0 +1,68 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/` — TypeScript source. Key areas: `teamcity/` (API + managers), `tools.ts` (MCP tools), `utils/`, `types/`, `config/`, `server.ts`.
+- `tests/` — Jest tests (unit/integration) plus mocks and setup.
+- `docs/` — Additional docs; see `ARCHITECTURE.md` for design notes.
+- `scripts/` — Build/tooling scripts. Build output goes to `dist/`.
+- Path aliases: `@/utils`, `@/types`, `@/config`, `@/server`, `@/tools`.
+
+## Build, Test, and Development Commands
+- `npm run dev` — Watch + run `src/index.ts` via tsx.
+- `npm run build` — Production build to `dist/`.
+- `npm start` — Run built server from `dist/`.
+- `npm test` | `npm run test:unit` | `npm run test:integration` — Run Jest suites.
+- `npm run test:coverage` — Coverage report (thresholds enforced).
+- `npm run lint` / `npm run lint:check` — ESLint with Prettier integration.
+- `npm run format` — Format; `npm run typecheck` — TS type checking.
+- Node 20.x required. Use `.nvmrc` (20.x). Copy `.env` from `.env.example` and fill values.
+
+## Coding Style & Naming Conventions
+- Prettier: 2 spaces, 100 cols, single quotes, trailing commas; import order via `@trivago/prettier-plugin-sort-imports`.
+- ESLint: `no-console` — use `utils/logger.ts` (Winston). Prefer arrow functions, `const`, template strings.
+- Naming: types/interfaces/enums — PascalCase; vars/functions/params — camelCase; constants may be UPPER_CASE.
+- Types: no `any`; use generics/`unknown`/precise types. Public APIs have explicit return types. Default or named exports allowed.
+
+## Testing Guidelines
+- Framework: Jest + ts-jest. Tests in `src/**/*.test.ts` or `tests/**`. Setup: `jest.setup.js`, `tests/setup.ts`; mocks in `tests/__mocks__/`.
+- Coverage: ≥ 80% (branches, functions, lines, statements) via `npm run test:coverage`.
+- Behavior-first: assert outputs, events, and side effects. Avoid peeking into internals or mock call counts except for thin adapters or explicit logging/redaction utilities.
+
+## Commit & Pull Request Guidelines
+- Commits: imperative subject; include ticket when applicable, e.g., `[TMCP-123] Short summary` (≤72 chars). Add body for rationale/breaking changes.
+- PRs: link issues/tickets, describe scope and testing, include relevant logs or CLI output. Require green CI and `npm run check` locally.
+- PR descriptions should use Markdown with proper newlines. When scripting, prefer `gh pr edit --body-file` (or `--body` with actual newlines) to ensure bullets and paragraphs render correctly.
+
+## Security & Configuration Tips
+- Never commit secrets. Configure via `.env` (e.g., `TEAMCITY_URL`, `TEAMCITY_TOKEN`, `MCP_MODE`). Use provided TeamCity client/managers; respect rate limits and retries.
+
+## Reference Documentation
+- Primary: `docs/` and `ARCHITECTURE.md` for design, flows, and module boundaries.
+- API surface: `src/teamcity/` managers and `src/teamcity/index.ts` re-exports. Contracts are defined in `src/teamcity/api-types.ts` and `src/types/`.
+- MCP tools: `src/tools.ts` lists tool identifiers, argument shapes, and returned payloads. Search by tool `name` to find handlers.
+- Configuration: see `src/config/` and `.env.example` for required keys and defaults.
+- Quick discovery examples:
+  - `rg -n "^export (type|interface|enum)" src/types src/teamcity`
+  - `rg -n "name: '" src/tools.ts`
+
+## Agent-Specific Instructions
+- Keep changes minimal and focused; preserve module boundaries.
+- Prefer existing utilities, path aliases, and the shared logger.
+- Add tests alongside code; avoid new dependencies without discussion.
+
+## TeamCity API Map
+- Entry point: `src/teamcity/index.ts` — re-exports auth/config/utilities and exposes `initializeTeamCity`, `getTeamCityClient`, `createTeamCityClient`, plus convenience helpers (e.g., `triggerBuild`, `getBuildStatus`).
+- Client: `client.ts` (`TeamCityClient`) and `client-adapter.ts` — typed HTTP access to TeamCity REST APIs.
+- Config: `config.ts` — `loadTeamCityConfig`, `validateConfig`, `toClientConfig`, `TeamCityFullConfig`.
+- Types: `api-types.ts` and `src/teamcity/types/**` — API contracts and normalized shapes.
+- Managers (behavioral layers):
+  - Build: `build-configuration-*.ts`, `build-config-manager.ts`, `build-step-manager.ts`, `build-trigger-manager.ts`, `build-parameters-manager.ts`, `build-queue-manager.ts`, `build-results-manager.ts`, `build-status-manager.ts`, `build-list-manager.ts`.
+  - Projects: `project-manager.ts`, `project-list-manager.ts`, `project-navigator.ts`.
+  - Branch/Artifacts: `branch-*.ts`, `artifact-manager.ts`.
+- Utilities: `pagination.ts`, `circuit-breaker.ts`, `errors.ts`, `configuration-branch-matcher.ts`.
+- Quick start example:
+  ```ts
+  import { initializeTeamCity, triggerBuild } from '@/teamcity';
+  await initializeTeamCity();
+  await triggerBuild('MyBuildTypeId', 'refs/heads/main');
+  ```

package/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# TeamCity MCP Server — Architecture
+
+## Overview
+
+The server implements a straightforward MCP server that bridges MCP tools to the TeamCity REST API. The design favors direct, readable code over heavy abstractions.
+
+## Code Map
+
+```
+src/
+├── index.ts          # Entry point (env validation, transport wiring)
+├── server.ts         # MCP server setup and request handlers
+├── api-client.ts     # Thin TeamCity API wrapper (singleton access)
+├── tools.ts          # Tool definitions and handlers
+├── config/           # Config helpers (env parsing, mode)
+├── utils/            # Logging and helpers
+├── middleware/       # Error/formatting middleware used by tools
+├── teamcity/         # Higher-level managers for some operations
+└── teamcity-client/  # Generated REST client (OpenAPI)
+```
+
+## Design Principles
+
+- Direct implementation: no DI container, minimal indirection
+- Singleton API client via `TeamCityAPI.getInstance()`
+- Tools are registered via a simple list; handlers call the API client
+- Explicit error shaping for MCP responses; logs redact sensitive values
+
+## Request Flow
+
+1. `index.ts` loads env and starts the server over stdio (MCP)
+2. `server.ts` registers `tools/list` and `tools/call` handlers
+3. `tools.ts` exposes tools according to `MCP_MODE` (`dev` or `full`)
+4. Tool handlers use `api-client.ts` and/or `teamcity/` managers
+
+## Configuration
+
+Set environment variables (see `.env.example`):
+
+```
+TEAMCITY_URL=https://teamcity.example.com
+TEAMCITY_TOKEN=your-api-token
+MCP_MODE=dev   # or full
+```
+
+## Extending Tools
+
+Add a new entry in `tools.ts` with an input schema and handler:
+
+```ts
+{
+  name: 'my_new_tool',
+  description: 'What it does',
+  inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  handler: async ({ id }) => {
+    const api = TeamCityAPI.getInstance();
+    const data = await api.someMethod(id);
+    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+  },
+}
+```
+
+## Notes
+
+- The `teamcity-client/` folder contains generated code and may include permissive typings (e.g., `any`) from the upstream spec. Core modules avoid `any`.
+- Large Swagger/OpenAPI JSON files are not checked in; use generator configs in the root to regenerate as needed.

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.2 (2025-09-11)
+
+
+### Miscellaneous Chores
+
+* release 0.1.2 ([21e2595](https://github.com/Daghis/teamcity-mcp/commit/21e25950074ed49bd3e6c571f432f27fb8bd434e))