mcp-sql

Model Context Protocol을 통해 SQL Server에 연결하기 위한 CLI 도구 / MCP 서버입니다.

Isasoft SAS의 자산입니다.

종속성 설치

bun install

개발

Bun으로 직접 실행(개발 모드):

bun run src/cli.ts --help

독립 실행 파일 빌드

대상 머신에 Bun/Node 런타임이 필요 없는 단일 네이티브 실행 파일로 컴파일합니다:

bun run build:win        # dist/mcp-sql-win-x64.exe (Windows x64)

크로스 컴파일 스크립트도 사용할 수 있습니다(이 빌드의 일부로 실행/검증되지는 않았으며, build:linux는 Windows에서 성공적으로 크로스 컴파일되었습니다. build:mac-x64 / build:mac-arm64는 실제 macOS 하드웨어에서 검증되지 않았습니다):

bun run build:mac-x64    # dist/mcp-sql-macos-x64 (macOS Intel, cross-compiled, unverified)
bun run build:mac-arm64  # dist/mcp-sql-macos-arm64 (macOS Apple Silicon, cross-compiled, unverified)
bun run build:linux      # dist/mcp-sql-linux-x64 (Linux x64, cross-compiled)

출력 바이너리는 dist/에 기록됩니다.

사용법

빌드 후(또는 개발 모드에서 bun run src/cli.ts를 통해) CLI는 다음 하위 명령을 제공합니다:

mcp-sql setup [name]  Interactively configure a SQL Server connection
                       (defaults to the name "default")
mcp-sql list           List configured connections and mark the active one
mcp-sql use <name>     Switch which configured connection is active
mcp-sql remove <name>  Remove a configured connection (and its credential)
mcp-sql run            Run mcp-sql in server mode (starts the MCP server)
mcp-sql discover        Detect installed AI clients (Claude Desktop, Cline, Roo
                        Code) and configure them to use mcp-sql

다중 연결

mcp-sql은 한 번에 둘 이상의 명명된 SQL Server 연결을 저장할 수 있지만, 주어진 시점에 활성 상태인 연결은 하나뿐입니다 — mcp-sql run(따라서 연결된 모든 AI 클라이언트)이 사용하는 연결이 바로 그것입니다. 명시적 이름을 전달하지 않으면 모든 것이 이전과 동일하게 "default"라는 이름으로 동작합니다.

setup

mcp-sql setup          # configure (or reconfigure) the "default" connection
mcp-sql setup staging  # configure a connection named "staging"

대화형 마법사를 통해 주어진 이름(생략 시 default)으로 SQL Server 연결 세부 정보/자격 증명을 구성하고 저장합니다. 마지막에 이 연결을 활성 연결로 설정할지 묻습니다(처음 구성하는 연결인 경우 기본값은 "yes").

list

mcp-sql list

구성된 모든 연결의 이름을 호스트 및 데이터베이스(비밀번호는 절대 아님)와 함께 나열하고 어떤 것이 활성 상태인지 표시합니다. 아직 구성된 것이 없으면 깔끔한 메시지를 출력합니다(충돌 없음).

use

mcp-sql use staging

주어진 연결을 활성으로 표시합니다. 이름이 존재하지 않으면 알려진 연결 이름 목록과 함께 명확한 오류를 출력합니다.

remove

mcp-sql remove staging

구성된 연결을 저장된 자격 증명과 함께 제거합니다. 현재 활성 연결은 제거를 거부합니다 — 먼저 mcp-sql use <other-name>으로 다른 연결로 전환하세요.

discover

mcp-sql discover           # detect clients and write/merge their MCP config
mcp-sql discover --dry-run # preview what would be written, without touching any files

설치된 AI 클라이언트(Claude Desktop, Cline, Roo Code)를 감지하고 각 클라이언트의 MCP 구성 파일에 mcp-sql 항목을 주입하여 이 실행 파일의 자체 경로(command)를 args: ["run"]으로 가리킵니다. 기존 구성 내용과 다른 MCP 서버 항목은 보존됩니다. 실제(드라이런이 아닌) 주입 시마다 이전 파일의 .bak 백업이 기록됩니다.

run

mcp-sql run

