Skip to main content
Glama
commit-check

commit-check-mcp

Official
by commit-check
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Validate branch name

validate_branch_name
Read-onlyIdempotent

Validate a branch name against configured naming conventions and optional base branch rules, returning a pass/fail/skip status with detailed check results.

Instructions

Validate a branch name against the configured naming convention (e.g. feature/, bugfix/) and, when configured, that the branch is based on the required merge base. Read-only.

Returns {status, warnings, checks[]}. status is 'pass', 'fail' or 'skip': only 'fail' is a rejection; 'skip' means every check skipped, so nothing was validated and the result is not approval. warnings is the number of checks with status 'warn'. Each check has: rule_id (stable rule id, e.g. 'CC001'); check (rule name, e.g. 'message'); status 'pass' | 'fail' | 'warn' | 'skip' ('warn' = the config lists the check under warn, so the finding is reported without failing the run; 'skip' = the rule did not run, e.g. the author is in ignore_authors or there was nothing to check); value (what was checked); error (why it failed); suggest (advice for a person); fix (the corrected value when the correction is unambiguous, else ''); docs_url (documentation for the rule). On 'fail', apply a non-empty fix verbatim; when fix is '', rewrite following suggest; then validate again.

Use this before creating or pushing a branch. Omit branch to check the branch currently checked out in repo_path. For combined message+branch+author validation use validate_commit_context.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
branchNoBranch name to validate, e.g. 'feature/login'. Omit to validate the branch currently checked out in repo_path, which must then be a git repository. Must be non-empty when provided.
configNoInline commit-check config overrides as a JSON object, merged on top of the built-in defaults and any config file, e.g. {"warn": ["message"]} or {"commit": {"require_body": true}}.
repo_pathNoPath to the git repository to validate against. Its cchk.toml or commit-check.toml (also looked up under .github/) is loaded, and a relative config_path is resolved from it. Omit to use the server's working directory.
config_pathNoPath to a commit-check TOML config file, used instead of the repository's own cchk.toml/commit-check.toml; a relative path is resolved from repo_path.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.10
    • addedInput schema / properties / branch / description
      Added value: +"Branch name to validate, e.g. 'feature/login'. Omit to validate the branch currently checked out in repo_path, which must then be a git repository. Must be non-empty when provided."
    • addedInput schema / properties / config / description
      Added value: +"Inline commit-check config overrides as a JSON object, merged on top of the built-in defaults and any config file, e.g. {\"warn\": [\"message\"]} or {\"commit\": {\"require_body\": true}}."
    • addedInput schema / properties / config_path / description
      Added value: +"Path to a commit-check TOML config file, used instead of the repository's own cchk.toml/commit-check.toml; a relative path is resolved from repo_path."
    • addedInput schema / properties / repo_path / description
      Added value: +"Path to the git repository to validate against. Its cchk.toml or commit-check.toml (also looked up under .github/) is loaded, and a relative config_path is resolved from it. Omit to use the server's working directory."
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses the exact return semantics (pass/fail/skip), explains that 'skip' is not approval, and details the required action on failure (apply fix verbatim or rewrite per suggest and revalidate). This goes well beyond the annotations to fully inform the agent of behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is somewhat lengthy and repeats the status/check field definitions, but it is well organized into purpose, return format, and usage guidance. Every section carries necessary information, so the length is justified, though it could be tightened without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It provides a complete picture: what the tool does, how the result is structured, how to interpret statuses and check fields, and what action to take upon failure. It also tells the agent when to use it and when to use the alternative, leaving no critical gaps for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides detailed descriptions for all four parameters, covering the branch omission behavior and config merging. The description adds useful context about the naming convention and merge-base check, but does not substantially extend the schema. Given the high schema coverage, this is above the baseline but not exceptional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action: validate a branch name against a configured naming convention and optionally a merge-base requirement. It also explicitly differentiates from the sibling validate_commit_context, which handles combined message+branch+author validation, so an agent can immediately understand the tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit timing guidance: 'Use this before creating or pushing a branch.' It also clarifies when to omit the branch parameter (current checked-out branch) and points to validate_commit_context for combined validation, making the choice between tools unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools