# mcp-sql

CLI tool / MCP server for connecting to SQL Server via the Model Context Protocol.

Propiedad de Isasoft SAS.

## Install dependencies

```bash
bun install
```

## Development

Run directly with Bun (dev mode):

```bash
bun run src/cli.ts --help
```

## Building a standalone executable

Compile to a single native executable with no Bun/Node runtime required on the
target machine:

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

Cross-compile scripts are also available (not run/verified as part of this
build, except `build:linux` which was successfully cross-compiled on Windows;
`build:mac-x64` / `build:mac-arm64` have not been verified on real macOS
hardware):

```bash
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)
```

Output binaries are written to `dist/`.

## Usage

Once built (or via `bun run src/cli.ts` in dev mode), the CLI exposes these
subcommands:

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

### Multiple connections

`mcp-sql` can store more than one named SQL Server connection at a time, but
only one is **active** at any given moment — that's the one `mcp-sql run`
(and therefore any connected AI client) uses. If you never pass an explicit
name, everything behaves exactly as before under the name `"default"`.

### `setup`

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

Walks you through an interactive wizard to configure and store the SQL
Server connection details/credentials under the given name (`default` if
omitted). At the end it asks whether this connection should become the
active one (defaults to "yes" if it's the first connection you've ever
configured).

### `list`

```bash
mcp-sql list
```

Lists the names of all configured connections along with their host and
database (never the password), marking which one is active. Prints a clean
message (no crash) if none are configured yet.

### `use`

```bash
mcp-sql use staging
```

Marks the given connection as active. If the name doesn't exist, prints a
clear error along with the list of known connection names.

### `remove`

```bash
mcp-sql remove staging
```

Removes a configured connection along with its stored credential. Refuses to
remove the currently active connection — switch to another one first with
`mcp-sql use <other-name>`.

### `discover`

```bash
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
```

Detects installed AI clients (Claude Desktop, Cline, Roo Code) and injects an
`mcp-sql` entry into each client's MCP config file, pointing at this
executable's own path (`command`) with `args: ["run"]`. Existing config
content and other MCP server entries are preserved; a `.bak` backup of the
previous file is written on every real (non-dry-run) injection.

### `run`

```bash
mcp-sql run
```

Starts mcp-sql in MCP server mode. This is what AI clients invoke — you
normally don't run this manually; `discover` wires it up for you.

## Permanent install location

`discover` injects the **absolute path of the currently running executable**
(`process.execPath`) into each client's config. That means the compiled
`.exe` must stay put once you've run `discover` against it — if you move or
rename it afterward, the client configs will point at a file that no longer
exists there.

Recommended: leave the compiled executable at

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

which is where `bun run build:win` produces it, inside this stable project
directory.

**Do not move this file after running `discover`.** If you do need to move
it, re-run `discover` from the executable's *new* location afterward
(e.g. `path\to\new\location\mcp-sql-win-x64.exe discover`) to update the
client configs to match.

## Instalación / Distribución

Releases are built automatically by the Azure Pipelines pipeline defined in
[`azure-pipelines.yml`](./azure-pipelines.yml):

1. Push a tag matching `v*` (e.g. `v1.0.0`). The pipeline triggers on tag
   push (or can be run manually), installs Bun, runs `bun test` and
   `bunx tsc --noEmit` as hard gates, then runs all 4 `bun run build:*`
   scripts on a single `windows-latest` agent (Bun cross-compiles the
   mac/linux targets from Windows; only `build:win` and `build:linux` have
   been run-verified so far — the mac builds are best-effort/unverified on
   real hardware, see the note above).
2. SHA256 checksums for all 4 binaries are generated into
   `dist/checksums.sha256`.
3. Everything (the 4 binaries, the install scripts, and the checksums file)
   is published as an Azure DevOps pipeline artifact named
   `mcp-sql-release`. Download it from the pipeline run's "Artifacts" tab.
   (A commented-out `GitHubRelease@1` block in the pipeline shows how to
   also publish to a GitHub Release once a GitHub service connection is
   configured.)

End users then install with a single script from inside the downloaded
`mcp-sql-release` folder:

```powershell
# Windows
.\install.ps1
```

```bash
# macOS / Linux
./install.sh
```

Both scripts install the binary, optionally run `mcp-sql setup` (interactive
credential wizard) and `mcp-sql discover` (configures Claude Desktop, Cline,
Roo Code), and print clearly what they're about to do before touching any
other application's config files. Pass `-SkipSetup`/`-SkipDiscover`
(PowerShell) or `--skip-setup`/`--skip-discover` (bash) to opt out of the
automatic steps.

La carpeta [`/docs`](./docs) de este repo está lista para publicarse como la
Wiki del proyecto en Azure DevOps (Project Settings -> Wikis -> Publish code
as wiki -> este repo -> `/docs`). Incluye una guía de instalación estilo
"one-liner" (adaptada para el feed privado de Azure Artifacts) — ver
[`docs/Installation.md`](./docs/Installation.md).

Alternativamente (o además), una vez que este repo viva en GitHub, la misma
carpeta `/docs` se puede publicar con **GitHub Pages**: habilita
Settings -> Pages -> Source: "GitHub Actions" (una sola vez), y el workflow
[`.github/workflows/pages.yml`](./.github/workflows/pages.yml) construye y
despliega `docs/` automáticamente (vía Jekyll) en cada push a `main` que
toque `docs/**`.

## Attribution

"Propiedad de Isasoft SAS" is printed as part of `mcp-sql --help` output.