fastpanel-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.

What this is

An MCP (Model Context Protocol) server that exposes a FastPanel 2 hosting panel's REST API as tools. It runs over stdio and is consumed by Claude Code, Claude Desktop, Cursor, etc. The entire server is ~850 lines across four src/ files.

Commands

pnpm build        # tsc → dist/ (the published artifact; bin is dist/index.js)
pnpm typecheck    # tsc --noEmit — run this to validate changes; there is no test suite
pnpm dev          # tsx watch src/index.ts — hot-reload for local iteration
pnpm inspect      # MCP Inspector GUI against dist/index.js
pnpm start        # node dist/index.js

There are no unit tests and no linter. The only runtime check is scripts/smoke.mjs, which spawns the built server, runs initialize → tools/list, and calls the read tools against a live panel:

FASTPANEL_URL=… FASTPANEL_TOKEN=… node scripts/smoke.mjs

Always pnpm build before running smoke or inspect — they execute dist/, not src/.

Architecture

Four layers, registered in index.ts:main():

• config.ts — loadConfig() reads env (FASTPANEL_URL, FASTPANEL_TOKEN, optional FASTPANEL_WRITE_TOKEN, FASTPANEL_INSECURE_TLS, FASTPANEL_TIMEOUT_MS, and the optional FASTPANEL_SSH_* block) and throws on missing required vars. The dual-token split lives here: writeToken is null when unset; ssh is null until FASTPANEL_SSH_HOST is set.
• client.ts — FastPanelClient wraps undici with one persistent Agent. get() uses the read token; post/patch/put/delete() set requiresWrite:true and use the write token, throwing FastPanelWriteDisabledError if it's null. >=400 responses throw FastPanelError carrying status + parsed body.
• ssh.ts — SshClient shells out to the operator's own ssh (via execFile, no library dep, no local shell) to run commands on the panel host. Opt-in and host-agnostic — nothing about a specific server is baked in; host/user/port/key all come from FASTPANEL_SSH_*. exec() resolves with stdout/stderr/exit code (does not throw on non-zero, so callers can read e.g. nginx -t failures); throws SshDisabledError when SSH is unconfigured. upload() pushes a local file/dir with rsync (scp fallback if local rsync is missing; --delete is rsync-only) and putContent() streams an inline buffer into a remote file via cat over spawn — both reuse the same connection options as exec() and never route bytes through the model for the rsync path. Dynamic values interpolated into remote commands MUST go through shq().
• tools.ts — registerTools(server, client, ssh) registers every tool. This is where all FastPanel API knowledge lives.