git-mcp-server CLAUDE.md

Agent Protocol & Architectural Mandate

Version: 2.15.3 Target Project: git-mcp-server Last Updated: 2026-08-24

This document defines the operational rules for contributing to this codebase. Follow it exactly.

Note on File Synchronization: AGENTS.md is a symlink to CLAUDE.md. Edit only CLAUDE.md — AGENTS.md will reflect changes automatically.

I. Core Principles (Non-Negotiable)

1. The Logic Throws, The Handler Catches

   • Tools: Implement pure, stateless business logic inside tool logic functions. No try/catch blocks.
   • Resources: Same rule — pure read logic, no try/catch.
   • On Failure: Throw new McpError(...) with the appropriate JsonRpcErrorCode and context.
   • Framework's Job:
     • createMcpToolHandler wraps tool logic: creates RequestContext, measures execution via measureToolExecution, formats the response, catches errors.
     • createToolHandler wraps git-specific logic: resolves DI dependencies and working directory before calling your pure logic.
     • Resource handlers (resourceHandlerFactory) validate params, invoke logic, apply responseFormatter, and catch errors.

2. Full-Stack Observability

   • OpenTelemetry is preconfigured. Logs and errors are automatically correlated to traces.
   • measureToolExecution automatically records duration, success, payload sizes, and error codes for every tool call.
   • Do not add custom spans in tool/resource logic. The framework handles instrumentation.

3. Structured, Traceable Operations

   • Tool logic receives dependencies via ToolLogicDependencies (which includes appContext and sdkContext).
   • appContext (RequestContext): Internal logging/tracing context with requestId, sessionId, tenantId, traceId.
   • sdkContext (SdkContext): MCP SDK protocol capabilities — signal, sendNotification, sendRequest, authInfo.
   • Pass appContext through your internal call stack. Use the global logger with appContext in every log call.