/microsoft:mssql

Manage the vendored MssqlMcp servers (Node.js and .NET). The plugin ships with pre-built servers - this skill is for diagnostics, rebuilding, and upstream updates.

Subcommands

Parse the first positional argument from $ARGUMENTS:

Subcommand	Description
`status`	Check environment, verify artifacts, test connectivity (default if no args)
`rebuild`	Rebuild servers from existing source code
`update`	Pull latest from upstream GitHub and rebuild

Flags

Flag	Applies to	Description
`--node`	`status`, `rebuild`	Only operate on Node.js server
`--dotnet`	`status`, `rebuild`	Only operate on .NET server
`--check`	`update`	Show what would change without applying

Subcommand: status (default)

Check environment configuration, verify build artifacts exist, and test database connectivity.

Step 1: Check Environment Variables

echo "--- Node (Azure/cloud) ---"
echo "MSSQL_NODE_AUTH_TYPE: ${MSSQL_NODE_AUTH_TYPE:-azure-default (default)}"
echo "MSSQL_NODE_SERVER: ${MSSQL_NODE_SERVER:-localhost (default)}"
echo "MSSQL_NODE_DATABASE: ${MSSQL_NODE_DATABASE:-master (default)}"
echo "MSSQL_NODE_USER: ${MSSQL_NODE_USER:-(not set)}"
echo "MSSQL_NODE_PASSWORD: ${MSSQL_NODE_PASSWORD:+(set)}"
echo "MSSQL_NODE_ENCRYPT: ${MSSQL_NODE_ENCRYPT:-true (default)}"
echo "MSSQL_NODE_READONLY: ${MSSQL_NODE_READONLY:-true (default)}"
echo "MSSQL_NODE_TRUST_CERT: ${MSSQL_NODE_TRUST_CERT:-true (default)}"
echo ""
echo "--- .NET (local) ---"
echo "MSSQL_CONNECTION_STRING: ${MSSQL_CONNECTION_STRING:+(custom)}"
echo "MSSQL_DOTNET_SERVER: ${MSSQL_DOTNET_SERVER:-localhost (default)}"
echo "MSSQL_DOTNET_DATABASE: ${MSSQL_DOTNET_DATABASE:-master (default)}"
echo "MSSQL_DOTNET_AUTH_TYPE: ${MSSQL_DOTNET_AUTH_TYPE:-windows (default)}"
echo "MSSQL_DOTNET_READONLY: ${MSSQL_DOTNET_READONLY:-true (default)}"

Step 2: Verify Build Artifacts

# Node.js - check bundle exists (single-file, no node_modules needed at runtime)
ls ${CLAUDE_PLUGIN_ROOT}/vendor/MssqlMcp/Node/bundle/index.cjs

# Node.js - check dist exists (used by bundle step)
ls ${CLAUDE_PLUGIN_ROOT}/vendor/MssqlMcp/Node/dist/index.js

# .NET - check published exe exists
ls ${CLAUDE_PLUGIN_ROOT}/vendor/MssqlMcp/dotnet-publish/MssqlMcp.exe

Report:

Build Artifacts

  Node.js:
    bundle/index.cjs: Found (runtime entry point)
    dist/index.js: Found (used by bundle step)

  .NET:
    dotnet-publish/MssqlMcp.exe: Found (pre-built, ready to use)

Step 3: Test Database Connectivity

# For LocalDB
sqlcmd -S "(localdb)\MSSQLLocalDB" -d master -Q "SELECT @@VERSION" -C

# For custom server
sqlcmd -S "${MSSQL_NODE_SERVER}" -d "${MSSQL_NODE_DATABASE}" -Q "SELECT @@VERSION" -C

Step 4: Report

SQL Server MCP Status

Environment:
  Server: (localdb)\MSSQLLocalDB
  Database: master
  Auth: azure-default
  Mode: Read-only

Build Status:
  mssql-node: Ready (bundle/index.cjs found)
  mssql-dotnet: Ready (dotnet-publish/MssqlMcp.exe found)

Connectivity:
  sqlcmd test: Success
  SQL Version: Microsoft SQL Server 2022 (RTM)

Status: READY

Subcommand: rebuild

Rebuild servers from existing source code. Use after modifying source or fixing a corrupted build.

Prerequisites

Node.js: Node.js 18+ with npm
.NET: .NET 8 SDK

Step 1: Check Prerequisites

node --version
npm --version
dotnet --version

Step 2: Build Node.js (unless --dotnet)

cd ${CLAUDE_PLUGIN_ROOT}/vendor/MssqlMcp/Node
npm install
npm run build
npm run bundle

Verify:

ls dist/index.js
ls bundle/index.cjs

Step 3: Build .NET (unless --node)

cd ${CLAUDE_PLUGIN_ROOT}/vendor/MssqlMcp/dotnet
dotnet publish MssqlMcp/MssqlMcp.csproj -c Release -o ../dotnet-publish

Verify:

ls ${CLAUDE_PLUGIN_ROOT}/vendor/MssqlMcp/dotnet-publish/MssqlMcp.exe

Step 4: Force-add rebuilt artifacts to git

git add -f plugins/microsoft/vendor/MssqlMcp/dotnet-publish/
git add -f plugins/microsoft/vendor/MssqlMcp/Node/bundle/
git add -f plugins/microsoft/vendor/MssqlMcp/Node/dist/

