mssql-mcp-node: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

mssql-mcp-node is an npm-published MCP server (CommonJS, Node ≥ 18, no build step) that exposes one or more Microsoft SQL Server databases to MCP clients via 11 tools, a CSV table resource template, and two prompts. It runs over stdio (src/index.js, also the bin) or stateless Streamable HTTP (src/http.js, POST /mcp). README.md is the user-facing reference (tool catalog, env vars, security model) and must be updated when tools or env vars change.

Commands

npm test                                   # all unit tests (node --test, no DB needed)
node --test test/safety.test.js            # one file
node --test --test-name-pattern="rollback" test/safety.test.js   # one test by name
npx eslint .                               # lint (no npm script for this)
npx prettier --check .                     # format check; --write to fix
npm run smoke                              # wire-level HTTP+stdio test with fake creds, no DB (scripts/smoke.js)
MSSQL_TEST_PASSWORD='...' npm run integration   # real SQL Server; creates+drops mcp_test_<ts> (see scripts/integration.js header for Docker one-liner)
npm start / npm run dev                    # stdio (dev = nodemon)
npm run start:http / npm run dev:http      # HTTP on $PORT (default 3000)
npx @modelcontextprotocol/inspector node src/index.js   # interactive e2e

Server needs MSSQL_* env (single-db) or MSSQL_<NAME>_* (multi-db) — see .env.example. .env is gitignored and loaded via dotenv in both entry points.

Architecture

Request flow: entry point → createServer() in src/server.js → tools/resources/prompts.registerAll(server). The HTTP entry creates a fresh McpServer + transport per POST (stateless mode); stdio creates one for the process lifetime. Both close all pools on SIGINT/SIGTERM.

Tool module contract. Every file in src/tools/ exports { name, config, handler } where config is the registerTool config (title, description, Zod inputSchema/outputSchema shapes, annotations). src/tools/index.js is an explicit array, not a directory scan — a new tool must be added there. Handlers all follow the same shape: