docs: add CLAUDE.md and README.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,57 @@
+# 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
+pnpm build          # Compile TypeScript to dist/
+pnpm start          # Run compiled server (requires build first)
+pnpm 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
+```
+
+## 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`
+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

README.md

@@ -0,0 +1,131 @@
+# OpenProject MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that connects AI assistants to [OpenProject](https://www.openproject.org/) via the v3 REST API.
+
+## Features
+
+- 18 MCP tools covering projects, work packages, relations, users, time tracking, versions, and activities
+- Stdio transport — works with Claude Code, Zed, Claude Desktop, and any MCP-compatible client
+- HAL+JSON responses formatted into readable text summaries
+- Optimistic concurrency control for work package updates
+
+## Prerequisites
+
+- Node.js 18+
+- pnpm
+- An OpenProject instance with an API key
+
+## Setup
+
+1. **Clone and install:**
+
+   ```bash
+   git clone https://gitea.kollect.biz/KollectRnD/MCP-OpenProject.git
+   cd MCP-OpenProject
+   pnpm install
+   ```
+
+2. **Configure environment:**
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Edit `.env` with your OpenProject URL and API key:
+
+   ```
+   OPENPROJECT_URL=https://your-instance.openproject.com
+   OPENPROJECT_API_KEY=your-api-key-here
+   ```
+
+3. **Build:**
+
+   ```bash
+   pnpm build
+   ```
+
+## Usage
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "openproject": {
+      "command": "node",
+      "args": ["dist/index.js"],
+      "env": {
+        "OPENPROJECT_URL": "https://your-instance.openproject.com",
+        "OPENPROJECT_API_KEY": "<YOUR_API_KEY>"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "openproject": {
+      "command": "node",
+      "args": ["/absolute/path/to/MCP-OpenProject/dist/index.js"],
+      "env": {
+        "OPENPROJECT_URL": "https://your-instance.openproject.com",
+        "OPENPROJECT_API_KEY": "<YOUR_API_KEY>"
+      }
+    }
+  }
+}
+```
+
+### Development
+
+Run directly without building:
+
+```bash
+pnpm dev
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all accessible projects |
+| `get_project` | Get project details by ID or identifier |
+| `list_work_packages` | List work packages with filtering |
+| `get_work_package` | Get work package details |
+| `create_work_package` | Create a new work package |
+| `update_work_package` | Update an existing work package |
+| `add_work_package_comment` | Add a comment to a work package |
+| `list_relations` | List relations for a work package |
+| `create_relation` | Create a relation between work packages |
+| `delete_relation` | Delete a relation |
+| `list_statuses` | List available statuses |
+| `list_types` | List available types (Task, Bug, Feature, etc.) |
+| `list_priorities` | List available priorities |
+| `get_me` | Get authenticated user profile |
+| `list_users` | List all users |
+| `list_time_entries` | List time entries |
+| `log_time` | Log time on a work package |
+| `list_versions` | List project versions/milestones |
+| `list_work_package_activities` | List work package activity history |
+
+## Project Structure
+
+```
+src/
+  index.ts      — Entry point, server bootstrap, tool registration
+  client.ts     — OpenProject API v3 HTTP client
+  tools.ts      — MCP tool definitions with Zod schemas
+  handlers.ts   — Tool handlers (API calls + response formatting)
+```
+
+## License
+
+Private — Kollect Systems