runbook-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 an MCP (Model Context Protocol) server that provides Claude with access to Runbook's document management and workflow automation capabilities. The server exposes tools for searching articles, managing books, and executing workflows through a standardized MCP interface.

Development Commands

# Build the project
npm run build

# Watch mode for development
npm run watch

# Run tests
npm test

# Run only unit tests
npm run unit

# Lint code
npm run lint

# Start the server locally
npm start

Architecture

The codebase follows a modular MCP server architecture:

Core Structure

• src/server.ts: MCP server setup using Server from @modelcontextprotocol/server (SDK v2)
• src/index.ts: stdio entry point. serveStdio(() => buildServer(...)) serves both protocol eras: 2026-07-28 (server/discover) and 2025-era clients (initialize)
• src/tools/tools.ts: All tool implementations (search, get, list, process operations)
• src/resources/resources.ts: Resource handlers for runbook://books/* and runbook://articles/* URIs
• src/queries/: GraphQL query definitions for Runbook API integration
• src/types.ts: TypeScript type definitions for all GraphQL operations

Key Patterns

Handler Objects: Both tools and resources use handler objects with description, inputSchema, and handler properties. Tools are dynamically registered using Object.entries(toolHandlers).

GraphQL Integration: Uses @runbook-docs/client with custom queries stored in separate files. All operations are strongly typed with TypeScript interfaces.

Configuration Management: Supports multiple config sources (CLI args > env vars > config file > defaults) with the config.ts module.

Prefix System: Tool names use withPrefix() function to support multiple server instances with different prefixes.