git-mcp-server

# 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.

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                                                                                                                                  |
| :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `src/mcp-server/tools/definitions/`     | MCP Tool definitions. Named `git-[operation].tool.ts`.                                                                                   |
| `src/mcp-server/tools/utils/`           | Shared tool utilities: `toolDefinition.ts`, `toolHandlerFactory.ts`, `git-validators.ts`, `json-response-formatter.ts`.                  |
| `src/mcp-server/tools/schemas/`         | Shared Zod schemas: `PathSchema`, `CommitRefSchema`, `BranchNameSchema`, etc.                                                            |
| `src/mcp-server/resources/definitions/` | MCP Resource definitions. Primary: `git-working-directory.resource.ts`.                                                                  |
| `src/mcp-server/resources/utils/`       | Shared resource utilities: `ResourceDefinition` and handler factory.                                                                     |
| `src/mcp-server/prompts/definitions/`   | MCP Prompt definitions (e.g., `git-wrapup.prompt.ts`).                                                                                   |
| `src/mcp-server/transports/`            | Transport implementations: `http/` (Hono + Streamable HTTP), `stdio/`, `auth/` (JWT/OAuth strategies).                                   |
| `src/services/git/`                     | Git service: `core/` (interfaces, factory), `providers/cli/` (CLI implementation with domain-organized operations).                      |
| `src/storage/`                          | Storage abstractions and providers (in-memory, filesystem, supabase, cloudflare).                                                        |
| `src/container/`                        | Dependency injection (`tsyringe`). Service registration and tokens.                                                                      |
| `src/utils/`                            | Global utilities: `internal/` (logger, requestContext, ErrorHandler, performance), `security/` (sanitization), `telemetry/`, `metrics/`. |
| `tests/`                                | Unit/integration tests mirroring `src/` structure.                                                                                       |

---

## III. Tool Development Workflow

### Step 1 — File Location

- Place new tools in `src/mcp-server/tools/definitions/`.
- Name files `git-[operation].tool.ts` (e.g., `git-commit.tool.ts`, `git-status.tool.ts`).
- Use existing tools as reference (e.g., `git-status.tool.ts`).

### Step 2 — Define the ToolDefinition

Export a single `const` named `[toolName]Tool` of type `ToolDefinition` with:

- `name`: Programmatic tool name, `snake_case` with `git_` prefix (e.g., `git_status`, `git_commit`).
- `title` (optional): Human-readable title (e.g., `'Git Status'`).
- `description`: Clear, LLM-facing description.
- `inputSchema`: A `z.object({ ... })`. **Every field must have `.describe()`**. Use shared schemas from `schemas/common.ts` (`PathSchema`, `CommitRefSchema`, etc.).
- `outputSchema`: A `z.object({ ... })` describing the successful output structure.
- `annotations` (optional): UI/behavior hints (`readOnlyHint`, `openWorldHint`, etc.).
- `logic`: Wrapped with `createToolHandler` (see below).
- `responseFormatter` (optional): Use `createJsonFormatter` for consistent output.

### Step 3 — Implement Logic with `createToolHandler`

Tool logic uses a **two-tier handler pattern**:

1. **`createToolHandler`** resolves DI dependencies (StorageService, GitProviderFactory) once via lazy closure, resolves the working directory from `input.path`, and passes everything to your pure logic function as `ToolLogicDependencies`.
2. **`createMcpToolHandler`** (framework-level) wraps everything for the MCP SDK: context creation, performance measurement, error handling, response formatting.

Your logic function receives `(input, deps: ToolLogicDependencies)`:

```typescript
interface ToolLogicDependencies {
  provider: IGitProvider; // Git provider, already resolved
  storage: StorageService; // Storage service, already resolved
  appContext: RequestContext; // Request context for logging/tracing
  sdkContext: SdkContext; // MCP SDK context (signal, sendNotification, etc.)
  targetPath: string; // Resolved working directory (from input.path)
}
```

For tools that don't need path resolution (e.g., `git_clone`, `git_set_working_dir`), pass `{ skipPathResolution: true }`:

```typescript
logic: withToolAuth(['tool:git:write'],
  createToolHandler(myLogic, { skipPathResolution: true })
),
```

### Step 4 — Apply Authorization

Wrap `logic` with `withToolAuth`:

```typescript
logic: withToolAuth(['tool:git:read'], createToolHandler(gitStatusLogic)),
```

