Agent Protocol & Architectural Mandate

Agent Protocol & Architectural Mandate

**Version:** 2.10.5 **Target Project:** git-mcp-server **Last Updated:** 2026-03-25

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.

4. **Decoupled Storage**

   • Never directly access persistence backends from tool/resource logic.
   • Use StorageService (injected via DI) for session state (working directory persistence).
   • Git operations execute via the IGitProvider interface, not direct CLI calls.

5. **Graceful Degradation in Development**

   • When tenantId is missing, default to permissive behavior: const tenantId = appContext.tenantId || 'default-tenant';
   • Auth/scope checks default to allowed when auth is disabled.
   • Production environments with auth enabled provide real tenantId from JWT claims automatically.

---

II. Directory Structure

Directory	Purpose