# codescene-mcp-server [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/codescene-oss/codescene-mcp-server  
**GitHub Stars:** 78  
**npm Downloads (last month):** 18095  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/codescene-mcp-server

## Description
An MCP server that provides CodeScene Code Health analysis tools.

## Tools
Capabilities this server exposes over MCP:

- **analyze_change_set** — Run a branch-level Code Health review for all files that differ between
current HEAD and base_ref.

When to use:
    Use this as a local PR pre-flight check before opening a pull
    request, so regressions are caught across the full change set.

Limitations:
    - Requires a valid git repository path.
    - base_ref must exist and be resolvable by git in that repository.
    - Reviews only files that differ from base_ref.
    - Output is JSON text from the CLI command.

The result can be used to decide whether to refactor before creating
or updating a pull request.

Returns:
    A JSON object containing:
      - quality_gates: the central outcome, summarizing whether the change
        set passes or fails Code Health thresholds ("passed" or "failed").
      - metadata: scope and coverage details from the CLI, including `status` plus file counts such as `checked-file-count`. Use this to distinguish an empty `results` array caused by checked files with no degradations from one caused by no applicable branch changes.
      - results: an array of objects for each affected file with:
          - name: the name of the file whose Code Health is impacted.
          - verdict: "improved", "degraded", "stable", or "unknown".
          - findings: an array describing improvements/degradation for each code smell.

Setup hints:
    If the result contains `codescene_setup_hint`, do not mention that field.
    Follow its `message`: briefly explain the benefit, ask permission to add
    the suggested repository instructions, and wait before editing files.

On failure:
    If this tool returns an error (e.g., the CLI cannot run, or base_ref
    cannot be resolved by git), run the verify_installation tool to diagnose the
    cause, then report the failing checks and how to fix them.

Example:
    Compare against base_ref="main" for git_repository_path="/repo" and
    fail the local PR check if any file verdict is "degraded".
- **code_health_refactoring_business_case** — Generate a data-driven business case for refactoring a source file.

When to use:
    Use this tool to justify refactoring investment with quantified
    predictions tied to the file's current Code Health.

Limitations:
    - Estimates are model-based projections, not guarantees.
    - Evaluates one file at a time.
    - Requires an analyzable source file.

Returns:
    A JSON object with:
        - scenario: Recommended target Code Health level.
        - optimistic_outcome: Upper bound estimate for improvements
          in development speed and defect reduction.
        - pessimistic_outcome: Lower bound estimate for improvements.
        - confidence_interval: The optimistic to pessimistic range,
          representing a 90% confidence interval for the expected impact.

On failure:
    If this tool returns an error (e.g., the CLI cannot run, or the file
    cannot be analyzed), run the verify_installation tool to diagnose the
    cause, then report the failing checks and how to fix them.

Example:
    Call with file_path="/repo/src/service.py" and use the optimistic
    and pessimistic outcomes to frame a refactoring proposal.
- **code_health_review** — Review the Code Health of a single source file and return a detailed
CLI review output that includes the score and code smell findings.

When to use:
    Use this tool when you need actionable maintainability diagnostics
    for one file (not just the score).

Limitations:
    - Analyzes one file at a time.
    - Requires a supported source file.
    - Returns CLI review text, not a normalized JSON schema.

Returns:
    A review string from the CodeScene CLI. The output typically
    includes a Code Health score and code smell details to explain
    why the score is high or low.

    The Code Health scores are interpreted as:
      * Optimal Code: a Code Health 10.0 is optimized for both human and AI comprehension
      * Green Code: high quality with a score of 9.0-9.9
      * Yellow Code: problematic technical debt with a score of 4.0-8.9
      * Red Code: severe technical debt, maintainability issues, and expensive onboarding with a score of 1.0-3.9

Setup hints:
    If the result contains `codescene_setup_hint`, do not mention that field.
    Follow its `message`: briefly explain the benefit, ask permission to add
    the suggested repository instructions, and wait before editing files.

On failure:
    If this tool returns an error (e.g., the CLI cannot run, or Code Health
    cannot be computed), run the verify_installation tool to diagnose the
    cause, then report the failing checks and how to fix them.

Example:
    Call with file_path="/repo/src/app.py" and summarize the returned
    smells into prioritized refactoring actions.
- **code_health_score** — Calculate the Code Health score for a single source file.
The tool returns one numeric score from 10.0 (optimal) to 1.0 (worst).

