# openproject-mcp

`openproject-mcp` is a Model Context Protocol (MCP) server that connects AI assistants (such as Claude Desktop, Cursor, and Antigravity) to [OpenProject](https://github.com/opf/openproject) via OpenProject's REST API v3.

It allows agents to browse, query, and reason about OpenProject workspaces using personal API keys over standard MCP transports (stdio).

---

## Features

- **Project Discovery**: List accessible projects, inspect hierarchies, and retrieve project details.
- **Work Package Browsing**: Query work packages with status, type, and custom filters; inspect work package details and relationships.
- **Saved Queries (Views)**: Discover and execute saved project and global queries.
- **Taxonomies & Metadata**: Query work package types (Tasks, Bugs, Features), statuses, priorities, and users to enable structured agent reasoning.
- **HAL+JSON Normalization**: Converts OpenProject's verbose HAL+JSON representations into concise, token-efficient structures.
- **Secure Authentication**: Uses OpenProject Personal API tokens via HTTP Basic Auth (`apikey:<token>`) with zero credential storage inside the codebase.

---

## Project Documentation

- [AGENTS.md](AGENTS.md): Guidelines, coding standards, and workflow instructions for AI coding agents.
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): System architecture, layer diagrams, tool schemas, and technical design.
- [docs/DECISIONS.md](docs/DECISIONS.md): Architectural Decision Records (ADRs) documenting stack choices, protocols, and designs.
- [docs/TODO.md](docs/TODO.md): Task tracking, roadmap, and agent check-in policies.

---

## Running via Docker

You can run `openproject-mcp` without installing Bun or cloning this repository by using the container image published to GitHub Container Registry (`ghcr.io`).

### Docker Quickstart

Run interactively with standard I/O streaming:

```bash
docker run -i --rm \
  -e OPENPROJECT_BASE_URL="https://openproject.example.com" \
  -e OPENPROJECT_API_KEY="your-api-key" \
  ghcr.io/stereotypicalcat/openproject-mcp:latest
```

### Read-Only Mode

To ensure the server strictly restricts capabilities to read-only queries and inspection:

```bash
docker run -i --rm \
  -e OPENPROJECT_BASE_URL="https://openproject.example.com" \
  -e OPENPROJECT_API_KEY="your-api-key" \
  ghcr.io/stereotypicalcat/openproject-mcp:latest --read-only
```

*(Alternatively, pass `-e OPENPROJECT_READ_ONLY=true`.)*

### MCP Client Configuration

#### Claude Desktop

Add the following to your `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "openproject": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENPROJECT_BASE_URL=https://openproject.example.com",
        "-e",
        "OPENPROJECT_API_KEY=your-api-key",
        "ghcr.io/stereotypicalcat/openproject-mcp:latest",
        "--read-only"
      ]
    }
  }
}
```

#### Cursor

Add the following to `.cursor/mcp.json` (or Cursor Settings > Features > MCP):

```json
{
  "mcpServers": {
    "openproject": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENPROJECT_BASE_URL=https://openproject.example.com",
        "-e",
        "OPENPROJECT_API_KEY=your-api-key",
        "ghcr.io/stereotypicalcat/openproject-mcp:latest",
        "--read-only"
      ]
    }
  }
}
```

---

## Quickstart: Local OpenProject Test Stack

A complete OpenProject 17 environment with PostgreSQL 17 and Memcached is included via Docker Compose for local testing and agentic validation.

### Prerequisites

- Docker and Docker Compose (v2+)
- [Bun](https://bun.sh) (>= 1.2 / 1.3)

### 1. Start the Environment & Seed Data

Run the start script to boot the containers, wait for health checks, seed sample data, and generate a personal API token:

```bash
./scripts/start.sh
```

Or step-by-step:

```bash
# 1. Start the Docker Compose stack in the background
docker compose up -d

# 2. Wait for health checks, seed test data, and generate credentials
./scripts/seed.sh
```

This will automatically create `.env.test` and `.env.local` containing the generated credentials:

```env
OPENPROJECT_BASE_URL=http://localhost:8080
OPENPROJECT_API_KEY=opapi-...
OPENPROJECT_TEST_PROJECT=mcp-test-project
```

### 2. Verify OpenProject is Running

Once seeded, OpenProject is accessible at [http://localhost:8080](http://localhost:8080):
- **Username**: `admin`
- **Password**: `admin12345678`

You can verify the API v3 connection directly using `curl`:

```bash
curl -u "apikey:$(grep OPENPROJECT_API_KEY .env.test | cut -d= -f2)" \
  http://localhost:8080/api/v3/projects
```

### 3. Stop the Stack

```bash
./scripts/stop.sh
# or
docker compose down
```

To also remove database and asset volumes:

```bash
docker compose down -v
```

---

## MCP Server Development (Bun)

Install project dependencies:

```bash
bun install
```

Start the MCP server over stdio:

```bash
bun run src/index.ts
```

Run test suite:

```bash
bun test
```

Type-check:

```bash
bun run typecheck
```

---

## Configuration

The MCP server accepts configuration through environment variables or a `.env` file:

| Variable | Description | Default |
| :--- | :--- | :--- |
| `OPENPROJECT_BASE_URL` | Base URL of the OpenProject instance | `http://localhost:8080` |
| `OPENPROJECT_API_KEY` | Personal API token (created under My Account > Access tokens) | - |
| `OPENPROJECT_READ_ONLY` | Run server in read-only mode (`true` / `false` or `--read-only`) | `false` |
| `PORT` | Local port for the Docker Compose web container | `8080` |
| `TAG` | OpenProject container image tag | `17-slim` |
| `POSTGRES_VERSION` | PostgreSQL container image tag | `17` |

### Read-Only Mode

To ensure AI assistants cannot make any modifications to your OpenProject instance, enable read-only mode:

```bash
OPENPROJECT_READ_ONLY=true bun run src/index.ts
# or
bun run src/index.ts --read-only
```

When active, write tools are omitted from the tool manifest and blocked by execution guards.

---

## Development Roadmap

- **Phase 1 (Current)**: Read-only browsing tools for projects, work packages, queries, and taxonomies.
- **Phase 2**: Mutating operations (create/update work packages, add comments, log time).
- **Phase 3**: Attachment reading and document resources.
- **Phase 4**: SSE / Stream transport for remote server deployments.

---

## License

GNU General Public License v3.0 (aligned with OpenProject Community Edition).