# CLAUDE.md

## Project Overview

OpenProject MCP Server (`@kollect/openproject-mcp`) — a TypeScript MCP server that bridges AI assistants to OpenProject via the v3 REST API.

## Tech Stack

- **Runtime:** Node.js (ES modules)
- **Language:** TypeScript (strict, ES2022 target)
- **MCP SDK:** `@modelcontextprotocol/sdk` (stdio transport)
- **Validation:** Zod v4
- **Package manager:** pnpm
- **Build:** `tsc` → `dist/`

## Project Structure

```
src/
  index.ts      — Entry point, server setup, tool registration
  client.ts     — OpenProject API v3 HTTP client (Basic Auth)
  tools.ts      — MCP tool definitions with Zod schemas
  handlers.ts   — Tool handler implementations (API calls + formatting)
```

## Commands

```bash
just install        # Install Node.js dependencies (pnpm install)
just build          # Compile TypeScript to dist/
just start          # Run compiled server (requires build first)
just dev            # Run directly with tsx (no build needed)
just bootstrap      # Full setup: uv, just, commitizen, pre-commit, git hooks
just setup          # Install commitizen + pre-commit hooks only
just update         # Refresh pre-commit hook versions
just changelog      # Generate CHANGELOG.md from commit history
just bump           # Bump version based on commit history
```

## Gitignored (do not commit)

- `.env` — contains API keys
- `.mcp.json` — contains API keys (use `.mcp.json.example` as template)
- `.claude/settings.local.json` — local Claude Code permissions
- `node_modules/`, `dist/` — build artifacts

## Environment Variables

- `OPENPROJECT_URL` — Base URL of the OpenProject instance (e.g. `https://openproject.kollect.biz/openproject`)
- `OPENPROJECT_API_KEY` — API key from OpenProject (My Account > Access Tokens)

## MCP Tools Provided

Projects: `list_projects`, `get_project`
Work Packages: `list_work_packages`, `get_work_package`, `create_work_package`, `update_work_package`, `add_work_package_comment`
Attachments: `list_attachments`, `upload_attachment`, `delete_attachment`
Relations: `list_relations`, `create_relation`, `delete_relation`
Lookup: `list_statuses`, `list_types`, `list_priorities`
Users: `get_me`, `list_users`
Time: `list_time_entries`, `log_time`
Versions: `list_versions`
Activities: `list_work_package_activities`

## Conventions

- Commits follow [Conventional Commits](https://www.conventionalcommits.org/) (enforced by pre-commit hook via commitizen)
- OpenProject API uses HAL+JSON; link hrefs follow the pattern `/api/v3/<resource>/<id>`
- Work package updates require `lockVersion` for optimistic concurrency (handled automatically by client)
- Tool handlers format HAL+JSON responses into human-readable text summaries