**Scopes:** `tool:git:read` for read-only, `tool:git:write` for mutations.

### Step 5 — Register via Barrel Export

Add your tool to `src/mcp-server/tools/definitions/index.ts` in `allToolDefinitions`.

### Complete Example

```typescript
/**
 * @fileoverview Git status tool - show working tree status
 * @module mcp-server/tools/definitions/git-status
 */
import { z } from 'zod';

import type { ToolDefinition } from '../utils/toolDefinition.js';
import { withToolAuth } from '@/mcp-server/transports/auth/lib/withAuth.js';
import { PathSchema } from '../schemas/common.js';
import {
  createToolHandler,
  type ToolLogicDependencies,
} from '../utils/toolHandlerFactory.js';
import {
  createJsonFormatter,
  type VerbosityLevel,
} from '../utils/json-response-formatter.js';

const TOOL_NAME = 'git_status';
const TOOL_TITLE = 'Git Status';
const TOOL_DESCRIPTION =
  'Show the working tree status including staged, unstaged, and untracked files.';

const InputSchema = z.object({
  path: PathSchema,
  includeUntracked: z
    .boolean()
    .default(true)
    .describe('Include untracked files in the output.'),
});

const OutputSchema = z.object({
  success: z.boolean().describe('Indicates if the operation was successful.'),
  currentBranch: z.string().nullable().describe('Current branch name.'),
  isClean: z.boolean().describe('True if working directory is clean.'),
  stagedChanges: z
    .object({
      added: z
        .array(z.string())
        .optional()
        .describe('Files added to the index.'),
      modified: z
        .array(z.string())
        .optional()
        .describe('Files modified and staged.'),
      deleted: z
        .array(z.string())
        .optional()
        .describe('Files deleted and staged.'),
    })
    .describe('Changes staged for the next commit.'),
  unstagedChanges: z
    .object({
      modified: z
        .array(z.string())
        .optional()
        .describe('Files modified but not staged.'),
      deleted: z
        .array(z.string())
        .optional()
        .describe('Files deleted but not staged.'),
    })
    .describe('Changes not yet staged.'),
  untrackedFiles: z.array(z.string()).describe('Untracked files.'),
  conflictedFiles: z.array(z.string()).describe('Files with merge conflicts.'),
});

type ToolInput = z.infer<typeof InputSchema>;
type ToolOutput = z.infer<typeof OutputSchema>;

// Pure business logic — receives pre-resolved dependencies
async function gitStatusLogic(
  input: ToolInput,
  { provider, targetPath, appContext }: ToolLogicDependencies,
): Promise<ToolOutput> {
  const result = await provider.status(
    { includeUntracked: input.includeUntracked },
    {
      workingDirectory: targetPath,
      requestContext: appContext,
      tenantId: appContext.tenantId || 'default-tenant',
    },
  );

  return {
    success: true,
    currentBranch: result.currentBranch,
    isClean: result.isClean,
    stagedChanges: result.stagedChanges,
    unstagedChanges: result.unstagedChanges,
    untrackedFiles: result.untrackedFiles,
    conflictedFiles: result.conflictedFiles,
  };
}

// Verbosity filter for response formatting
function filterGitStatusOutput(
  result: ToolOutput,
  level: VerbosityLevel,
): Partial<ToolOutput> {
  if (level === 'minimal') {
    return {
      success: result.success,
      currentBranch: result.currentBranch,
      isClean: result.isClean,
    };
  }
  return result; // standard & full return everything
}

const responseFormatter = createJsonFormatter<ToolOutput>({
  filter: filterGitStatusOutput,
});

export const gitStatusTool: ToolDefinition<
  typeof InputSchema,
  typeof OutputSchema
> = {
  name: TOOL_NAME,
  title: TOOL_TITLE,
  description: TOOL_DESCRIPTION,
  inputSchema: InputSchema,
  outputSchema: OutputSchema,
  annotations: { readOnlyHint: true },
  logic: withToolAuth(['tool:git:read'], createToolHandler(gitStatusLogic)),
  responseFormatter,
};
```

---

### Response Formatter: JSON Output Pattern

All tools use `createJsonFormatter` for consistent, machine-readable JSON output with verbosity control (`minimal`, `standard`, `full`).

**Basic usage:**

```typescript
import {
  createJsonFormatter,
  shouldInclude,
  type VerbosityLevel,
} from '../utils/json-response-formatter.js';

function filterOutput(
  result: ToolOutput,
  level: VerbosityLevel,
): Partial<ToolOutput> {
  return {
    success: result.success,
    commitHash: result.commitHash,
    ...(shouldInclude(level, 'standard') && { files: result.files }),
    ...(shouldInclude(level, 'full') && {
      detailedStatus: result.detailedStatus,
    }),
  };
}

const responseFormatter = createJsonFormatter<ToolOutput>({
  filter: filterOutput,
});
```

**Rules:**

- Include or omit entire fields based on verbosity — never truncate arrays.
- Return complete arrays when included (LLMs need full context).
- For simple tools with minimal output, omit the filter entirely: `createJsonFormatter<ToolOutput>()`.

**Additional utilities:** `filterByVerbosity()`, `mergeFilters()`, `createFieldMapper()`, `createConditionalFilter()`.

---

## IV. Tool Layer vs Service Layer

**Tools MUST use the `IGitProvider` interface for all git operations.** Direct git command execution is forbidden in the tool layer.

```
┌─────────────────────────────────────────────────┐
│           Tool Layer (src/mcp-server/tools/)    │
│  - Input validation (Zod schemas)               │
│  - Path resolution (via createToolHandler)      │
│  - Output formatting for LLM                    │
│  - Pure validators (no git execution)           │
└─────────────────────┬───────────────────────────┘
                      │ IGitProvider interface
                      ▼
┌─────────────────────────────────────────────────┐
│          Service Layer (src/services/git/)      │
│  - Git command execution                        │
│  - Git-specific validators                      │
│  - Output parsing & error transformation        │
└─────────────────────────────────────────────────┘
```

### Validator Location Rules

| Validator Type                        | Location                                      | Reason                            |
| ------------------------------------- | --------------------------------------------- | --------------------------------- |
| Path sanitization                     | Tool layer (`git-validators.ts`)              | Security, no git execution        |
| Session directory resolution          | Tool layer (`git-validators.ts`)              | Uses StorageService               |
| Protected branch checks               | Tool layer (`git-validators.ts`)              | Pure logic                        |
| File path / commit message validation | Tool layer (`git-validators.ts`)              | Pure validation                   |
| Git repository validation             | Service layer (`cli/utils/git-validators.ts`) | Executes `git rev-parse`          |
| Branch existence check                | Service layer (`cli/utils/git-validators.ts`) | Executes `git rev-parse --verify` |
| Clean working dir check               | Service layer (`cli/utils/git-validators.ts`) | Executes `git status --porcelain` |
| Remote existence check                | Service layer (`cli/utils/git-validators.ts`) | Executes `git remote get-url`     |

### Working Directory Resolution

Handled automatically by `createToolHandler`. When `input.path` is `'.'`, it loads from session storage using key `session:workingDir:{tenantId}`. When it's an absolute path, it's used directly. All paths are sanitized to prevent directory traversal.

---

## V. Git Service Architecture

The git service uses a **provider-based architecture** with the CLI provider as the current implementation.

### Structure

```
src/services/git/
├── core/
│   ├── IGitProvider.ts           # Provider interface contract
│   ├── BaseGitProvider.ts        # Shared provider functionality
│   └── GitProviderFactory.ts     # Provider selection and caching
├── providers/cli/
│   ├── CliGitProvider.ts         # Main provider class
│   ├── operations/               # Operations organized by domain
│   │   ├── core/                 # init, clone, status, clean
│   │   ├── staging/              # add, reset
│   │   ├── commits/              # commit, log, show, diff
│   │   ├── branches/             # branch, checkout, merge, rebase, cherry-pick
│   │   ├── remotes/              # remote, fetch, push, pull
│   │   ├── tags/                 # tag
│   │   ├── stash/                # stash
│   │   ├── worktree/             # worktree
│   │   ├── history/              # blame, reflog
│   │   └── index.ts              # Single barrel export
│   └── utils/                    # CLI-specific utilities and validators
├── types.ts                       # Shared git types and DTOs
└── index.ts                       # Public API
```

### Key Design Principles

- Each file handles exactly one operation (one function per file).
- All operations are stateless async functions that throw `McpError` on failure.
- Operations receive an `execGit` function for executing git commands, keeping them testable.
- Single barrel export at `operations/index.ts` (no nested barrels).

### IGitProvider Interface

All providers implement: init, clone, status, clean, add, commit, log, show, diff, branch, checkout, merge, rebase, cherryPick, remote, fetch, push, pull, tag, stash, worktree, reset, blame, reflog.

