TeamCity

Translates incoming Model Context Protocol (MCP) JSON-RPC 2.0 requests into TeamCity REST API calls through a dedicated protocol handler (internal/mcp/handler.go) that manages session lifecycle, request routing, and response marshaling. The handler implements the full MCP specification including initialization, resource discovery, and tool invocation, converting structured MCP messages into authenticated HTTP requests to TeamCity's /app/rest endpoints.

Implements a production-grade server (internal/server/server.go) supporting three distinct transport mechanisms: HTTP for REST-like access, WebSocket for persistent bidirectional communication, and STDIO for local process integration. The server component handles connection lifecycle management, request routing, and graceful shutdown across all transports, allowing flexible deployment in cloud, desktop, and local development environments.

Implements caching layer for frequently accessed TeamCity data (projects, build types, agents) and periodic health checks to monitor TeamCity server availability. The caching system reduces API calls to TeamCity and improves response latency for resource discovery operations. Health checks detect connectivity issues and enable graceful degradation or alerting when TeamCity becomes unavailable.

Implements full JSON-RPC 2.0 specification compliance in the MCP protocol handler, including proper request/response formatting, error code mapping, and exception handling. The handler validates incoming requests, maps TeamCity API errors to JSON-RPC error codes, and returns properly formatted error responses with descriptive messages. This ensures compatibility with standard JSON-RPC clients and enables clear error communication to AI agents.

Exposes TeamCity resources (projects, build types, builds, agents) as MCP resource URIs (teamcity://projects, teamcity://buildTypes, teamcity://builds, teamcity://agents) that map directly to TeamCity REST API endpoints (/app/rest/projects, /app/rest/buildTypes, etc.). The resource handler fetches and structures data from TeamCity, enabling AI agents to discover and enumerate CI/CD infrastructure without needing to understand TeamCity's API structure.

Implements the trigger_build tool that initiates new TeamCity builds with support for specifying target branch, custom build parameters, and build type selection. The tool accepts buildTypeId, branchName, and properties parameters, constructs a TeamCity build request, and returns build ID and status. This enables AI agents to programmatically start CI/CD pipelines with context-specific configuration.

Implements the cancel_build tool that stops running TeamCity builds by buildId with optional comment annotation. The tool sends a cancellation request to TeamCity's build management API, allowing AI agents to halt in-progress builds and provide context about why the cancellation occurred. Comments are stored in TeamCity's build history for audit and debugging purposes.

Implements the pin_build tool that marks TeamCity builds as 'pinned' to prevent automatic cleanup and retention policy deletion. The tool accepts buildId, pin (boolean), and optional comment parameters, allowing AI agents to preserve important builds (successful releases, baseline builds) from garbage collection. Pinned builds remain accessible for artifact retrieval and historical analysis.

Implements the set_build_tag tool that manages TeamCity build tags through add and remove operations. The tool accepts buildId, tags (array of tag strings to add), and removeTags (array of tag strings to remove) parameters, allowing AI agents to organize and categorize builds with semantic labels. Tags enable filtering, searching, and organizing builds by release version, environment, or custom metadata.

Implements the download_artifact tool that retrieves build artifacts from TeamCity by buildId and artifactPath. The tool constructs artifact download URLs, handles authentication, and streams artifact content to the client. This enables AI agents to access build outputs (binaries, logs, reports) for analysis, deployment, or distribution without requiring direct TeamCity UI access.

Implements the search_builds tool that queries TeamCity builds using multiple filter criteria: status (success/failure/running), branch, user (who triggered the build), and tags. The tool constructs TeamCity REST API search queries with combined filters, returning matching builds with metadata. This enables AI agents to find specific builds based on complex criteria without enumerating all builds.

Manages server configuration through environment variables and configuration files (internal/config/config.go), including TeamCity server URL, authentication credentials, transport settings, and logging configuration. The configuration system supports multiple authentication methods (token-based, username/password) and transport modes (HTTP, WebSocket, STDIO), allowing flexible deployment across different environments without code changes.