When to use:
    Use this tool for quick triage, ranking files by maintainability,
    or checking whether a refactoring improved file-level quality.

Limitations:
    - Analyzes one file at a time.
    - Returns only the score summary, not the full smell breakdown.
    - Requires a supported source file.

Returns:
    A string in the format "Code Health score: <score>".

    The Code Health scores are interpreted as:
      * Optimal Code: Code Health 10.0 optimized for human and AI comprehension
      * Green Code: high quality with a score of 9.0-9.9
      * Yellow Code: problematic technical debt with a score of 4.0-8.9
      * Red Code: severe technical debt with a score of 1.0-3.9

On failure:
    If this tool returns an error (e.g., the CLI cannot run, or the score
    cannot be computed), run the verify_installation tool to diagnose the
    cause, then report the failing checks and how to fix them.

Example:
    Call with file_path="/repo/src/module.py" and compare the score
    before and after a refactoring.
- **code_ownership_for_path** — Find the owner or owners of a specific path in a project.

When to use:
    Use this tool to identify likely reviewers or domain experts for
    code reviews and technical questions about a file or directory.

Limitations:
    - Requires a valid project_id.
    - Uses the latest project analysis data available in CodeScene.
    - If no matching ownership data is found, an empty JSON array is returned.

Returns:
    A list of owners and their paths that they own. The name of the owner who can be responsible
    for code reviews or inquiries about the file and a link to the CodeScene System Map page filtered
    by the owner. Explain that this link can be used to see more details
    about the owner's contributions and interactions within the project.
    You MUST always show a link after every owner. Show resulting data in a Markdown
    table with columns: Owner, Key Areas, Link.

On failure:
    If this tool returns an error (e.g., the CodeScene API cannot be
    reached, or the access token is missing/invalid), run the
    verify_installation tool to diagnose the cause, then report the
    failing checks and how to fix them.

Example:
    Call with project_id=42 and path="/repo/src/service.py", then
    present each owner row with its corresponding system-map link.
- **download_skill** — Download a single skill to a local directory.

When to use:
    Use this tool to install a specific skill into your local
    skills directory (e.g., ~/.claude/skills/).

Limitations:
    - By default, refuses to overwrite existing skills.
    - Set overwrite=true to replace an existing skill.
    - Creates the destination directory if it does not exist.

Returns:
    A confirmation message with the path where the skill was written.

Example:
    Call with skill_name="safeguarding-ai-generated-code" and
    destination_dir="~/.claude/skills" to install the skill.
- **explain_code_health** — Explains CodeScene's Code Health metric for assessing code quality and maintainability for both human devs and AI.

When to use:
    Use this tool when a user asks what Code Health means, how scores are
    interpreted, or why Code Health matters in day-to-day development.

Limitations:
    - Returns static documentation text from this MCP server package.
    - Does not analyze a specific repository or file.

Returns:
    Markdown content explaining the Code Health model and core concepts.

Example:
    Call this tool, then summarize the returned Markdown into a short
    explanation tailored to the user's current question.
- **explain_code_health_productivity** — Describes how to build a business case for Code Health improvements.
Covers empirical data on how healthy code lets you ship faster with
fewer defects.

When to use:
    Use this tool when a user asks for ROI, productivity impact, or
    management-facing framing for refactoring investments.

Limitations:
    - Returns static documentation text from this MCP server package.
    - Does not compute project-specific forecasts.

Returns:
    Markdown content describing productivity and defect-risk implications
    of improving Code Health.

Example:
    Call this tool and extract 2-3 evidence-based points to support a
    proposal for incremental refactoring.
- **get_config** — Read current CodeScene MCP Server configuration values.

When to use:
    Use this tool to discover available configuration keys, inspect
    effective values, and understand where each value comes from.

Limitations:
    - Returns JSON text only; callers must format it for display.
    - Sensitive values (tokens) are masked.
    - Effective values can be overridden by client-provided env vars.

When called without a key, lists every available configuration
option together with its current effective value, the source of
that value (environment variable vs. config file), and a short
description.

When called with a specific key, returns details for that option
only. Sensitive values (tokens) are masked in the output.

Returns:
    A JSON string. When querying a single key, the object has:
    key, env_var, value, source, description, aliases, and
    docs_url. When listing all, the object has: config_dir and
    options (array of the same shape). Use the aliases array
    to match user intent to the correct key. Present the data
    clearly and always include docs_url links.

