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

This is a GMAT Documentation MCP (Model Context Protocol) Server that provides semantic search capabilities over GMAT documentation. The server scrapes, parses, chunks, and embeds GMAT documentation content to enable AI assistants to access comprehensive GMAT information through vector search.

Architecture

The project follows a modular architecture with the following phases:

Phase 1: Setup and Dependencies

• TypeScript-based Node.js project using @modelcontextprotocol/sdk and zod
• Uses pnpm as package manager (version 10.10.0)
• Core dependencies for scraping (axios, cheerio), embeddings (openai), and vector search

Phase 2: Data Ingestion Pipeline

• Scraping: src/utils/scraper.ts - Fetches HTML from GMAT documentation site
• Parsing: src/utils/parser.ts - Converts HTML to structured chunks using Cheerio, chunks by headings
• Embedding: src/utils/embedder.ts - Generates embeddings using OpenAI's text-embedding-3-small model
• Caching: src/utils/cache.ts - Persists embedded chunks to filesystem for performance

Phase 3: MCP Server

• Search Engine: src/utils/search.ts - In-memory cosine similarity search over embeddings
• Local Embedder: src/utils/localEmbedder.ts - Query/corpus embeddings via transformers.js (all-MiniLM-L6-v2, 384d); no API key needed at runtime. src/reembedLocal.ts migrates an OpenAI-embedded corpus to local embeddings (npm run reembed).
• GMAT Tools: src/utils/gmat.ts - runGmat (async headless execution + outcome classification), getGmatIdioms, listGmatSamples, getGmatSample
• Server: src/index.ts - Main MCP server that loads cached data and handles protocol requests

Common Commands

# Setup (install dependencies)
pnpm install

# Build TypeScript
pnpm run build  # Will need to add to package.json

# Development mode
pnpm run dev    # Will need to add to package.json

# One-time data ingestion (run before starting server)
pnpm run setup  # Will need to add to package.json

# Start MCP server
pnpm start      # Will need to add to package.json

# Tests
pnpm test       # Will need to add to package.json