redmine-mcp-server: 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 a Model Context Protocol (MCP) server for Redmine that provides comprehensive access to Redmine's REST API. The server automatically generates TypeScript handlers and schemas from a Redmine OpenAPI specification and extends them with custom attachment file handling capabilities.

Architecture

Core Components

• Generated API Layer: Located in src/__generated__/ (auto-generated, don't edit directly)

  • handlers.ts - MCP tool handlers for each Redmine API endpoint
  • http-schemas/ - Zod schemas for API requests/responses
  • tool-schemas.zod.js - Tool parameter schemas
  • http-client.ts - HTTP client with custom fetch integration

• Custom Extensions: Located in src/attachment/

  • File upload/download handlers that extend the generated API
  • Thumbnail download functionality
  • Direct file I/O operations with Redmine

• Configuration: src/config.ts

  • Environment-based configuration loading
  • Read-only mode support via REDMINE_MCP_READ_ONLY=true
  • Requires REDMINE_URL and REDMINE_API_KEY environment variables

• Main Server: src/server.ts

  • Registers all tools with read-only/write classification
  • Implements conditional tool registration based on read-only mode
  • Extensive tool registry covering all Redmine operations

Code Generation Workflow

1. OpenAPI Specification: redmine-openapi.yaml defines the Redmine API
2. Orval Configuration: orval.config.ts configures code generation
3. Generated Code: pnpm gen creates handlers and schemas in src/__generated__/
4. Post-Processing: post-generate.js adds custom fetch import to generated HTTP client

Development Commands

# Generate API code from OpenAPI spec
pnpm gen

# Build the project (includes generation)
pnpm build

# Build for publishing
pnpm prepublishOnly

Key Patterns