# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Development Commands
### Installation and Setup
```bash
uv sync
```
### Running the Server
```bash
uv run main.py
```
### Environment Variables Required
- `API_KEY` - Your DocDocDoc API key (required)
- `BASE_URL` - API base URL (defaults to https://staging.docdocdoc.fr)
## Architecture
This is a Model Context Protocol (MCP) server that provides tools to interact with the DocDocDoc document request API. The codebase follows a modular structure:
### Core Components
- **`main.py`** - Entry point that starts the MCP server
- **`server.py`** - Main MCP server setup using FastMCP, registers tools and resources
- **`config/settings.py`** - Environment-based configuration management with validation
- **`api/client.py`** - HTTP client wrapper for DocDocDoc API calls with error handling
- **`tools/requests.py`** - MCP tools for document request operations (CRUD)
- **`models/constants.py`** - Document types and other constants
- **`utils/helpers.py`** - Utility functions
### MCP Tools Available
The server exposes these tools for document request management:
- `create_request` - Create new document requests with full validation
- `get_request` - Retrieve request details with optional related data
- `update_request` - Modify existing requests
- `cancel_request` - Cancel requests (preserves data, sets status to cancelled)
- `delete_request` - Permanently remove requests
### Request Data Model
Document requests include:
- Required: requested_email, requested_name, requestor_email, requestor_name
- Optional: phone numbers, company names, document_type, custom message
- Statuses: pending, viewed, cancelled, completed, rejected, approved, expired
- Document types: id_card, passport, driver_license, residence_permit, statutes, company_registration, beneficials_owner_register
### API Integration
- Uses `requests` library for HTTP calls to DocDocDoc staging API
- Authentication via `X-API-Key` header
- Comprehensive error handling and input validation
- All operations work with live API endpoints
## Commit Guidelines
This project uses **Conventional Commits** format. Always structure commits as:
```
type(scope): description
[optional body]
[optional footer]
```
**Required types**: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
**Examples**:
- `feat(tools): add cancel_request functionality`
- `fix(api): resolve authentication issue`
- `docs: update README with installation instructions`
For breaking changes, include `BREAKING CHANGE:` in the footer.
