openproject-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Tonle OpenProject MCP Server - a Model Context Protocol (MCP) server that provides AI assistants with seamless integration to OpenProject (open-source project management software). The server implements MCP tools that wrap the OpenProject API v3, enabling natural language interactions for project management operations.

Development Commands

Running the Server

# Start STDIO server (for local MCP clients like Claude Desktop)
bun run start
# or
bun run index.ts

# Start HTTP server (for remote/web clients)
bun run start:http

# Development mode with auto-reload
bun run dev          # STDIO transport
bun run dev:http     # HTTP transport

# Test with MCP Inspector
bun run inspect      # Inspect STDIO server
bun run inspect:http # Inspect HTTP server

Running Tests

# Run all tests
bun test

# Run HTTP transport tests only
bun test tests/mcp-server.test.ts

# Run transport comparison tests
bun test tests/transport-comparison.test.ts

Package Management

# Install dependencies
bun install

# Update dependencies
bun update

Architecture

Core Components

1. index.ts - STDIO MCP server entry point

   • Uses shared server setup from src/server-setup.ts
   • Implements stdio transport for local integration (Claude Desktop, Cursor)
   • Best for spawning server as subprocess

2. http-server.ts - HTTP MCP server entry point

   • Uses shared server setup from src/server-setup.ts
   • Implements Streamable HTTP transport for remote clients
   • Supports session management with UUID-based sessions
   • Endpoints: /mcp (POST/GET/DELETE), /health (GET)

3. src/server-setup.ts - Shared MCP server configuration

   • Registers all MCP tools using @modelcontextprotocol/sdk
   • Tool handlers transform user-friendly parameters into API calls
   • Each tool follows pattern: validate input → call client → format response