# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.20.0] - 2026-08-06

### Deprecated

- **This package is deprecated in favour of CircleCI's hosted MCP server and the CircleCI CLI MCP.** See https://circleci.com/docs/guides/toolkit/circleci-mcp-overview/. This repository will be archived.
- The server now prints a deprecation banner to stderr at startup (both transports), where MCP clients surface it in their logs. There is no opt-out: an off-switch would be adopted by exactly the high-volume operators who most need to migrate, and the server already logs to stderr unconditionally on every start.
- Every tool description now carries the deprecation notice. Tool descriptions enter the model's context, so the assistant relays the notice in conversation — the only channel that reaches users who never open a log file. Almost the entire installed base runs `npx -y @circleci/mcp-server-circleci@latest` from an MCP client config that re-resolves on every start, so the package itself is the only reliable way to reach them; a README notice is not.

Nothing in this release changes tool behaviour, arguments, or output. The deprecation is deliberately non-breaking: a server that stops working gets pinned to the last working version, which strands operators on an unmaintained release rather than moving them forward.

## [0.19.2] - 2026-08-05

### Security

- The remote transport now refuses to start when request authentication is disabled (`REQUIRE_REQUEST_TOKEN=false`, the shared-token mode) *and* it would bind a non-loopback interface — which the default `MCP_BIND_HOST=0.0.0.0` does. That combination served the org's `CIRCLECI_TOKEN` to any peer that could route to the port, with no credential, including `run_pipeline` with arbitrary pipeline config. Operators who genuinely have the port restricted to a trusted network can opt back in with `MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS=true`; a loud warning is logged whenever request auth is off.
- Clarified that the `Host`/`Origin` validation added in 0.17.0 is a DNS-rebinding mitigation and **not** authentication. Both headers are chosen by the caller, so a non-browser client can always satisfy the check by sending an allowed `Host` and omitting `Origin`; it was never an access-control boundary, and the docs no longer read as though `/mcp` is protected by it. Authentication is `REQUIRE_REQUEST_TOKEN` (on by default, returns `401`) or an authenticating proxy. The absent-`Origin` allowance is retained deliberately: requiring the header would break `mcp-remote`, curl and every other non-browser client while stopping no attacker.

### Added

- `MCP_ALLOW_UNAUTHENTICATED_NETWORK_ACCESS` — set to `true` to acknowledge running the shared-token mode on a network-reachable interface. Required in that configuration; ignored when request tokens are required.

## [0.19.1] - 2026-07-28

### Security

- Fixed a path-traversal / arbitrary-file-write vulnerability in the tools that take a filesystem path. `outputDir` (`get_build_failure_logs`, `download_usage_api_data`) and `csvFilePath` (`find_underused_resource_classes`) were used unvalidated, so a caller could create directories and write files anywhere the server process had access (`/etc`, `~/.ssh`, `~/Library/LaunchAgents`, …) or read any file the process could open. Reads and writes are now confined to the server's working directory, the user's home directory and the system temp directory; hidden config directories, `node_modules` and launch-agent directories are rejected. Set `MCP_FILE_OUTPUT_ROOTS` to allow additional locations.
- System directories (`/etc`, `/usr`, `/bin`, `/System`, `/Library`, `%SystemRoot%`, …) are refused unconditionally, independently of the permitted roots. Without this floor, a server launched with a working directory of `/` — which is what a GUI MCP client or a systemd unit with no `WorkingDirectory` gives the process — would have had the entire filesystem as a permitted root, leaving the vulnerability open in that configuration.
- Fixed filename injection in `download_usage_api_data`. The caller-supplied `jobId`, `startDate` and `endDate` were interpolated straight into the output filename, so a value such as `/../../../../tmp/pwned` escaped `outputDir` and gave the caller control of the full written path. Every interpolated value is now reduced to a single safe filename segment, and each write is asserted to land as a direct child of the validated directory.
- File writes now open with `O_NOFOLLOW`. The output filenames are derived from caller input and the temp directory is world-writable, so another local process could pre-plant a symlink at the destination filename and redirect the write to an arbitrary file; validating the directory alone did not prevent this.
- Symlinked directories that resolve outside the permitted roots are rejected, including dangling ones — a symlink that cannot be canonicalised is no longer treated as a not-yet-created directory.
- Error messages no longer include stack traces, the resolved host path, or the list of permitted roots, all of which disclosed the host's filesystem layout to the client. `find_underused_resource_classes` reports only the errno for a failed read.
- `download_usage_api_data` validates `outputDir` before starting an export job instead of on the poll that finds it complete, so a rejected directory no longer consumes a usage export.

### Added

- `MCP_FILE_OUTPUT_ROOTS` — comma-separated list of additional directories that the file-reading/writing tools may use. The working directory, home directory and temp directory are always allowed; system directories can never be allowed. Deployments whose checkout lives outside those roots (`/workspace` in a container, `/srv`, a secondary volume) must set this.

## [0.19.0] - 2026-07-19

### Removed

- Removed the Prompt Workbench toolchain (`create_prompt_template`, `recommend_prompt_template_tests`, `run_evaluation_tests`) — the feature has been shut down.
- Removed the `analyze_diff` tool — it depended on the Circlet backend which has been decommissioned.

## [0.18.0] - 2026-07-17

### Security

- Marked MCP tools as potentially destructive for client confirmation.

## [0.17.0] - 2026-06-26

### Security

- Fixed a DNS-rebinding vulnerability in the remote HTTP transport. The `/mcp` routes now validate the `Host` header against an allowlist (loopback by default) and the `Origin` header when present (absent Origin is allowed — non-browser clients such as `mcp-remote` never send it). Requests with a disallowed `Host` or `Origin` receive `403 Forbidden`. **Breaking for public deployments:** operators must set `MCP_ALLOWED_HOSTS` to the hostname their clients use, or requests will be rejected.

### Added

- `MCP_ALLOWED_HOSTS` — comma-separated list of additional `Host` values to permit on `/mcp` routes (e.g. `my-mcp.example.com`). Loopback is always allowed.
- `MCP_ALLOWED_ORIGINS` — comma-separated list of additional `Origin` values to permit (e.g. `https://my-app.example.com`). Loopback origins are always allowed. Only needed when a browser reaches this server directly.
- `MCP_BIND_HOST` — network interface to bind to (default: `0.0.0.0`, unchanged). Set to `127.0.0.1` to restrict to loopback.

## [0.16.2] - 2026-06-16

### Changed

- npm releases now use trusted publishing (OIDC) instead of a static `NPM_ACCESS_TOKEN`. The publish job exchanges a CircleCI OIDC token for a short-lived npm token via `NPM_ID_TOKEN` (#170)

## [0.16.1] - 2026-06-09

### Security

- Fixed a command injection in the `run_evaluation_tests` tool. The caller-supplied `promptFiles[].fileName` was interpolated unquoted into shell commands inside the generated pipeline config, allowing arbitrary command execution in the CircleCI runner under the server's token. `fileName` is now constrained to `/^[A-Za-z0-9._-]+$/` at the schema boundary and single-quoted at every interpolation site (#169)

### Changed

- Remote HTTP request authentication is now secure by default. `REQUIRE_REQUEST_TOKEN` defaults to required; operators running the shared-token mode must now set `REQUIRE_REQUEST_TOKEN=false` to allow unauthenticated requests. **Breaking** for existing shared-token deployments that relied on no auth (#169)

## [0.16.0] - 2026-06-09

### Added

- Added per-request CircleCI token auth for remote MCP deployments. Remote HTTP servers can accept each developer's CircleCI PAT via `Authorization: Bearer` or `Circle-Token` headers, with an optional `REQUIRE_REQUEST_TOKEN=true` for team deployments and `CIRCLECI_TOKEN` retained as a shared-token fallback (#165)
- Added optional `outputDir` parameter to the `get_build_failure_logs` tool to write full logs to a file (#162)

## [0.15.1] - 2026-04-21

### Fixed

- Fixed `labels` schema parsing in deploy environments and components responses. Labels are now correctly parsed as `{ key, value }` objects instead of strings, which restores `list_component_versions` when resolving environments or components that carry labels.

## [0.15.0] - 2026-03-25

### Added

- Added `listArtifacts` tool to list artifacts for a CircleCI job (thank you @nadav-dav)

### Fixed

- Removed non-spec `tools.list` capability advertisement that caused compatibility issues with some MCP clients (thank you @stig)

## [0.14.2] - 2026-02-20

### Fixed

- Fixed bug in `download_usage_api_data` tool where `endDate` could resolve to a future time
- Fixed bug in `download_usage_api_data` tool where date parameters could be passed in ISO 8601 duration format, which chrono-node cannot parse

## [0.14.1] - 2025-09-17

### Fixed

- Output log messages to stderr instead of stdout, following MCP server specification. This avoids MCP server startup issues in some agents, such as Warp. Fixes #125

## [0.14.0] - 2025-08-11

### Added

- Added `download_usage_api_data` tool to start and retrieve CircleCI usage export jobs

- Added `find_underused_resource_classes` tool to analyze usage CSV for underused resource classes (default threshold 40%)

## [0.13.0] - 2025-08-05

### Added

- Added `listComponentVersions` tool to list all versions for a CircleCI component

### Changed

- Simplified `runRollbackPipeline` tool by moving part of its inner logic to `listComponentVersions`.

## [0.12.2] - 2025-08-01

### Added

- Added support for rerunning workflow in `runRollbackPipeline` when no rollback pipeline is defined.

## [0.12.1] - 2025-07-30

### Fixed

- Fixed `runRollbackPipeline` tool to not suggest other projects

## [0.12.0] - 2025-07-29

### Added

- Added `runRollbackPipeline` tool to run a rollback pipeline

## [0.11.4] - 2025-07-28

### Fixed

- Remove `tool/` prefix from tool list entries, this was breaking tool name resolution in some MCP clients.

## [0.11.3] - 2025-07-24

### Changed

- Make the diff reviewer tool work with other IDE based rule systems.

## [0.11.2] - 2025-06-20

### Added

- Add `file` property to the `RuleReviewSchema` to align with updated endpoint

## [0.11.1] - 2025-06-18

### Fixed

- Fixed bug in `get_flaky_tests` tool where unrelated tests were being returned
- Fixed bug in `get_flaky_tests` tool where if the output directory cannot be created the tool would respond with an error. We now throw in that case, which makes us fallback to the text output.

## [0.11.0] - 2025-06-18

### Fixed

- Fixed bug in `get_flaky_tests` tool where the same job number was being fetched multiple times
- Fixed bug in `get_flaky_tests` where the output directory was not being created when using file output mode

## [0.10.2] - 2025-06-18

### Added

- Add `speedMode` and `filterBy` parameters to the `analyze_diff` tool

## [0.10.1] - 2025-06-17

### Fixed

- Add a .gitignore file to the flaky-tests-output directory to ignore all files in the directory

## [0.10.0] - 2025-06-17

### Added

- Added `USE_FILE_OUTPUT` environment variable to `get_flaky_tests` tool
  - When set to `true`, the tool will write flaky tests to files in the `./flaky-tests-output` directory instead of returning the results in the response
  - The tool will return the file paths of the written files in the response

## [0.9.2] - 2025-06-17

### Added

- Anthropic support on prompt eval script (w. auto-detection for OpenAI and Anthropic models)
- Added `temperature` parameter support to prompt template tools
  - Enhanced `create_prompt_template` tool with configurable temperature setting
  - Enhanced `recommend_prompt_template_tests` tool with temperature parameter
  - Default temperature value set to 1.0 for consistent prompt template generation

### Updated

- Updated default model from `gpt-4o-mini` to `gpt-4.1-mini` for prompt template tools
- Enhanced evaluation script dependencies for improved compatibility
  - Updated `deepeval` to version 3.0.3+ (from 2.8.2+)
  - Updated `openai` to version 1.84.0+ (from 1.76.2+)
  - Added `anthropic` version 0.54.0+ for Anthropic model support
  - Updated `PyYAML` to version 6.0.2+

## [0.9.1] - 2025-06-12

### Added

- Added `analyze_diff` tool to analyze git diffs against cursor rules to identify rule violations
  - Evaluates code changes against repository coding standards and best practices
  - Provides detailed violation reports with confidence scores and explanations
  - Supports both staged and unstaged changes and all changes analysis
  - Returns actionable feedback for maintaining code quality consistency

## [0.9.0] - 2025-06-03

### Added

- Added `run_evaluation_tests` tool to run evaluation tests on CircleCI pipelines
  - Support for running prompt template evaluation tests in CircleCI
  - Integration with prompt template files from `./prompts` directory
  - Dynamic CircleCI configuration generation for evaluation workflows
  - Support for multiple prompt files with automatic parallelism configuration
  - Compatible with both JSON and YAML prompt template formats
  - Comprehensive error handling and validation for prompt template files
- Enhanced `runPipeline` API to support custom configuration content
  - Added `configContent` parameter to override default pipeline configuration
  - Enables dynamic pipeline configuration for specialized use cases

## [0.8.1] - 2025-05-28

### Added

- Enhanced prompt template tools with support for existing codebase prompts
  - Added `promptOrigin` parameter to distinguish between new requirements and existing codebase prompts
  - Added `model` parameter to specify target model for testing (defaults to gpt-4o-mini)
  - Enhanced documentation and examples for prompt template creation
  - Added integration guidance for codebase-sourced prompts
  - Improved prompt templates file location, naming conventions, and structure

## [0.8.0] - 2025-05-22

### Added

- Added `rerun_workflow` tool to rerun a workflow from its start or from the failed job

## [0.7.1] - 2025-05-14

### Updated

- Updated `get_build_failure_logs`, `get_job_test_results`, and `get_latest_pipeline_status` tools to require a branch parameter when using projectSlug option

## [0.7.0] - 2025-05-13

### Added

- Added `list_followed_projects` tool to list all projects that the user is following on CircleCI

## [0.6.2] - 2025-05-13

### Fixed

- Fixed `get_job_test_results` tool to filter tests by result when a job number is provided

## [0.6.1] - 2025-05-13

### Updated

- Updated `get_build_failure_logs` tool to support legacy job url format like `https://circleci.com/gh/organization/project/123`

## [0.6.0] - 2025-05-13

### Added

- Added `filterByTestsResult` parameter to `get_job_test_results` tool
  - Filter the tests by result
  - Support for filtering by `failure` or `success`

## [0.5.1] - 2025-05-12

### Added

- Fix handling of legacy job url format in tools
- Fix handling of pagination of test results when no test results are found

## [0.5.0] - 2025-05-09

### Added

- Added `run_pipeline` tool to run a pipeline
  - Support for triggering pipelines using project URL or local git repository context
  - Branch detection from URLs or local git context
  - Handles multiple pipeline definitions with interactive selection
  - Provides direct link to monitor pipeline execution

## [0.4.4] - 2025-05-08

### Fixed

- Fixed project detection and pipeline number extraction from URLs with custom server domains

## [0.4.3] - 2025-05-08

### Fixed

- Fixed project detection when branch is provided in URL but not in params
- Improved error handling for failed pipeline workflow fetches
- Enhanced error messaging when project is not found or inputs are missing

## [0.4.2] - 2025-05-08

### Improvements

- Enhanced prompt template file structure and organization for consistency
  - Added standardized file naming convention for prompt templates
  - Implemented structured JSON format with required fields (name, description, version, template, contextSchema, tests, sampleInputs, etc.)
  - Added support for test case naming in Title Case format
  - Improved documentation requirements for prompt templates

## [0.4.1] - 2025-05-05

### Added

- Update project detection to correctly paginate the followed projects

## [0.4.0] - 2025-04-30

### Added

- Added `get_job_test_results` tool to retrieve and analyze test metadata from CircleCI jobs
  - Support for retrieving test results using job, workflow, or pipeline URLs
  - Support for retrieving test results using local git repository context
  - Displays comprehensive test result summary (total, successful, failed)
  - Provides detailed information for failed tests including name, class, file, error messages, and runtime
  - Lists successful tests with timing information
  - Offers actionable guidance when no test results are found
  - Includes documentation link to help users properly configure test metadata collection

## [0.3.0] - 2025-04-30

### Added

- Added `get_latest_pipeline_status` tool to get the latest pipeline status
  - Support for both project URL and local git repository context
  - Displays all workflows within the latest pipeline
  - Provides formatted details including pipeline number, workflow status, duration, and timestamps

## [0.2.0] - 2025-04-18

### Added

- Added `create_prompt_template` tool to help generate structured prompt templates

  - Converts feature requirements into optimized prompt templates
  - Generates context schema for input parameters
  - Enables building robust AI-powered features
  - Integrates with prompt template testing workflow

- Added `recommend_prompt_template_tests` tool for prompt template validation
  - Creates diverse test scenarios based on templates
  - Generates test cases with varied parameter combinations
  - Helps identify edge cases and potential issues
  - Ensures consistent AI responses across inputs

## [0.1.10] - 2025-04-17

### Fixed

- Fixed rate limiting issues when fetching job logs and flaky tests (#32)
  - Implemented `rateLimitedRequests` utility for controlled API request batching
  - Added configurable batch size and interval controls
  - Improved error handling for rate-limited responses
  - Added progress tracking for batch operations
  - Applied rate limiting fix to both job logs and flaky test detection
  - Enhanced reliability of test results retrieval

### Improvements

- Enhanced HTTP client configuration flexibility
  - Configurable base URL through environment variables
  - Better support for different CircleCI deployment scenarios
  - Streamlined client initialization process
- Added output text truncation
  - Prevents response overload by limiting output size
  - Includes clear warning when content is truncated
  - Preserves most recent and relevant information

## [0.1.9] - 2025-04-16

### Added

- Added support for API subdomain configuration in CircleCI client
  - New `useAPISubdomain` option in HTTP client configuration
  - Automatic subdomain handling for API-specific endpoints
  - Improved support for CircleCI enterprise and on-premise installations
- Added `config_helper` tool to assist with CircleCI configuration tasks
  - Support for validating .circleci/config.yml files
  - Integration with CircleCI Config Validation API
  - Detailed validation results and configuration recommendations
  - Helpful error messages and best practice suggestions

## [0.1.8] - 2025-04-10

### Fixed

- Fixed bug in flaky test detection where pipelineNumber was incorrectly used instead of projectSlug when URL not provided

### Improvements

- Consolidated project slug detection functions into a single `getPipelineNumberFromURL` function with enhanced test coverage
- Simplified build logs tool to use only `projectURL` parameter instead of separate pipeline and job URLs
- Updated tool descriptions to provide clearer guidance on accepted URL formats
- Removed redundant error handling wrapper

## [0.1.7] - 2025-04-10

### Added

- Added `find_flaky_tests` tool to identify and analyze flaky tests in CircleCI projects
  - Support for both project URL and local git repository context
  - Integration with CircleCI Insights API for flaky test detection
  - Integration with CircleCI Tests API to fetch detailed test execution results
  - Formatted output of flaky test analysis results with complete test logs

## [0.1.6] - 2025-04-09

### Added

- Added User-Agent header to CircleCI API requests

## [0.1.5] - 2025-04-08

### Added

- Support for configurable CircleCI base URL through `CIRCLECI_BASE_URL` environment variable

## [0.1.4] - 2025-04-08

### Fixed

- Handle missing job numbers in CircleCI API responses by making job_number optional in schema
- Skip jobs without job numbers when fetching job logs instead of failing

## [0.1.3] - 2025-04-04

### Added

- Improved schema validation and output formatting for job information

## [0.1.2] - 2025-04-04

### Fixed

- More permissive schema validation for CircleCI API parameters
- Allow optional parameters in API requests

### Documentation

- Updated documentation around package publishing
- Removed note about package not being published

## [0.1.1] - 2025-04-04

### Fixed

- Non functional fixes

## [0.1.0] - 2025-04-04

Initial release of the CircleCI MCP Server, enabling natural language interactions with CircleCI functionality through MCP-enabled clients.

### Added

- Core MCP server implementation with CircleCI integration

  - Support for MCP protocol version 1.8.0
  - Robust error handling and response formatting
  - Standardized HTTP client for CircleCI API interactions

- CircleCI API Integration

  - Support for both CircleCI API v1.1 and v2
  - Comprehensive API client implementation for Jobs, Pipelines, and Workflows
  - Private API integration for enhanced functionality
  - Secure token-based authentication

- Build Failure Analysis Tool

  - Implemented `get_build_failure_logs` tool for retrieving detailed failure logs
  - Support for both URL-based and local project context-based queries
  - Intelligent project detection from git repository information
  - Formatted log output with job names and step-by-step execution details

- Development Tools and Infrastructure
  - Comprehensive test suite with Vitest
  - ESLint and Prettier configuration for code quality
  - TypeScript configuration for type safety
  - Development workflow with MCP Inspector support
  - Watch mode for rapid development

### Security

- Secure handling of CircleCI API tokens
- Masked sensitive data in log outputs
- Proper error handling to prevent information leakage