70 lines
2.7 KiB
Markdown
70 lines
2.7 KiB
Markdown
# 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
|