Barry Walker
7aa8fddea8
- Add cog.toml with commit type configs and version bump hooks - Add .woodpecker.yml pipeline for automated version bumping on main - Add Version element to csproj for cog to update - Document cog workflow in CLAUDE.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
# 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
|
|
|
|
## Versioning with Cocogitto (cog)
|
|
|
|
This repo uses [Cocogitto](https://docs.cocogitto.io/) for conventional commit enforcement and version management.
|
|
|
|
**Git hook:** A `commit-msg` hook enforces conventional commits. Install it after cloning:
|
|
```bash
|
|
cog install-hook commit-msg
|
|
```
|
|
|
|
**Commit format:**
|
|
```
|
|
<type>[optional scope]: <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer(s)]
|
|
```
|
|
|
|
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
|
|
|
|
**Version bumping:**
|
|
```bash
|
|
cog bump --auto # Auto-detect bump type from commits
|
|
cog bump --patch # Bump patch version (0.1.12 -> 0.1.13)
|
|
cog bump --minor # Bump minor version (0.1.12 -> 0.2.0)
|
|
cog bump --major # Bump major version (0.1.12 -> 1.0.0)
|
|
cog bump --dry-run # Preview what would happen
|
|
```
|
|
|
|
**Other useful commands:**
|
|
```bash
|
|
cog check # Verify all commits follow conventional format
|
|
cog changelog # Generate changelog
|
|
cog get-version # Show current version
|
|
```
|