docs: add CLAUDE.md and README.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user