Each provider declares capabilities via `GitProviderCapabilities`, allowing consumers to check feature support.

### Provider Types

- **CLI** (`GitProviderType.CLI`): Full feature set, local-only (default, current)
- **Isomorphic** (`GitProviderType.ISOMORPHIC`): Edge-compatible (planned)

---

## VI. Resource Development Workflow

Resources follow the same pattern as tools with a declarative `ResourceDefinition`.

- Place in `src/mcp-server/resources/definitions/` as `[resource-name].resource.ts`.
- Export a `const` of type `ResourceDefinition` with: `name`, `description`, `uriTemplate`, `paramsSchema`, `logic`, and optional `responseFormatter`.
- Wrap logic with `withResourceAuth(['resource:git:read'], ...)`.
- Register in `src/mcp-server/resources/definitions/index.ts` via `allResourceDefinitions`.
- Logic is pure (no `try/catch`) — throw `McpError` on failure.

---

## VII. Core Services & Utilities

### DI-Managed Services (tokens in `src/container/tokens.ts`)

| Token                     | Purpose                                       |
| ------------------------- | --------------------------------------------- |
| `StorageService`          | Session state (working directory persistence) |
| `GitProviderFactory`      | Git provider selection and caching            |
| `Logger`                  | Pino-backed structured logging                |
| `AppConfig`               | Validated environment configuration           |
| `RateLimiterService`      | Optional rate limiting for HTTP transport     |
| `CreateMcpServerInstance` | Factory resolved by `TransportManager`        |
| `TransportManagerToken`   | Manages stdio/HTTP transport lifecycle        |

### Directly Imported Utilities

- `logger` — Global Pino logger instance
- `requestContextService` — AsyncLocalStorage-based context propagation
- `ErrorHandler.tryCatch` — For services/infrastructure (NOT in tool/resource logic)
- `sanitization` — **Critical** for path validation and directory traversal prevention
- `measureToolExecution` — Performance measurement (used by handlers automatically)

### Key Utility Modules (`src/utils/`)

| Module       | Key Exports                                                                             |
| :----------- | :-------------------------------------------------------------------------------------- |
| `internal/`  | `logger`, `requestContextService`, `ErrorHandler`, `performance` (measureToolExecution) |
| `security/`  | `sanitization` (path/input validation), `rateLimiter`, `idGenerator`                    |
| `telemetry/` | OpenTelemetry instrumentation                                                           |

---

## VIII. Authentication & Authorization

### HTTP Transport

- **Modes:** `MCP_AUTH_MODE` = `'none'` | `'jwt'` | `'oauth'`
- **JWT mode:** Uses `MCP_AUTH_SECRET_KEY`. In dev without the secret, verification is bypassed.
- **OAuth mode:** Verifies tokens via remote JWKS. Requires `OAUTH_ISSUER_URL` and `OAUTH_AUDIENCE`.
- **Extracted claims:** `clientId`, `scopes`, `subject`, `tenantId` (from `'tid'` claim).
- **Scope enforcement:** Always wrap logic with `withToolAuth` or `withResourceAuth`. Defaults to allowed when auth is disabled.

### STDIO Transport

No HTTP-based auth. Authorization handled by the host application.

### HTTP Endpoints

- `GET /healthz` — Unprotected health check
- `GET /.well-known/oauth-protected-resource` — RFC 9728 protected resource metadata (unprotected, for discovery)
- `GET /mcp` — Unprotected server identity and config summary
- `POST /mcp` — JSON-RPC transport (protected when auth enabled)
- `DELETE /mcp` — Session termination (MCP Spec 2025-06-18)
- CORS enabled via `MCP_ALLOWED_ORIGINS` or `'*'` fallback

---

## IX. Server Lifecycle

### `createMcpServerInstance` (`src/mcp-server/server.ts`)

- Configures `RequestContext` global settings.
- Creates `McpServer` with capabilities: `logging`, `resources` (listChanged), `tools` (listChanged), `prompts` (listChanged).
- Registers all capabilities via DI-managed registries: `ToolRegistry`, `ResourceRegistry`, `PromptRegistry`.

### `TransportManager`

- Resolves `CreateMcpServerInstance` to get a configured `McpServer`.
- Based on `MCP_TRANSPORT_TYPE`, starts the appropriate transport (`http` or `stdio`).
- Handles graceful startup and shutdown.

