deployhq-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

DeployHQ MCP Server is a Model Context Protocol (MCP) server that enables AI assistants (Claude Desktop and Claude Code) to interact with DeployHQ deployments. It provides two operational modes:

1. stdio transport (primary): npm package for direct use with npx deployhq-mcp-server
2. HTTP/SSE transports (optional): Express server for hosted deployment

Development Commands

Build & Type Checking

npm run build         # Compile TypeScript to dist/
npm run type-check    # Type check without emitting files
npm run clean         # Remove dist/ directory

Development & Testing

npm run dev           # Watch mode for hosted server (index.ts)
npm run start         # Run compiled hosted server
npm run lint          # ESLint on src/

Testing stdio Transport Locally

# Build first
npm run build

# Test with environment variables
DEPLOYHQ_EMAIL="email" DEPLOYHQ_API_KEY="pass" DEPLOYHQ_ACCOUNT="account" node dist/stdio.js

# Or use the test script
export DEPLOYHQ_EMAIL="email"
export DEPLOYHQ_API_KEY="pass"
export DEPLOYHQ_ACCOUNT="account"
./test-stdio.sh

Testing with Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "deployhq-local": {
      "command": "node",
      "args": ["/absolute/path/to/dist/stdio.js"],
      "env": {
        "DEPLOYHQ_EMAIL": "email",
        "DEPLOYHQ_API_KEY": "pass",
        "DEPLOYHQ_ACCOUNT": "account"
      }
    }
  }
}

Restart Claude Desktop to test.

Architecture

Core Components

Two Entry Points:

• src/stdio.ts → dist/stdio.js (bin entry, stdio transport for MCP clients)
• src/index.ts → dist/index.js (Express server for hosted deployment)

Shared Core:

• src/mcp-server.ts: Factory function createMCPServer(username, password, account) that returns a configured MCP Server instance. Used by both stdio and hosted modes.
• src/tools.ts: Defines 6 MCP tools (list_projects, get_project, list_servers, list_deployments, get_deployment, create_deployment) with Zod validation schemas
• src/api-client.ts: DeployHQClient class for HTTP Basic Auth API calls to DeployHQ REST API. Uses node-fetch for Node 16+ compatibility.