# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Test Commands

```bash
dotnet build                # Build the solution
dotnet test                 # Run all tests
dotnet test --filter "FullyQualifiedName~DocumentToolsTests"  # Run specific test class
dotnet test --logger "console;verbosity=detailed"             # Verbose test output
```

**Running locally:**
```bash
# Set required environment variables
export PAPERLESS_BASE_URL=https://your-instance.com
export PAPERLESS_API_TOKEN=your-token

# stdio mode (for Claude Desktop)
dotnet run --project PaperlessMCP -- --stdio

# HTTP mode (runs at http://localhost:5000/mcp)
dotnet run --project PaperlessMCP
```

## Architecture

PaperlessMCP is an MCP (Model Context Protocol) server that bridges Paperless-ngx with AI assistants. It supports dual transport modes: stdio for Claude Desktop integration and HTTP for remote usage.

### Key Components

- **Program.cs** - Entry point with dual transport setup (stdio vs HTTP). Configures DI, HttpClient with Polly retry policies, and MCP server registration.

- **Client/PaperlessClient.cs** - Central API client for all Paperless-ngx operations. Uses snake_case JSON serialization to match API conventions.

- **Client/PaperlessAuthHandler.cs** - DelegatingHandler that injects API token authentication.

- **Tools/** - MCP tool implementations, one file per entity type:
  - `DocumentTools.cs` - Search, CRUD, bulk operations, upload (base64 and file path)
  - `TagTools.cs`, `CorrespondentTools.cs`, `DocumentTypeTools.cs`, `StoragePathTools.cs` - Entity management with matching algorithms
  - `CustomFieldTools.cs` - Custom field definitions and assignments
  - `HealthTools.cs` - Ping and capabilities

- **Models/** - Request/response DTOs organized by entity (Documents/, Tags/, etc.). Uses `PaginatedResponse<T>` for list endpoints.

### Configuration

Environment variables (take precedence over appsettings.json):
- `PAPERLESS_BASE_URL` / `PAPERLESS_URL` - Paperless-ngx instance URL
- `PAPERLESS_API_TOKEN` / `PAPERLESS_TOKEN` - API authentication token
- `MAX_PAGE_SIZE` - Max items per page (default: 100)
- `MCP_PORT` - HTTP server port (default: 5000)

### Testing

Tests use xUnit with FluentAssertions for assertions, NSubstitute for mocking, and RichardSzalay.MockHttp for HTTP mocking. Test files mirror the main project structure under `PaperlessMCP.Tests/`.

## Conventions

- Use [Conventional Commits](https://www.conventionalcommits.org/) - version bumps are automatic based on commit type (`fix:` = patch, `feat:` = minor, `feat!:` = major)
- Trunk-based development: feature branches merge directly to `main`
- All destructive operations (delete, bulk operations) require explicit `confirm=true` and default to dry-run mode