garoon-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 Garoon MCP (Model Context Protocol) server that provides tools for interacting with the Garoon API. Garoon is a groupware application by Cybozu used for scheduling, collaboration, and organizational management. Garoon bundles various applications like the following.

• Scheduler(スケジュール)
• Workflow(ワークフロー)
• E-mail(メール)
• Messages(メッセージ)
• Space(スペース)
• Bulletin Board(掲示板)
• MultiReport(マルチレポート)
• Portal(ポータル)
• Cabinet(ファイル管理)
• Presence indicators(在籍情報)
• and more.

This MCP server mainly uses REST API. Garoon also has SOAP API, but it is legacy and its use is not recommended.

Development Commands

Setup

# Install dependencies
pnpm install --frozen-lockfile

# Build the TypeScript project
pnpm run build

Development

# Run with MCP Inspector for debugging (requires direnv; see CONTRIBUTING.md)
pnpm run dev

# Build TypeScript
pnpm run build

# Start the MCP server
pnpm run start

# Type checking
pnpm run typecheck

Testing

# Run all tests
pnpm run test

# Run tests with coverage
pnpm run test:coverage

# Watch mode for test development
pnpm run test:watch

Docker

# Build Docker image
scripts/build-docker.sh

# Run with Docker (configure in .vscode/mcp.json)
docker run --rm -i \
  -e GAROON_BASE_URL \
  -e GAROON_USERNAME \
  -e GAROON_PASSWORD \
  -e https_proxy \  # Optional
  -e http_proxy \   # Optional
  -e GAROON_PFX_FILE_PATH \  # Optional
  -e GAROON_PFX_FILE_PASSWORD \  # Optional
  -e GAROON_BASIC_AUTH_USERNAME \  # Optional
  -e GAROON_BASIC_AUTH_PASSWORD \  # Optional
  -e GAROON_PUBLIC_ONLY \  # Optional
  garoon-mcp-server:latest

Architecture

Directory Layout

The source tree is organized by Garoon application, mirroring the Garoon REST API namespaces:

src/
  index.ts                 # composition only
  config.ts / client.ts / constants.ts
  core/                    # protocol-level infrastructure: register.ts (defineTool/registerTools), error-handler.ts, structured-output.ts
  schemas/                 # cross-application Garoon vocabulary (id, user, organization, datetime, pagination)
  applications/<app>/      # one directory per Garoon application (schedule, bulletin, base), matching Garoon REST API namespaces
    index.ts               # aggregated tool exports
    schemas/               # schemas shared by two or more tools within the application
    tools/<tool>/          # index.ts, handler.ts, input-schema.ts, output-schema.ts, tests/