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.

Documentation

When you add, remove, or change MCP tools or server behavior, update the docs page using a Haiku sub-agent:

Agent({
  subagent_type: "haiku",
  model: "haiku",
  description: "Update MCP server docs page",
  prompt: "Update apps/web/src/pages/docs/mcp-server.astro to reflect: [describe what changed]. Explain what each tool does and when AI tools call it. No em dashes."
})

Docs page: apps/web/src/pages/docs/mcp-server.astro

Build & Dev

From the monorepo root:

npm run mcp:build    # Build with tsup
npm run mcp:watch    # Watch mode
npm run mcp:test     # Run tests

Locally (from this directory):

npx tsup             # Build
npx tsup --watch     # Watch
node --import tsx --test $(find src/test -name '*.test.ts' | tr '\n' ' ')  # Run tests
tsc --noEmit         # Type-check only

No linter is configured for this package.

Architecture

This package (@keepgoingdev/mcp-server) has two runtime roles driven by a single entry point (src/index.ts):

1. MCP server (default): Connects via stdio to MCP hosts (Claude Code, Cursor, etc.). Exposes tools and prompts.
2. Legacy CLI mode: When invoked with flags like --save-checkpoint, --heartbeat, etc., runs a one-shot handler and exits. These flags are deprecated - the server now tries to delegate to the keepgoing CLI binary and falls back to built-in handlers if unavailable.

Entry Point Dispatch

src/index.ts checks process.argv for known CLI flags first. If a flag matches, it checks whether the standalone keepgoing CLI is on PATH and delegates to it with a deprecation notice. If the CLI is unavailable, the legacy handler in src/cli/ runs directly. If no flag matches, the MCP server starts.

Tools (src/tools/)

Each file exports a register<Name>(server, reader, workspacePath?) function. All tools follow the same pattern: validate input with zod, read data via KeepGoingReader (or call shared utilities for git data), and return { content: [{ type: 'text', text }] }.