Git MCP Server

Field testing is a debugging and verification process used to exercise the real HTTP transport and JSON-RPC layer of the MCP server. Unlike unit tests that use mocked contexts, field testing uses a live HTTP server to catch issues like:

• Awkward input shapes and unhelpful error messages.
• Missing responseFormatter output.
• Drift between structuredContent and content[] fields.
• Git-specific edge cases (e.g., conflicts, bare repositories, protected branches, or working directory state).

Best Practice: When testing git tools, use a throwaway test repository (e.g., /tmp/field-test-repo initialized with git init and a seed commit) instead of the project itself to ensure state changes are bounded and easy to clean up.

The server provides different output formats via MCP_RESPONSE_FORMAT. Regardless of the format chosen for the client, the LLM always receives the complete structured data via the responseFormatter (including full file lists, metadata, and timestamps).

JSON Format (Default)

Optimized for LLM consumption. Example:

{
  "success": true,
  "branch": "main",
  "staged": ["src/index.ts", "README.md"],
  "unstaged": ["package.json"],
  "untracked": []
}

Markdown Format

Human-readable format. Example:

# Git Status: main

## Staged (2)
- src/index.ts
- README.md

## Unstaged (1)
- package.json

Verbosity Levels

Controlled by MCP_RESPONSE_VERBOSITY:

• minimal: Core fields only.
• standard: Balanced detail (default).
• full: Includes all available metadata and details.

To interact with an MCP HTTP server, you must perform a two-step initialization sequence to establish a session ID:

1. Initialize: Send a POST request to the server URL with the initialize method. The server returns a mcp-session-id in the HTTP response headers.
2. Notify: Send a POST request with the notifications/initialized method, including the captured Mcp-Session-Id in the headers.

All subsequent requests must include the Mcp-Session-Id header to be associated with the active session.

When testing tools, distinguish between protocol-level errors and tool-domain errors:

• Tool Domain Errors: These occur when a tool executes but the operation fails (e.g., a Git conflict or invalid command). These return a successful JSON-RPC response where isError: true is set inside the result object. Do not look for the JSON-RPC error field for these.
  • Format: { "result": { "content": [...], "isError": true } }
• Protocol Errors: These occur when the JSON-RPC envelope is malformed, the session is invalid, or the method is unknown. These return a standard JSON-RPC error field.

Structured Git Errors: When the server throws a formal McpError, it will include a code and context. The content[] array should contain a human-readable explanation of the error reason.

GitHub issues are public. You must redact all secrets, credentials, API keys, JWT tokens, or git remote URLs that encode credentials before submitting.

Redaction Rules:

• Do not rely on partial masking; replace sensitive values entirely.
• Use obvious placeholders like REDACTED or sk-...REDACTED.
• Example: https://REDACTED@github.com/...

The repository uses a monolithic changelog following the Keep a Changelog format.

Conventions:

• Headers: Every release must have a top-level ## v<version> - <YYYY-MM-DD> header. Never use [Unreleased].
• Sections: Group entries under ### Added, ### Changed, ### Fixed, ### Removed, or ### Security.
• Breaking Changes: Call these out in bold at the top of the relevant section or use a dedicated ### Breaking header.
• References: Use code blocks for tool names (e.g., `git_merge`) and reference PR/issue numbers (e.g., (#42)).
• Ordering: Newest releases at the top; oldest at the bottom.

The server implements several security measures:

• Path Validation: All file paths are sanitized to prevent directory traversal.
• Sandboxing: Setting GIT_BASE_DIR restricts all git operations to a specific directory tree.
• Argument Safety: Git commands use validated arguments via process spawning to avoid shell interpolation.
• Destructive Operation Safety: Operations like git clean or git reset --hard require explicit confirmation flags.
• Authentication: Supports none, jwt, and oauth modes for deployed environments.
• Auditability: All operations are logged with request context.

The skills/ directory at the project root is the source of truth for agent-specific capabilities. To use these skills with an AI agent (like Claude Code, Codex, Cursor, or Windsurf), you must sync the contents of the root skills/ directory to the agent's specific configuration directory.

Important: Do not delete existing skills in the agent's directory that are not present in the root skills/ folder, as those may be general-purpose skills provided by the agent itself (e.g., code-security).

mkdir -p .claude/skills && cp -R skills/* .claude/skills/

After investigating changelogs, apply the necessary changes to the codebase. Focus on:

• Breaking changes: Fix call sites. Priority areas include src/mcp-server/, src/services/, src/utils/, src/storage/, and src/container/.
• Deprecations: Migrate code to new APIs while the context is fresh.
• New APIs: Refactor targeted areas to use better APIs; avoid unnecessary wide-scale refactoring.
• New configuration: Update .env.example, the Zod schema in src/config/index.ts, and README.md if the changes are user-facing.

Specific areas to re-check based on package type:

• src/services/git/providers/cli/ (if child-process libraries changed)
• src/mcp-server/transports/http/ (if Hono / MCP SDK changed)
• src/utils/telemetry/ (if OpenTelemetry SDK changed)
• src/mcp-server/transports/auth/ (if jose changed)