@daghis/teamcity-mcp 0.1.2

package/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Thanks for contributing! This document highlights conventions and expectations to keep the repository consistent and easy to maintain.
+
+## Testing Philosophy
+
+We follow a behavior‑first approach for tests:
+
+- Prefer asserting observable outcomes over internal implementation details.
+- Validate returned values, state transitions, emitted events, and documented side‑effects.
+- Avoid checking private/underscored fields and exact wire formats (locators, field strings, headers, payload shapes) unless explicitly part of the public contract.
+
+### When call‑count assertions are appropriate
+
+Only add call‑count assertions when the count itself is the documented behavior:
+
+- Caching: second identical call returns the same result and does not invoke the underlying client again. After TTL or with `forceRefresh`, calls increase accordingly.
+- Concurrency/parallelization: where a component guarantees parallel execution, keep minimal assertions that reflect the contract (e.g., not N× sequential time).
+- Circuit breaker: ensuring short‑circuiting behavior with no underlying call in OPEN state.
+
+### Logging assertions
+
+It’s acceptable to assert logger calls only when logging is part of the public contract (e.g., specific redaction guarantees, structured error logging). Otherwise prefer asserting returned errors/results.
+
+### MCP tool responses
+
+Tools must return standardized JSON payloads. Tests should assert:
+
+- `success`, `action`, and echoed identifiers (e.g., `agentId`, `locator`, `buildId`).
+- Documented optional flags (e.g., `includeQueueTotals`) affecting response shape.
+- Avoid verifying how API clients are invoked.
+
+### Examples (good)
+
+- “Calling list with `all=true` returns all items and correct pagination metadata.”
+- “Second call within TTL returns same results; client calls remain at 1.”
+- “get_build_status returns `queued` with `queuePosition` and `waitReason` when flags are set.”
+
+### Examples (avoid)
+
+- Verifying exact TeamCity `locator` strings or `fields` parameter composition.
+- Inspecting axios request headers/payload shapes for managers/tools.
+- Counting calls without a documented behavior that warrants it.
+
+## Code Style
+
+- TypeScript, strict mode. No `any`. Prefer precise types and generics.
+- Prettier for formatting; ESLint for lint rules. Run `npm run lint` and `npm run format`.
+- Use existing logger utilities; avoid `console.log`.
+- Keep changes minimal and focused; preserve module boundaries.
+
+## Commit Messages
+
+- Imperative mood: “Add X”, “Fix Y”.
+- Include ticket IDs when applicable: `[TMCP-123] Short summary`.
+- Follow [Conventional Commits](https://www.conventionalcommits.org/):
+  - Use lower‑case `type` prefixes like `feat`, `fix`, or `chore`.
+  - Keep the summary within 72 characters.
+  - PR titles must also follow this format and will become the squash merge commit message.
+- Commit message linting runs in CI to enforce the convention.
+
+## Pull Requests
+
+- Describe scope, rationale, and testing.
+- Link issues/tickets; include logs or CLI output if relevant.
+- Ensure CI is green and `npm run check` passes locally.
+- Use **Squash and merge** so the merge commit inherits the PR’s conventional title.
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 TeamCity MCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,256 @@
+# TeamCity MCP Server
+
+[![CI](https://github.com/Daghis/teamcity-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Daghis/teamcity-mcp/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Daghis/teamcity-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/Daghis/teamcity-mcp/actions/workflows/codeql.yml)
+[![codecov](https://codecov.io/gh/Daghis/teamcity-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/Daghis/teamcity-mcp)
+
+A Model Control Protocol (MCP) server that bridges AI coding assistants with JetBrains TeamCity CI/CD server, enabling natural language control of builds, tests, and deployments.
+
+## Overview
+
+The TeamCity MCP Server allows developers using AI-powered coding assistants (Claude Code, Cursor, Windsurf) to interact with TeamCity directly from their development environment using natural language commands.
+
+## Features
+
+### 🚀 Two Operational Modes
+
+- **Dev Mode**: Safe CI/CD operations
+  - Trigger builds
+  - Monitor build status and progress
+  - Fetch and analyze build logs
+  - Investigate test failures
+  - List projects and configurations
+
+- **Full Mode**: Complete infrastructure management
+  - All Dev mode features, plus:
+  - Create and clone build configurations
+  - Manage build steps and triggers
+  - Configure VCS roots and agents
+  - Set up new projects
+  - Modify infrastructure settings
+
+### 🎯 Key Capabilities
+
+- **Natural Language Control**: Execute CI/CD tasks using conversational commands
+- **Intelligent Analysis**: Automatic test failure summarization and build problem identification
+- **Real-time Monitoring**: Live build status updates via WebSocket/SSE
+- **Enterprise Security**: Token-based authentication with audit logging
+- **Modern Architecture**: Simple, direct implementation with singleton pattern
+- **Performance Optimized**: Fast startup time with minimal overhead
+- **Clean Codebase**: Well-organized modules with clear separation of concerns
+
+## Installation
+
+### Prerequisites
+
+- Node.js >= 20.10.0
+- TeamCity Server 2020.1+ with REST API access
+- TeamCity authentication token
+
+### Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/Daghis/teamcity-mcp.git
+cd teamcity-mcp
+
+# Install dependencies
+npm install
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your TeamCity URL and token
+
+# Run in development mode
+npm run dev
+```
+
+### npm Package (Coming Soon)
+
+```bash
+npx @daghis/teamcity-mcp --mode=dev
+```
+
+## Configuration
+
+Environment is validated centrally with Zod. Supported variables and defaults:
+
+```env
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+LOG_LEVEL=info
+
+# TeamCity Configuration (aliases supported)
+TEAMCITY_URL=https://teamcity.example.com
+TEAMCITY_TOKEN=your-auth-token
+# Optional aliases:
+# TEAMCITY_SERVER_URL=...
+# TEAMCITY_API_TOKEN=...
+
+# MCP Mode (dev or full)
+MCP_MODE=dev
+
+# Optional advanced TeamCity options (defaults shown)
+# Connection
+# TEAMCITY_TIMEOUT=30000
+# TEAMCITY_MAX_CONCURRENT=10
+# TEAMCITY_KEEP_ALIVE=true
+# TEAMCITY_COMPRESSION=true
+
+# Retry
+# TEAMCITY_RETRY_ENABLED=true
+# TEAMCITY_MAX_RETRIES=3
+# TEAMCITY_RETRY_DELAY=1000
+# TEAMCITY_MAX_RETRY_DELAY=30000
+
+# Pagination
+# TEAMCITY_PAGE_SIZE=100
+# TEAMCITY_MAX_PAGE_SIZE=1000
+# TEAMCITY_AUTO_FETCH_ALL=false
+
+# Circuit Breaker
+# TEAMCITY_CIRCUIT_BREAKER=true
+# TEAMCITY_CB_FAILURE_THRESHOLD=5
+# TEAMCITY_CB_RESET_TIMEOUT=60000
+# TEAMCITY_CB_SUCCESS_THRESHOLD=2
+```
+
+These values are normalized in `src/config/index.ts` and consumed by `src/teamcity/config.ts` via helper getters.
+
+## Usage Examples
+
+Once integrated with your AI coding assistant:
+
+```
+"Build the frontend on feature branch"
+"Why did last night's tests fail?"
+"Deploy staging with the latest build"
+"Create a new build config for the mobile app"
+```
+
+### Tool Responses and Pagination
+
+- Responses: Tools now return consistent MCP content. For list/get operations, the `content[0].text` contains a JSON string. Example shape:
+  `{ "items": [...], "pagination": { "page": 1, "pageSize": 100 } }` or `{ "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }`.
+- Pagination: Most list\_\* tools accept `pageSize`, `maxPages`, and `all`:
+  - `pageSize` controls items per page.
+  - `all: true` fetches multiple pages up to `maxPages`.
+  - Legacy `count` on `list_builds` is kept for compatibility but `pageSize` is preferred.
+
+### Validation and Errors
+
+- Input validation: Tool inputs are validated with Zod schemas; invalid input returns a structured error payload in the response content (JSON string) with `success: false` and `error.code = VALIDATION_ERROR`.
+- Error shaping: Errors are formatted consistently via a global handler. In production, messages may be sanitized; sensitive values (e.g., tokens) are redacted in logs.
+
+### API Usage
+
+```typescript
+import { TeamCityAPI } from '@/api-client';
+
+// Get the API client instance
+const api = TeamCityAPI.getInstance();
+
+// List projects
+const projects = await api.listProjects();
+
+// Get build status
+const build = await api.getBuild('BuildId123');
+
+// Trigger a new build
+const newBuild = await api.triggerBuild('BuildConfigId', {
+  branchName: 'main',
+});
+```
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+
+# Type check
+npm run typecheck
+
+# Build for production
+npm run build
+```
+
+## Project Structure
+
+```
+teamcity-mcp/
+├── src/               # Source code
+│   ├── tools/        # MCP tool implementations
+│   ├── utils/        # Utility functions
+│   ├── types/        # TypeScript type definitions
+│   └── config/       # Configuration management
+├── tests/            # Test files
+├── docs/             # Documentation
+└── .agent-os/        # Agent OS specifications
+```
+
+## API Documentation
+
+The MCP server exposes tools for TeamCity operations. Each tool corresponds to specific TeamCity REST API endpoints:
+
+### Build Management
+
+- `TriggerBuild` - Queue a new build
+- `GetBuildStatus` - Check build progress
+- `FetchBuildLog` - Retrieve build logs
+- `ListBuilds` - Search builds by criteria
+
+### Test Analysis
+
+- `ListTestFailures` - Get failing tests
+- `GetTestDetails` - Detailed test information
+- `AnalyzeBuildProblems` - Identify failure reasons
+
+### Configuration (Full Mode Only)
+
+- `create_build_config` - Create new TeamCity build configurations with full support for:
+  - VCS roots (Git, SVN, Perforce) with authentication
+  - Build steps (script, Maven, Gradle, npm, Docker, PowerShell)
+  - Triggers (VCS, schedule, finish-build, maven-snapshot)
+  - Parameters and template-based configurations
+  - See the Tool Reference for details: docs/mcp-tools-reference.md
+- `CloneBuildConfig` - Duplicate configurations (coming soon)
+- `ManageBuildSteps` - Add/edit/remove steps (coming soon)
+- `ManageVCS` - Configure version control (coming soon)
+
+See also: `docs/TEAMCITY_MCP_TOOLS_GUIDE.md` for an overview. Some advanced sections in that guide describe future enhancements; the behavior above reflects the current implementation.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## Security
+
+- Configure `TEAMCITY_TOKEN` via environment (see `.env.example`); never commit real tokens
+- Token-based authentication only
+- Logs redact sensitive values
+
+## Support
+
+- GitHub Issues: [Report bugs or request features](https://github.com/Daghis/teamcity-mcp/issues)
+- Documentation: See the `docs/` folder in this repository
+
+## Acknowledgments
+
+- JetBrains TeamCity for the excellent CI/CD platform
+- Anthropic for the Model Control Protocol specification
+- The open-source community for continuous support
+
+---
+
+Built with ❤️ for developers who love efficient CI/CD workflows

package/TODO.md

@@ -0,0 +1,80 @@
+# OSS Launch TODO
+
+High-level checklist to complete before publishing the repository to GitHub.
+
+## Legal & Notices
+- Create `THIRD_PARTY_NOTICES.md`:
+  - Note use of JetBrains TeamCity name/trademark; clarify no affiliation or endorsement.
+  - Mention TeamCity REST API usage and link to relevant terms.
+  - Acknowledge project crafting via Anthropic’s Claude Code and OpenAI Codex CLI.
+  - List notable third‑party deps/tools: `@modelcontextprotocol/sdk`, `axios`, `zod`, `jest`, `ts-jest`, `prettier`, `eslint`, OpenAPI generator.
+- Verify LICENSE (MIT) is correct and reflected in README.
+
+## TeamCity Self‑Integration
+- Create a TeamCity project that builds this repo (self‑hosting example):
+  - Steps: install deps, `npm run lint`, `npm run typecheck`, `npm test`, `npm run build`.
+  - Parameterize Node version via `.nvmrc` (24.7.0) and agent requirements.
+  - Configure secure `TEAMCITY_URL`/`TEAMCITY_TOKEN` (dev‑mode, read‑only) as server/agent parameters.
+  - Add triggers on `main` and PR branches; publish build artifacts (e.g., coverage report) for docs.
+  - Optional: nightly job to run integration smoke tests against a sandbox TeamCity instance.
+
+## GitHub Actions (CI/CD)
+- Add workflows (defer until ready to enable CI):
+  - `ci.yml`: Node 24, cache `~/.npm`, run `lint:check`, `format:check`, `typecheck`, and `test:coverage` (enforce thresholds); optionally upload coverage to a badge service.
+  - `release.yml`: On tag, build and publish to npm (if publishing), generate changelog and GitHub Release.
+  - `codeql.yml`: Code scanning (JavaScript/TypeScript).
+  - Optional: `e2e.yml` gated by secrets for TeamCity sandbox.
+- Configure required checks (branch protection) for `main` when CI is enabled.
+
+## OSS Best Practices
+- README badges: build status (GH Actions), coverage, npm version (if publishing), license, Node version, Prettier.
+- Add Node 24 badge and update README references to Node 24.
+- Governance docs:
+  - `CODE_OF_CONDUCT.md` (Contributor Covenant)
+  - `SECURITY.md` (reporting policy)
+  - Ensure `CONTRIBUTING.md` aligns with workflows and labels
+  - Issue/PR templates and labels (bug, feature, question, good‑first‑issue)
+- Release hygiene:
+  - `CHANGELOG.md` (keep a human‑readable log or use release‑please)
+  - Semantic versioning policy documented in README
+- Repository hygiene:
+  - `CODEOWNERS` for review routing
+  - Dependabot or Renovate for deps
+  - Stale bot policy (optional)
+
+## Packaging & Publishing
+- `package.json` metadata: `repository`, `homepage`, `bugs`, `license`, `engines`, `exports`/`bin` (if CLI), `files` whitelist.
+- Add `.npmignore` (or use `files` field) to exclude tests, local scripts, and docs not needed for package.
+- Verify build output under `dist/` matches exports and type definitions.
+
+## Codebase Quality (Housekeeping)
+- ESLint hygiene: keep `no-await-in-loop` disables narrowly scoped around intentional sequential logic (done in current codebase; verify on new contributions).
+- Remove remaining legacy `getTool(...)!` usages by migrating to `getRequiredTool` where applicable.
+- Centralize env var validation (zod) in `src/config` and use consistently.
+- Silence ESLint multi-project hint by using `tsconfig.lint.json` or enabling `noWarnOnMultipleProjects`.
+
+## Test Stability
+- Avoid forced Jest exits; rely on natural shutdown. Ensure timers are cleared in `tests/setup.ts` (added) and prefer fake timers in new tests.
+
+## Documentation
+- README refinements:
+  - Add badges, succinct Quick Start, and a minimal “Dev vs Full mode” table.
+  - Link to `docs/` and `THIRD_PARTY_NOTICES.md`.
+  - Add a short “Security & Privacy” note about token redaction and not committing secrets.
+- Docs site (optional): publish GitHub Pages or Docusaurus if scope grows.
+- Provide minimal examples in `examples/` to demonstrate common tool calls and MCP client integration.
+
+## Security & Compliance
+- Enable GitHub secret scanning and push protection.
+- Validate token redaction in logs; keep `.env.example` minimal and safe.
+- Add threat‑model notes (read‑only defaults in `dev` mode; `full` mode cautions).
+
+## Project Setup on GitHub
+- Initialize repo, push baseline, add branch protections, enable Discussions (optional).
+- Configure Actions permissions (workflows can create releases/tags if needed).
+- Configure CI required checks and status badges.
+
+## Nice‑to‑Haves (Post‑Launch)
+- Benchmarks and performance notes for large TeamCity instances.
+- Example TeamCity templates for self‑integration (YAML or screenshots).
+- Automated docs generation (OpenAPI → client usage snippets) if we add an API facade.