readonly-mssql-mcp-db: Instructions file for Claude Code

mcp-sqlserver — Project Guide for Claude

This file tells Claude (and any AI assistant using Claude Code / MCP) how to work in this repo. Read it in full before making changes. For deeper rules, follow the links at the bottom — each file is a focused, bite-sized ruleset.

What this project is

@tugberkgunver/mcp-sqlserver is a Model Context Protocol (MCP) server for Microsoft SQL Server. It exposes 39 tools across 7 categories (schema discovery, query, DDL, stored procedures, performance, DBA diagnostics, developer utilities, server management) so AI assistants can talk to SQL Server with enterprise-grade security controls.

• Package: @tugberkgunver/mcp-sqlserver on npm
• Repo: gunvertugberk/mcp-sqlserver on GitHub
• Current version: see package.json (version) and src/server.ts (McpServer version string) — keep them in sync
• License: MIT

Stack

• Language: TypeScript 5.8, strict: true
• Runtime: Node.js >=18
• Module system: Node16 ESM — imports must use .js extension even when importing .ts files (see coding-standards.md)
• Target: ES2022
• Key deps: @modelcontextprotocol/sdk, mssql (tedious), yaml, zod
• Optional dep: msnodesqlv8 for Windows SSPI auth

Commands

npm install          # install dependencies
npm run build        # tsc → dist/
npm run dev          # tsc --watch
npm test             # vitest run (238 tests)
npm run test:watch   # vitest in watch mode
npm start            # node dist/index.js (after build)
npm start -- --config ./mssql-mcp.yaml
npm start -- --http 3000

Testing: Vitest with 238 tests across 10 files covering security utils, formatters, and all 38 tool handlers. Run npm test before every commit.

Directory map

src/
├── index.ts               # CLI entry: arg parsing, transport (stdio/http), graceful shutdown
├── server.ts              # createServer(config) — wires all tool groups, registers list_servers
├── config.ts              # AppConfig types, loadConfig(), resolveServer(), single+multi-server loading
├── database.ts            # Connection pool per serverName, buildSqlConfig() per auth type, executeQuery()
├── utils/
│   ├── security.ts        # escapeIdentifier, validateQuery, isDatabaseAllowed, isSchemaAllowed,
│   │                      # applyMasking, ensureRowLimit, SecurityError
│   └── formatter.ts       # formatResultSet (markdown), formatResultSetJson, ISO date handling
└── tools/
    ├── schema.ts          # 9 schema discovery tools
    ├── query.ts           # execute_query, execute_mutation
    ├── ddl.ts             # execute_ddl (admin / allowDDL only)
    ├── procedure.ts       # list_procedures, describe_procedure, execute_procedure
    ├── performance.ts     # query plans, active queries, table/index/server/db stats, missing indexes
    ├── dba.ts             # wait stats, deadlocks, blocking, backups, query store, rebuild index, health
    └── utility.ts         # compare_schemas, generate_code, ER diagram, sample/test data, export_query