Example:
    Call with key="access_token" to inspect one setting, or
    call without key to list all configurable options.
- **get_skill_manifest** — Get the file manifest for a specific skill.

When to use:
    Use this tool to inspect what files a skill contains,
    their sizes, and SHA256 hashes before downloading.

Limitations:
    - Requires a valid skill name from list_skills.

Returns:
    A JSON manifest with the skill name and an array of files,
    each with path, size in bytes, and sha256 hash.

Example:
    Call with skill_name="safeguarding-ai-generated-code" to
    see the manifest, then use download_skill to install it.
- **list_skills** — List all available skills embedded in this MCP server.

When to use:
    Use this tool to discover what skills are available for
    download or inspection.

Limitations:
    - Returns only skills embedded at compile time.
    - Does not scan external skill directories.

Returns:
    A formatted list of skill names with their descriptions.

Example:
    Call this tool to see all available skills, then use
    download_skill or sync_skills to install them locally.
- **list_technical_debt_goals_for_project** — Lists the technical debt goals for a project.

When to use:
    Use this tool to see all files in a project that currently have
    explicit technical debt goals in CodeScene.

Limitations:
    - Requires a valid project_id.
    - Returns goal data from the latest available analysis.
    - Includes only files with non-empty goals.

Returns:
    A JSON object with two fields:
    - `data`: an array of objects each containing the path of a file and its goals.
    - `link`: a URL to the CodeScene Code Biomarkers page for the project.

    Show the goals for each file in a structured format that is easy to read and explain
    the goal description for each file. It also includes a description, please include that in your output.
    Always include the `link` in the output and explain that more details about the
    technical debt goals can be found on that page.

On failure:
    If this tool returns an error (e.g., the CodeScene API cannot be
    reached, or the access token is missing/invalid), run the
    verify_installation tool to diagnose the cause, then report the
    failing checks and how to fix them.

Example:
    Call with project_id=42 and summarize each file's goals with the
    biomarkers link for deeper inspection.
- **list_technical_debt_goals_for_project_file** — Lists the technical debt goals for a specific file in a project.

When to use:
    Use this tool when you need goal details for one file before
    planning targeted refactoring work.

Limitations:
    - Requires a valid project_id.
    - Returns data from the latest available analysis only.
    - A file may return zero goals, which is a valid outcome.

Returns:
    A JSON object with two fields:
    - `data`: an array containing the goals for the specified file.
    - `link`: a URL to the CodeScene Code Biomarkers page for the specific file.

    Show the goals in a structured format that is easy to read and explain
    the goal description. It also includes a description, please include that in your output.
    Always include the `link` in the output and explain that more details about the
    technical debt goals can be found on that page.

On failure:
    If this tool returns an error (e.g., the CodeScene API cannot be
    reached, or the access token is missing/invalid), run the
    verify_installation tool to diagnose the cause, then report the
    failing checks and how to fix them.

Example:
    Call with file_path="/repo/src/module.py" and project_id=42, then
    use the goals and link to propose file-level improvements.
- **list_technical_debt_hotspots_for_project** — Lists the technical debt hotspots for a project.

When to use:
    Use this tool to identify high-impact technical debt hotspots across
    a project and prioritize refactoring targets.

Limitations:
    - Requires a valid project_id.
    - Returns hotspots from the latest available project analysis.
    - Uses the API's hotspot filtering and pagination behavior.

Returns:
    A JSON object with two fields:
    - `data`: an array of objects each containing the path of a file, code health score, revisions count and lines of code count.
    - `link`: a URL to the CodeScene technical debt hotspots page for the project.

    Describe the hotspots for each file in a structured format that is easy to read and explain.
    It also includes a description, please include that in your output.
    Always include the `link` in the output and explain that the user can find more
    detailed information about each hotspot on that page.

On failure:
    If this tool returns an error (e.g., the CodeScene API cannot be
    reached, or the access token is missing/invalid), run the
    verify_installation tool to diagnose the cause, then report the
    failing checks and how to fix them.

Example:
    Call with project_id=42 and rank returned hotspots by code health
    and revision frequency before proposing refactoring work.
- **list_technical_debt_hotspots_for_project_file** — Lists the technical debt hotspots for a specific file in a project.

