mcp-sheet-filler: 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

MCP server that provides tools for storing and safely auto-filling tabular data using Google Sheets as the storage backend. The server prevents overwriting already-filled values.

Development Commands

npm install          # Install dependencies
npm run build        # Build TypeScript
npm run dev          # Run in dev mode (tsx, stdio)
npm run dev:http     # Run in dev mode (tsx, HTTP)
npm start            # Start MCP server (stdio)
npm run start:http   # Start MCP server (HTTP)
npm run auth         # Run OAuth authentication flow
npm run lint         # Run ESLint
npm test             # Run tests in watch mode (vitest)
npm run test:run     # Run tests once
npm test -- src/path/to/test.ts  # Run single test file
npm run docs:tools   # Regenerate docs/tools.md after modifying tools

After adding, removing, or changing tool descriptions/schemas, run npm run docs:tools to regenerate docs/tools.md.

Transport Modes

The server supports two transport modes:

• stdio (default) - Standard input/output, for local MCP client integration
• http - Streamable HTTP transport for remote deployment

HTTP Transport

Set TRANSPORT=http to enable HTTP mode. HTTP transport requires OAuth authentication per the MCP Authorization specification (RFC 9728).

Required environment variables for HTTP transport:

• RESOURCE_URL - Public URL of this server
• GOOGLE_OAUTH_CLIENT_ID - Google OAuth client ID
• GOOGLE_OAUTH_CLIENT_SECRET - Google OAuth client secret

The server exposes:

Method	Path	Description
POST	/mcp	MCP JSON-RPC endpoint (requires auth)
GET	/mcp	SSE stream (requires auth)
DELETE	/mcp	Session teardown (requires auth)
GET	/health	Health check (no auth)
GET	/.well-known/oauth-protected-resource/mcp	RFC 9728 Protected Resource Metadata (no auth)