Skip to content

CLAUDE.md

Latest commit

 

History

History
104 lines (76 loc) · 4.88 KB

CLAUDE.md

File metadata and controls

104 lines (76 loc) · 4.88 KB

This file provides guidance to Claude Code when working with this repository.

Project Overview

ToolHive Studio is an Electron desktop application for managing MCP (Model Context Protocol) servers. Built with React, TypeScript, and Vite. The Electron app bundles the ToolHive CLI (thv) binary.

Build and Development Commands

pnpm install              # Install dependencies (runs rebuild for native modules)
pnpm run start            # Start dev server with hot reload
pnpm run lint             # Run ESLint
pnpm run type-check       # TypeScript checking (both app and node configs)
pnpm run format           # Format with Prettier
pnpm run test:nonInteractive  # Run unit tests once
pnpm run test             # Run unit tests in watch mode
pnpm run test:coverage    # Unit tests with coverage
pnpm run e2e              # Package + run Playwright e2e tests
pnpm run knip             # Detect unused code
pnpm run generate-client  # Fetch OpenAPI spec + regenerate API client

Husky/lint-staged automatically run lint + format on staged .ts/.tsx files. Run pnpm run type-check manually before committing — it is not covered by the hook.

Environment Requirements

  • Node.js >=24 <25 (use nvm use — .nvmrc is present)
  • pnpm package manager
  • Docker daemon must be running (required by ToolHive)

Common Gotchas

  • Docker must be running before pnpm run start — ToolHive manages containers, so the daemon is required even in dev
  • Node version mismatch: native modules (better-sqlite3) break on wrong Node version. Always nvm use first
  • Stale generated types: if type errors reference API types, run pnpm run generate-client to refresh
  • Native module rebuild: after Node version change or fresh install issues, run pnpm run rebuild
  • Electron test runner: unit tests run through Electron (vitest:electron), not plain Node — required for native module compatibility
  • All commands from root: always run pnpm commands from the repository root, not from subdirectories

Auto-Generated Code — Never Edit Manually

These files are generated and will be overwritten:

  • renderer/src/route-tree.gen.ts — Generated by TanStack Router plugin from route files
  • common/api/generated/* — Generated by pnpm run generate-client from OpenAPI spec

To update generated API client: edit the OpenAPI spec source, then run pnpm run generate-client. To update routes: add/modify files in renderer/src/routes/, the route tree regenerates automatically.

Architecture

Electron Process Model

  • main/ — Main process: app lifecycle, IPC handlers, database (SQLite), auto-update, deep links, CLI integration
  • renderer/ — Renderer process: React UI, routing, API calls, state management
  • preload/ — Preload scripts: bridge between main and renderer via window.electronAPI
  • common/ — Shared code: generated API client, types, constants

Renderer Architecture

  • Routing: TanStack Router with file-based convention in renderer/src/routes/
    • __root.tsx — root layout
    • Route files use dot-notation for nesting (e.g., logs.$groupName.$serverName.tsx)
  • State: TanStack React Query for server state, React Context for app state (theme, permissions)
  • API: Generated client from OpenAPI spec in common/api/generated/
  • UI: Radix UI primitives + Tailwind CSS + CVA for component variants
  • Forms: React Hook Form + Zod validation

Code Conventions

  • File naming: always kebab-case (e.g., card-mcp-server.tsx, use-auto-update.ts)
  • Components: PascalCase exports, functional components with hooks
  • Path aliases: @/* (renderer/src), @common/* (common), @utils/* (utils), @mocks/* (mocks)
  • Imports: use path aliases, not relative paths for cross-directory imports
  • Exports: prefer named exports over default exports

Testing

  • Unit tests: Vitest + Testing Library + MSW for API mocking
  • Test location: __tests__/ directories colocated with source
  • API mocking: Auto-generated MSW fixtures from OpenAPI spec. See docs/mocks.md
    • Fixtures in renderer/src/common/mocks/fixtures/
    • Use .override() / .overrideHandler() for test-specific responses
    • Use recordRequests() to assert on API calls
  • E2E tests: Playwright in e2e-tests/

Running a Single Test

pnpm run test run path/to/file.test.tsx

Commit and PR Guidelines

  • Follow Conventional Commits: feat:, fix:, docs:, test:, chore:, etc.
  • PR titles must follow conventional commit format (validated by CI)
  • Keep PRs small and focused (size/XS or size/S preferred)
  • See CONTRIBUTING.md for full guidelines

Deep Links

  • Protocol: toolhive-gui://v1/<intent>?<params>
  • Handled by main process, routed to TanStack Router
  • See .claude/skills/deep-links/ for implementation guidance