2.7 KiB

Raw Permalink Blame History

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

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 (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

2.7 KiB Raw Permalink Blame History