### Worker (Edge) — Experimental

- `worker.ts` adapts the server for Cloudflare Workers.
- Git CLI operations require local filesystem access — edge deployment is experimental.

---

## X. Code Style & Security

- **JSDoc:** Every file: `@fileoverview` and `@module`. Document exported APIs.
- **Validation:** All inputs validated via Zod. Every schema field must have `.describe()`.
- **Logging:** Always include `RequestContext`. Use `logger.debug/info/warning/error` appropriately.
- **Error Handling:** Logic throws `McpError`; handlers catch. Use `ErrorHandler.tryCatch` in services only.
- **Secrets:** Access via `src/config/index.ts`. Never hard-code.

### Git-Specific Security

- **Path Sanitization:** All paths MUST use `sanitization` utilities to prevent directory traversal.
- **Command Injection:** Git command arguments must be validated — never from unsanitized input.
- **Destructive Operations:** `git reset --hard/--merge/--keep`, `git clean -fd` require explicit confirmation flags.

---

## XI. Configuration & Environment

All configuration validated via Zod in `src/config/index.ts`. Derives `serviceName` and `version` from `package.json` if not provided.

| Category      | Variables                                                                                                                                                                                                                                                  |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Transport** | `MCP_TRANSPORT_TYPE` (`stdio`/`http`), `MCP_HTTP_PORT`, `MCP_HTTP_HOST`, `MCP_HTTP_PATH`                                                                                                                                                                   |
| **Auth**      | `MCP_AUTH_MODE` (`none`/`jwt`/`oauth`), `MCP_AUTH_SECRET_KEY`, `OAUTH_ISSUER_URL`, `OAUTH_AUDIENCE`, `OAUTH_JWKS_URI`                                                                                                                                      |
| **Storage**   | `STORAGE_PROVIDER_TYPE` (`in-memory`/`filesystem`/`supabase`/`cloudflare-r2`/`cloudflare-kv`), `STORAGE_FILESYSTEM_PATH`                                                                                                                                   |
| **Git**       | `GIT_PROVIDER` (`auto`/`cli`/`isomorphic`), `GIT_SIGN_COMMITS`, `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL`, `GIT_BASE_DIR`, `GIT_MAX_COMMAND_TIMEOUT_MS`, `GIT_MAX_BUFFER_SIZE_MB`, `GIT_WRAPUP_INSTRUCTIONS_PATH` |
| **Telemetry** | `OTEL_ENABLED`, `OTEL_SERVICE_NAME`, `OTEL_SERVICE_VERSION`, `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`                                                                                                                   |

---

## XII. Workflow Commands

| Command                              | Purpose                                                                                |
| :----------------------------------- | :------------------------------------------------------------------------------------- |
| `bun rebuild`                        | Clean and rebuild; clears logs. Run after dependency changes.                          |
| `bun devcheck`                       | Lint, format, typecheck, security audit. Flags: `--no-fix`, `--no-lint`, `--no-audit`. |
| `bun test`                           | Run unit/integration tests.                                                            |
| `bun run dev:stdio` / `dev:http`     | Development mode.                                                                      |
| `bun run start:stdio` / `start:http` | Production mode (after build).                                                         |
| `bun run build:worker`               | Build Cloudflare Worker bundle.                                                        |

---

## XIII. Multi-Tenancy

- `StorageService` requires `context.tenantId` — throws `McpError` if missing.
- In HTTP + auth mode, `tenantId` is automatically extracted from JWT `'tid'` claim.
- In development (STDIO/no auth), use graceful degradation: `appContext.tenantId || 'default-tenant'`.
- The `createToolHandler` factory handles this pattern for you — `resolveWorkingDirectory` applies it internally.

---

## XIV. Quick Checklist

- [ ] Tool/resource logic in `*.tool.ts` or `*.resource.ts`, pure (no `try/catch`).
- [ ] Throws `McpError` for failures.
- [ ] Uses `createToolHandler` for dependency injection and path resolution.
- [ ] Wrapped with `withToolAuth` or `withResourceAuth`.
- [ ] Uses `logger` with `appContext` for logging.
- [ ] All file paths validated via `sanitization` utilities.
- [ ] Git command arguments validated (no command injection).
- [ ] Registered in `index.ts` barrel file.
- [ ] Tests added/updated (`bun test`).
- [ ] `bun run devcheck` passes.
- [ ] Smoke-tested local transports (`dev:stdio`/`dev:http`).