Step 5: Report

MssqlMcp Rebuild Complete

Node.js Server:
  Output: bundle/index.cjs (single-file bundle with all deps)

.NET Server:
  Output: dotnet-publish/MssqlMcp.exe

Artifacts re-tracked in git. Commit when ready.

Subcommand: update

Pull latest from upstream Azure-Samples/SQL-AI-samples and rebuild.

WARNING: Local Patches Will Be Overwritten

This plugin includes local patches (documented in vendor/MssqlMcp/PATCHES.md). After updating, you MUST re-apply these patches.

Step 1: Clone Upstream to Temp

TEMP_DIR=$(mktemp -d)
cd "$TEMP_DIR"

git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/Azure-Samples/SQL-AI-samples.git
cd SQL-AI-samples
git sparse-checkout set MssqlMcp

LATEST_COMMIT=$(git rev-parse --short HEAD)
LATEST_MESSAGE=$(git log -1 --format=%s)

Step 2: Compare Versions

cd "${CLAUDE_PLUGIN_ROOT}"
CURRENT_COMMIT=$(cat plugins/microsoft/vendor/MssqlMcp/VERSION 2>/dev/null || echo "unknown")

Report:

MssqlMcp Update Check

  Current: ${CURRENT_COMMIT}
  Upstream: ${LATEST_COMMIT} - ${LATEST_MESSAGE}

If --check, stop here.

Step 3: Copy Files

# Backup current
mv plugins/microsoft/vendor/MssqlMcp plugins/microsoft/vendor/MssqlMcp.bak

# Copy new files (preserving build artifacts and parent .gitignore from backup)
cp -r "$TEMP_DIR/SQL-AI-samples/MssqlMcp" plugins/microsoft/vendor/
cp -r plugins/microsoft/vendor/MssqlMcp.bak/Node/dist plugins/microsoft/vendor/MssqlMcp/Node/ 2>/dev/null || true
cp -r plugins/microsoft/vendor/MssqlMcp.bak/Node/bundle plugins/microsoft/vendor/MssqlMcp/Node/ 2>/dev/null || true
cp -r plugins/microsoft/vendor/MssqlMcp.bak/Node/node_modules plugins/microsoft/vendor/MssqlMcp/Node/ 2>/dev/null || true
cp -r plugins/microsoft/vendor/MssqlMcp.bak/dotnet-publish plugins/microsoft/vendor/MssqlMcp/ 2>/dev/null || true
cp plugins/microsoft/vendor/MssqlMcp.bak/.gitignore plugins/microsoft/vendor/MssqlMcp/ 2>/dev/null || true

# Write version file
echo "${LATEST_COMMIT}" > plugins/microsoft/vendor/MssqlMcp/VERSION

# Cleanup
rm -rf plugins/microsoft/vendor/MssqlMcp.bak
rm -rf "$TEMP_DIR"

Step 4: Rebuild Node.js

cd plugins/microsoft/vendor/MssqlMcp/Node
npm install
npm run build
npm run bundle

Step 5: Rebuild .NET

cd plugins/microsoft/vendor/MssqlMcp/dotnet
dotnet publish MssqlMcp/MssqlMcp.csproj -c Release -o ../dotnet-publish

Step 6: Re-Apply Local Patches

IMPORTANT: Read and re-apply patches from PATCHES.md:

cat plugins/microsoft/vendor/MssqlMcp/PATCHES.md

Current patches to re-apply:

Multi-auth support in Node/src/index.ts:
- Add AuthType type
- Replace createSqlConfig() with multi-auth factory
- Update ensureSqlConnection() for SQL auth

After re-applying, rebuild:

cd plugins/microsoft/vendor/MssqlMcp/Node
npm run build && npm run bundle

Step 7: Force-add and Report

git add -f plugins/microsoft/vendor/MssqlMcp/dotnet-publish/
git add -f plugins/microsoft/vendor/MssqlMcp/Node/bundle/
git add -f plugins/microsoft/vendor/MssqlMcp/Node/dist/
git status --short plugins/microsoft/vendor/MssqlMcp/

Examples

# Check status (default)
/microsoft:mssql

# Check status of Node.js server only
/microsoft:mssql status --node

# Rebuild both servers
/microsoft:mssql rebuild

# Rebuild only .NET server
/microsoft:mssql rebuild --dotnet

# Check for upstream updates (dry run)
/microsoft:mssql update --check

# Pull upstream and rebuild
/microsoft:mssql update

Troubleshooting

Node.js build fails:

Common issues:
  1. Old Node.js version - upgrade to 18+
  2. Corrupted node_modules - delete and retry
  3. npm cache issues - npm cache clean --force
  4. zod/TypeScript incompatibility - pin @modelcontextprotocol/sdk to 1.x

.NET build fails:

Common issues:
  1. Wrong SDK version - install .NET 8
  2. Missing workloads - dotnet workload restore
  3. NuGet cache issues - dotnet nuget locals all --clear

Upstream Source

Repository: https://github.com/Azure-Samples/SQL-AI-samples
Path: MssqlMcp/
License: MIT

Related Commands

/microsoft:setup-dab - Install and configure Data API Builder