When to use:
    Use this tool to inspect hotspot metrics for one file before
    deciding if it should be a refactoring candidate.

Limitations:
    - Requires a valid project_id.
    - Returns at most one hotspot object for the filtered file path.
    - If no hotspot exists for the file, returns an empty hotspot object.

Returns:
    A JSON object with two fields:
    - `data`: an array containing the code health score, revisions count and lines of code count for the specified file.
    - `link`: a URL to the CodeScene technical debt hotspots page for the project.

    Describe the hotspot in a structured format that is easy to read and explain.
    It also includes a description, please include that in your output.
    Always include the `link` in the output and explain that the user can find more
    detailed information about each hotspot on that page.

On failure:
    If this tool returns an error (e.g., the CodeScene API cannot be
    reached, or the access token is missing/invalid), run the
    verify_installation tool to diagnose the cause, then report the
    failing checks and how to fix them.

Example:
    Call with file_path="/repo/src/module.py" and project_id=42. If
    hotspot is empty, report that the file is not currently a hotspot.
- **login** — Sign in to CodeScene using OAuth.

When to use:
    Use this tool when no CS_ACCESS_TOKEN env to authenticate. Can be used during read-only mode. If the browser cannot be opened automatically, the URL
    is printed so the user can open it manually.

Limitations:
    - Not needed when CS_ACCESS_TOKEN is already set.
    - Requires the embedded CLI to be available.
    - Waits up to 2 minutes for the user to complete the browser flow.
    - For on-prem instances, configure CS_ONPREM_URL before calling this tool.

Returns:
    A success message when signed in, or an error describing the failure.
- **logout** — Sign out of CodeScene OAuth.

When to use:
    Use this tool to clear the stored OAuth session (CLI credentials and MCP OAuth config).

Limitations:
    - Does not remove CS_ACCESS_TOKEN / a Personal Access Token; clear that separately via set_config or your MCP client environment.
    - Requires the embedded CLI to be available for a full CLI logout; local OAuth config is still cleared if the CLI call fails.

Returns:
    A success message when signed out, noting if a PAT remains configured.
- **pre_commit_code_health_safeguard** — Review all modified and staged files in a repository and report
Code Health degradations before commit.

When to use:
    Use this tool as a pre-commit safeguard on local changes to catch
    regressions and code smells before creating a commit.

Limitations:
    - Requires a valid git repository path.
    - Evaluates current local modifications/staged changes only.
    - Output is JSON text from the CLI command.

Returns:
    A JSON object containing:
      - quality_gates: the central outcome, summarizing whether the commit passes or fails Code Health thresholds for the checked files.
      - metadata: scope and coverage details from the CLI, including `status` plus file counts such as `checked-file-count`. Use this to distinguish an empty `results` array caused by clean checked changes from one caused by no applicable changes.
      - results: an array of objects for each file with:
          - name: the name of the file whose Code Health is impacted (positively or negatively).
          - verdict: `improved`, `degraded`, `stable`, or `unknown`.
          - findings: an array describing improvements/degradation for each code smell.

Setup hints:
    If the result contains `codescene_setup_hint`, do not mention that field.
    Follow its `message`: briefly explain the benefit, ask permission to add
    the suggested repository instructions, and wait before editing files.

On failure:
    If this tool returns an error (e.g., the CLI cannot run, or the git
    repository cannot be analyzed), run the verify_installation tool to
    diagnose the cause, then report the failing checks and how to fix them.

Example:
    Run on git_repository_path="/repo" and block commit preparation if
    any quality gate fails.
- **rules_config_list_thresholds** — List the default Code Health thresholds for a programming language.
Thresholds define what Code Health issues such as "Complex Method" or
"Large Method" mean for a given language, and are the values you can
override in a code-health-rules.json file.

When to use:
    Use this tool to discover the built-in threshold names and default
    values for a language before overriding any of them with
    rules_config_set_threshold.

Limitations:
    - Local, filesystem-only operation. No CodeScene API or access token
      is required.
    - Requires a supported language name (e.g., Python, JavaScript, Java,
      C#).
    - config_path, when provided, must be an absolute path; the returned
      values then reflect that file's overrides. Without it, built-in
      defaults are shown.

Returns:
    A JSON object keyed by rule-set name, each containing a `thresholds`
    array of `{ name, value }` entries.

On failure:
    If the language is not supported, the error message lists supported
    languages. Retry with a valid language name.

Example:
    Call with language="Python" and present the threshold names and
    values the user can customize.
- **rules_config_set_rule** — Enable or disable a Code Health rule in a code-health-rules.json file.
Disabling a rule removes its impact from CodeScene's Code Health score;
enabling it restores the default behavior.

When to use:
    Use this tool to turn a specific Code Health rule (e.g., "Complex
    Method") on or off for a repository. This edits the rules file on
    disk.

Limitations:
    - Local, filesystem-only operation that WRITES to the rules file. No
      CodeScene API or access token is required.
    - rule_name must be a supported Code Health rule name.
    - config_path, when provided, must be an absolute path. Without it,
      the CLI edits .codescene/code-health-rules.json in the current git
      repository.
    - matching_content_path is required only when the file defines
      multiple rule sets; it selects which one to edit.

Returns:
    A confirmation message naming the rule, its new enabled/disabled
    state, and the rule set that was edited.

On failure:
    If the rule name is unknown the error suggests valid names; if
    multiple rule sets exist without a selector the error lists the
    available selectors. Retry with the corrected input.

Example:
    Call with rule_name="Complex Method" and enabled=false to disable the
    Complex Method rule, then confirm the change to the user.
- **rules_config_set_threshold** — Set a Code Health threshold value in a code-health-rules.json file.
Thresholds tune the sensitivity of Code Health issues (for example, the
number of lines at which a function is flagged as a "Large Method").

When to use:
    Use this tool to override a specific Code Health threshold for a
    repository. This edits the rules file on disk. Use
    rules_config_list_thresholds first to find valid threshold names.

Limitations:
    - Local, filesystem-only operation that WRITES to the rules file. No
      CodeScene API or access token is required.
    - threshold_name must be a supported Code Health threshold name.
    - value must be a positive integer.
    - config_path, when provided, must be an absolute path. Without it,
      the CLI edits .codescene/code-health-rules.json in the current git
      repository.
    - matching_content_path is required only when the file defines
      multiple rule sets; it selects which one to edit.

Returns:
    A confirmation message naming the threshold, its new value, and the
    rule set that was edited.

On failure:
    If the threshold name is unknown or the value is not a positive
    integer, the error message explains the problem. Retry with corrected
    input.

Example:
    Call with threshold_name="function_lines_of_code_warning" and
    value=120 to raise the Large Method warning threshold, then confirm
    the change.
- **rules_config_validate** — Validate a Code Health rules configuration file (code-health-rules.json).
This is the file that customizes CodeScene's Code Health analysis by
adjusting rule weights and thresholds.

When to use:
    Use this tool after creating or editing a Code Health rules file to
    confirm it is well-formed before relying on it for analysis.

Limitations:
    - Local, filesystem-only operation. No CodeScene API or access token
      is required.
    - config_path, when provided, must be an absolute path.
    - Without config_path, the CLI looks for
      .codescene/code-health-rules.json in the current git repository.

Returns:
    A JSON object with:
        - status: "ok" when the configuration is valid.
        - summary: A human-readable count of rule sets, rule overrides,
          and threshold overrides.

On failure:
    If the file is missing or malformed, the error message describes the
    problem and a suggested remedy. Fix the file (or supply a valid
    config_path) and validate again.

Example:
    Call with config_path="/repo/.codescene/code-health-rules.json" and
    report whether the Code Health rules configuration is valid.
- **select_project** — Lists all projects for an organization for selection by the user.
The user can select the desired project by either its name or ID.

When to use:
    Use this tool before project-scoped API tools so the user can pick
    the project context explicitly.

Limitations:
    - If default_project_id is configured, the server returns that
      project and selection is effectively locked.

Returns:
    A JSON object with the project name and ID, formatted in a Markdown table
    with the columns "Project Name" and "Project ID". If the output contains a
    `description` field, it indicates that a default project is configured
    (`default_project_id`), and the user cannot select a different project.
    Explain this to the user.

    Additionally, a `link` field is provided to guide the user to the
    Codescene projects page where the user can find more detailed information about each project.
    Make sure to include this link in the output, and explain its purpose clearly.

On failure:
    If this tool returns an error (e.g., the CodeScene API cannot be
    reached, or the access token is missing/invalid), run the
    verify_installation tool to diagnose the cause, then report the
    failing checks and how to fix them.

Example:
    Call without arguments. If default_project_id is configured,
    explain that the returned project is fixed unless that config is changed via set_config.
- **set_config** — Write a CodeScene MCP Server configuration value.

When to use:
    Use this tool to persist or remove server configuration values
    without editing config files manually.

Limitations:
    - Unknown keys are rejected.
    - Client-level environment variables may still override runtime
      behavior even after saving a config value.
    - Some changes may require an MCP client restart.

Persists the value to the config file and applies it to the
running session immediately. To remove a value, pass an empty
string as the value.

If the same setting is also defined as an environment variable in
your MCP client configuration (e.g. VS Code settings or Claude
Desktop config), the environment variable takes precedence at
runtime.

Call get_config first (without a key) to discover available keys,
their aliases, and docs_url links.

Returns:
    A JSON string with status ("saved" or "removed"), key,
    config_dir, and optional warning, restart_required, and
    docs_url fields. Present the data clearly and always
    include docs_url links.

Example:
    Call with key="access_token" and value="..." to save,
    or pass an empty value to remove that key from config.
- **show_mcp_usage_overview** — Display an overview of the authenticated user's CodeScene MCP safeguard usage.

When to use:
    Use this tool when a user asks about their MCP usage, safeguard activity,
    prevented Code Health degradations, or development impact.

Limitations:
    - Requires authenticated CodeScene API access.
    - Not available with a standalone license.
    - Lifetime metrics come from aggregated safeguard insights.
    - Recent work metrics cover only the latest 250 MCP events.
    - Availability on-prem depends on the CodeScene version supporting the
      MCP safeguard insights and outcomes endpoints.

Returns:
    A usage overview with Code Health uplifts, prevented degradations, the
    scope of recent work, and most-used tools. The result includes an MCP Apps
    dashboard and a Markdown representation of the same data.

On failure:
    If this tool returns an authentication, connectivity, or API error, run
    verify_installation and report the failing checks and how to fix them.

Example:
    Call this tool when the user asks, "Show me my CodeScene MCP usage."
- **switch_account** — Switch the active CodeScene Cloud OAuth account, or list accounts the user can switch to.

When to use:
    Use this tool when the user belongs to multiple Cloud accounts and needs to
    change which account the MCP server uses. Prefer this over set_config(account_id)
    alone — changing the pin without switch_account does not retarget the active
    OAuth session. If the user has not named an account, call this tool without
    arguments first so they can pick from the list.

Limitations:
    - Cloud OAuth only; does not apply to PAT / CS_ACCESS_TOKEN auth or on-prem.
    - Reuses a stored CLI credential slot when available; otherwise opens a browser
      for interactive login into that account (`authenticated` is false).
    - Not available in Docker (no OAuth browser flow).

Returns:
    With no arguments: a JSON object with an `accounts` array. Format it as a
    Markdown table with columns "Account Name", "Account ID", "Type", "Role",
    and "Signed in on this machine". Mark the row where `current` is true as the
    active account. Then ask the user which account to use and call this tool again
    with `name` or `account_id`.
    With `name` (display name or org slug) or `account_id`: a success message with
    the active account_id, or an error. If `name` is ambiguous or not found, the
    response includes the account list so you can ask the user to pick one.

Example:
    Call without arguments to list accounts. To switch, pass name="CodeScene Showcase"
    or account_id=11. If the user already named the account, pass name directly.
- **sync_skills** — Download all available skills to a local directory.

When to use:
    Use this tool to install every embedded skill into your
    local skills directory at once.

Limitations:
    - By default, skips skills that already exist locally.
    - Set overwrite=true to replace all existing skills.
    - Creates the destination directory if it does not exist.

Returns:
    A summary showing how many skills were downloaded and how
    many were skipped (if any already existed).

Example:
    Call with destination_dir="~/.claude/skills" to install
    all skills. Use overwrite=true to force-update them.
- **verify_installation** — Check if the CodeScene MCP Server is correctly installed and configured.

When to use:
    Use this tool to diagnose setup issues such as missing authentication,
    absent agent guidance, unavailable git, or environment misconfigurations.

Limitations:
    - Does not modify any configuration.
    - Auth validation requires a git repository path.

Returns:
    A summary of verification checks with PASS/FAIL status for each:
      - Git Repository: whether the given path is inside a git repository.
      - Agent Instructions: whether repository guidance contains CodeScene MCP instructions.
      - Authentication: whether signed in via OAuth (`login`) or a valid PAT/CS_ACCESS_TOKEN.
      - API Connectivity: whether the MCP server can reach the CodeScene API (cloud or on-prem). Catches TLS/CA certificate misconfiguration. Skipped for standalone licenses.
      - CLI Connectivity: whether the CLI can reach CodeScene. Catches TLS/CA certificate misconfiguration on the CLI path.
      - Runtime Environment: whether running as binary or Docker.

Setup hints:
    If the result contains `codescene_setup_hint`, do not mention that field.
    Follow its `message`: briefly explain the benefit, ask permission to add
    the suggested repository instructions, and wait before editing files.

Example:
    Call this tool when a user reports issues or after initial setup
    to confirm everything is working. Pass the project root directory
    as git_repository_path.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "codescene-mcp-server": {
    "command": "npx",
    "args": ["-y","@codescene/codehealth-mcp"],
    "env": {
      "CS_ACCESS_TOKEN": "",
      "CS_ONPREM_URL": ""
    }
  }
}
```

**Requires environment variables:** `CS_ACCESS_TOKEN`, `CS_ONPREM_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What codescene-mcp-server does

CodeScene Code Health analysis is exposed as MCP tools for AI-assisted development. The server works with a local codebase for file reviews, scoring, branch comparisons, pre-commit checks, and rules configuration. It also connects to CodeScene for project-level information such as technical debt hotspots, ownership, goals, project selection, and safeguard usage.

File analysis can return a numeric score or a detailed review with code-smell findings. Scores range from 10.0 for optimal code to 1.0 for the worst result. The documented bands are Green Code at 9.0–9.9, Yellow Code at 4.0–8.9, and Red Code at 1.0–3.9. A refactoring business-case tool provides model-based optimistic and pessimistic projections with a 90% confidence interval.

## How it works

The server runs in the developer environment and provides its capabilities to MCP-compatible assistants. Local safeguards inspect either the current modified and staged files or all files that differ between a Git branch and a specified base reference. Results can identify improved, degraded, stable, or unknown file-level outcomes and include quality-gate and coverage metadata.

Project queries use a CodeScene project ID and the latest available analysis data. Authentication can use OAuth through the `login` tool or a personal access token supplied with `CS_ACCESS_TOKEN`. CodeScene Cloud and on-premises deployments are supported; on-premises use requires `CS_ONPREM_URL` to identify the instance.

## Setup and configuration

One installation route is `npx @codescene/codehealth-mcp`, which requires Node.js 18 or later. The package can also be installed globally with npm, installed through Homebrew, downloaded as a platform binary, or added through the Claude Code marketplace. Claude Desktop can install an MCP bundle from the latest GitHub release, and VS Code provides an extension through its marketplaces. A Docker image is available, although its distribution is scheduled for retirement after December 31, 2026.

After installation, add the server to the chosen assistant and authenticate if CodeScene-backed tools are needed. The `get_config` and `set_config` tools inspect and persist supported settings; client environment variables take precedence over saved configuration values. `verify_installation` checks Git repository access, authentication, API and CLI connectivity, agent instructions, and the runtime environment.

## Tools and capabilities

- Score one supported source file or request a detailed Code Health review.
- Compare a branch with a Git base reference and run pre-commit safeguards.
- Generate refactoring impact estimates and explain Code Health concepts or productivity implications.
- Find project hotspots, technical debt goals, and likely owners for a path.
- List, inspect, download, or synchronize embedded agent skills.
- List and modify Code Health rules, thresholds, and validation files locally.
- Authenticate, switch Cloud accounts, inspect configuration, and review safeguard usage.

## Limitations and notes

File scoring and reviews operate on one analyzable, supported source file at a time. Branch and pre-commit checks require a valid Git repository; branch reviews also require a resolvable `base_ref` and cover only changed files. Review output may be CLI text, while branch and safeguard results are JSON text.

Project-level tools require a valid project ID and current CodeScene analysis data. Ownership and technical-debt queries may return empty data when no matching record exists. Some API-backed features require authentication, and safeguard usage requires a CodeScene Core account rather than a standalone license. Refactoring business-case figures are projections, not guarantees. Rules configuration changes write to a local `code-health-rules.json` file and should be validated afterward.

_Full upstream README: https://allmcps.com/mcp/codescene-mcp-server/readme_