MCP 서버 모드로 mcp-sql을 시작합니다. AI 클라이언트가 호출하는 것이 바로 이것입니다 — 일반적으로 수동으로 실행하지 않습니다. discover가 자동으로 연결해 줍니다.

영구 설치 위치

discover는 현재 실행 중인 실행 파일의 절대 경로(process.execPath)를 각 클라이언트의 구성에 주입합니다. 즉, discover를 실행한 후에는 컴파일된 .exe가 제자리에 있어야 합니다 — 이후에 이동하거나 이름을 바꾸면 클라이언트 구성이 더 이상 존재하지 않는 파일을 가리키게 됩니다.

권장 사항: 컴파일된 실행 파일을 다음 위치에 두세요

C:\Users\Wil\appisoft\mcp\dist\mcp-sql-win-x64.exe

이 안정적인 프로젝트 디렉터리 안에서 bun run build:win이 생성하는 위치입니다.

discover 실행 후에는 이 파일을 이동하지 마세요. 이동해야 한다면, 이후 실행 파일의 새 위치에서 discover를 다시 실행하여(예: path\to\new\location\mcp-sql-win-x64.exe discover) 클라이언트 구성을 일치하도록 업데이트하세요.

설치 / 배포

릴리스는 azure-pipelines.yml에 정의된 Azure Pipelines 파이프라인에 의해 자동으로 빌드됩니다:

1. v*와 일치하는 태그를 푸시합니다(예: v1.0.0). 파이프라인은 태그 푸시 시 트리거되고(또는 수동으로 실행 가능), Bun을 설치하고, bun test와 bunx tsc --noEmit을 하드 게이트로 실행한 다음, 단일 windows-latest 에이전트에서 4개의 bun run build:* 스크립트를 모두 실행합니다(Bun이 Windows에서 mac/linux 대상을 크로스 컴파일합니다. 현재까지 build:win과 build:linux만 실행 검증되었습니다 — mac 빌드는 실제 하드웨어에서 best-effort/미검증 상태입니다, 위 참고 사항 참조).

2. 4개 바이너리 모두에 대한 SHA256 체크섬이 dist/checksums.sha256에 생성됩니다.

3. 모든 것(4개 바이너리, 설치 스크립트, 체크섬 파일)이 mcp-sql-release라는 Azure DevOps 파이프라인 아티팩트로 게시됩니다. 파이프라인 실행의 "Artifacts" 탭에서 다운로드하세요. (파이프라인의 주석 처리된 GitHubRelease@1 블록은 GitHub 서비스 연결이 구성되면 GitHub Release에도 게시하는 방법을 보여줍니다.)

최종 사용자는 다운로드한 mcp-sql-release 폴더 안에서 단일 스크립트로 설치합니다:

# Windows
.\install.ps1

# macOS / Linux
./install.sh

두 스크립트 모두 바이너리를 설치하고, 선택적으로 mcp-sql setup(대화형 자격 증명 마법사)과 mcp-sql discover(Claude Desktop, Cline, Roo Code 구성)를 실행하며, 다른 애플리케이션의 구성 파일을 건드리기 전에 수행할 작업을 명확히 출력합니다. 자동 단계를 건너뛰려면 -SkipSetup/-SkipDiscover(PowerShell) 또는 --skip-setup/--skip-discover(bash)를 전달하세요.

이 저장소의 /docs 폴더는 Azure DevOps에서 프로젝트 Wiki로 게시할 준비가 되어 있습니다(Project Settings -> Wikis -> Publish code as wiki -> 이 저장소 -> /docs). "one-liner" 스타일 설치 가이드(Azure Artifacts 비공개 피드용으로 조정됨)가 포함되어 있습니다 — docs/Installation.md 참조.

대안으로(또는 추가로), 이 저장소가 GitHub에 있게 되면 동일한 /docs 폴더를 GitHub Pages로 게시할 수 있습니다: Settings -> Pages -> Source: "GitHub Actions"를 활성화하고(한 번만), .github/workflows/pages.yml 워크플로가 docs/**를 건드리는 main에 대한 각 푸시에서 docs/를 자동으로 빌드하고 배포합니다(Jekyll 경유).

저작자 표시

"Propiedad de Isasoft SAS"는 mcp-sql --help 출력의 일부로 표시됩니다.