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.

Repository Overview

This is the Octopus Deploy Official MCP Server, which provides Model Context Protocol (MCP) tools that allow AI assistants like Claude Code to interact with Octopus Deploy instances. The server is implemented in TypeScript as a Node.js application.

Key Commands

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript to dist/
npm run dev          # Development mode with file watching
npm run lint         # Run ESLint on src/ directory
npm start            # Run compiled server from dist/

Testing the Server

# Credentials must be supplied via environment variables (they are not accepted as CLI flags
# to avoid exposure in the host process list).
OCTOPUS_API_KEY=API-KEY OCTOPUS_SERVER_URL=https://your-octopus.com npm start

# Server URL may also be supplied via the --server-url flag:
OCTOPUS_API_KEY=API-KEY npm start -- --server-url https://your-octopus.com

Architecture

Core Structure

• src/index.ts: Entry point that sets up the MCP server, parses CLI arguments, and initializes the transport layer
• src/tools/index.ts: Tool registration system that loads all available tools based on configuration
• src/types/toolConfig.ts: Tool configuration system with toolsets and version tracking

Tool System

Tools self-register into TOOL_REGISTRY and are organized by toolsets:

• core: Basic operations (spaces, environments)
• projects, deployments, releases: Project lifecycle operations
• tasks, tenants, kubernetes, machines, certificates: Specialized operations

Each tool file exports a registration that includes:

• Tool name and handler function
• Toolset classification
• Read-only flag (all tools are currently read-only)
• Minimum Octopus version requirement (optional)

MCP SDK: use registerTool, not tool

Minimum SDK is ^1.22.0 — do not lower it. Six tools (find_releases, find_runbooks, find_interruptions, find_events, update_feature_toggle, run_runbook) pass a full z.object(...) as inputSchema rather than a raw shape. SDK releases before 1.22.0 mistake that ZodObject instance for a raw shape and re-wrap it with z.object(...), dragging the instance's own internals — including the _cached: null field every zod v3 ZodObject carries — into the shape. JSON Schema conversion then dies on null._def and tools/list fails outright with -32603 Cannot read properties of null (reading '_def'), taking every tool down with it. src/tools/__tests__/toolsList.test.ts guards both the floor and the published schemas.