@tikoci/rosetta 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server for searching [MikroTik RouterOS documentation](https://help.mikrotik.com/docs/spaces/ROS/overview). Gives your AI assistant searchable access to 317 documentation pages, 4,860 property definitions, 40,000-entry command tree, and 144 hardware product specs — with direct links to help.mikrotik.com.
 
-Tested with **Claude Desktop**, **Claude Code**, **VS Code Copilot** (including Copilot CLI), and **VS Code** on macOS and Linux.
+Tested with **Claude Desktop**, **Claude Code**, **VS Code Copilot** (including Copilot CLI), **Cursor**, and **OpenAI Codex** on macOS, Linux, and Windows.
 
 ## What is SQL-as-RAG?
 
@@ -10,7 +10,7 @@ Most retrieval-augmented generation (RAG) systems use vector embeddings to searc
 
 For structured technical documentation like RouterOS, full-text search with [BM25 ranking](https://www.sqlite.org/fts5.html#the_bm25_function) beats vector similarity. Technical terms like "dhcp-snooping" or "/ip/firewall/filter" are exact tokens — [porter stemming](https://www.sqlite.org/fts5.html#porter_tokenizer) and proximity matching handle the rest. No embedding pipeline, no vector database, no API keys. Just a single SQLite file that searches in milliseconds.
 
-The data flows: **HTML docs → SQLite extraction → FTS5 indexes → MCP tools → your AI assistant.** The database is built once from MikroTik's official Confluence documentation export, then the MCP server exposes 10 search tools over stdio transport.
+The data flows: **HTML docs → SQLite extraction → FTS5 indexes → MCP tools → your AI assistant.** The database is built once from MikroTik's official Confluence documentation export, then the MCP server exposes 11 search tools over stdio or HTTP transport.
 
 ## What's Inside
 
@@ -24,45 +24,75 @@ The data flows: **HTML docs → SQLite extraction → FTS5 indexes → MCP tools
 
 ## Quick Start
 
-Download a pre-built binary from [Releases](https://github.com/tikoci/rosetta/releases) — no Bun, Node.js, or other tools required.
+## MCP Discovery Status
 
-### 1. Download
+- GitHub MCP Registry listing: planned
+- Official MCP Registry publication: metadata is now prepared in `server.json`
 
-Go to the [latest release](https://github.com/tikoci/rosetta/releases/latest) and download the ZIP for your platform:
+Local install remains the primary path today (`bunx @tikoci/rosetta`).
 
-| Platform | File |
-|----------|------|
-| macOS (Apple Silicon) | `rosetta-macos-arm64.zip` |
-| macOS (Intel) | `rosetta-macos-x64.zip` |
-| Windows | `rosetta-windows-x64.zip` |
-| Linux | `rosetta-linux-x64.zip` |
+When ready to publish to the official registry:
 
-Extract the ZIP to a permanent location (e.g., `~/rosetta` or `C:\rosetta`).
+```sh
+brew install mcp-publisher
+mcp-publisher validate server.json
+mcp-publisher login github
+mcp-publisher publish server.json
+```
+
+After publication, the server should be discoverable via:
+
+```sh
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.tikoci/rosetta"
+```
+
+### Option A: Install with Bun (recommended)
 
-### 2. Run Setup
+Zero install, zero config, no binary signing issues. Requires [Bun](https://bun.sh/) — no Gatekeeper or SmartScreen warnings since there's no compiled binary to sign.
 
-Open a terminal in the extracted folder and run:
+**1. Install Bun** (if you don't have it):
 
 ```sh
-./rosetta --setup
+# macOS / Linux
+curl -fsSL https://bun.sh/install | bash
+
+# Windows
+powershell -c "irm bun.sh/install.ps1 | iex"
 ```
 
-On Windows:
-```powershell
-.\rosetta.exe --setup
+**2. Configure your MCP client** with `bunx @tikoci/rosetta` as the command. No setup step needed — the database downloads automatically on first launch (~50 MB compressed).
+
+<details>
+<summary><b>VS Code Copilot</b></summary>
+
+Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), choose **"MCP: Add Server…"**, select **"Command (stdio)"**, enter `bunx` as the command, and `@tikoci/rosetta` as the argument.
+
+Or add to User Settings JSON (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"):
+
+```json
+"mcp": {
+  "servers": {
+    "rosetta": {
+      "command": "bunx",
+      "args": ["@tikoci/rosetta"]
+    }
+  }
+}
 ```
 
-This downloads the documentation database (~50 MB compressed, ~230 MB on disk) and prints configuration instructions for your MCP client.
+</details>
 
-> **macOS Gatekeeper:** If macOS blocks the binary, go to **System Settings → Privacy & Security** and click **Allow Anyway**, then run again. Or from Terminal: `xattr -d com.apple.quarantine ./rosetta`
->
-> **Windows SmartScreen:** If Windows warns about an unrecognized app, click **More info → Run anyway**.
+<details>
+<summary><b>Claude Code</b></summary>
 
-### 3. Configure Your MCP Client
+```sh
+claude mcp add rosetta -- bunx @tikoci/rosetta
+```
 
-The `--setup` command prints the exact config for your platform. Here's what it looks like for each client:
+</details>
 
-#### Claude Desktop
+<details>
+<summary><b>Claude Desktop</b></summary>
 
 Edit your Claude Desktop config file:
 - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -74,37 +104,97 @@ Add (or merge into existing config):
 {
   "mcpServers": {
     "rosetta": {
-      "command": "/path/to/rosetta"
+      "command": "bunx",
+      "args": ["@tikoci/rosetta"]
     }
   }
 }
 ```
 
-Replace `/path/to/rosetta` with the actual path printed by `--setup`. Then **restart Claude Desktop**.
+> **PATH note:** Claude Desktop on macOS doesn't always inherit your shell PATH. If `bunx` isn't found, use the full path — typically `~/.bun/bin/bunx`. Run `which bunx` to find it, or use `bunx @tikoci/rosetta --setup` which prints the full-path config for you.
 
-#### Claude Code
+Then **restart Claude Desktop**.
 
-```sh
-claude mcp add rosetta /path/to/rosetta
-```
+</details>
+
+<details>
+<summary><b>GitHub Copilot CLI</b></summary>
+
+Inside a `copilot` session, type `/mcp add` to open the interactive form:
+
+- **Server Name:** `routeros-rosetta`
+- **Server Type:** 2 (STDIO)
+- **Command:** `bunx @tikoci/rosetta`
 
-#### VS Code Copilot
+Press <kbd>Tab</kbd> to navigate fields, <kbd>Ctrl+S</kbd> to save.
 
-The simplest way: open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), choose **"MCP: Add Server…"**, select **"Command (stdio)"**, and enter the full path to the `rosetta` binary.
+</details>
 
-Or add to your User Settings JSON (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"):
+<details>
+<summary><b>Cursor</b></summary>
+
+Open **Settings → MCP** and add a new server:
 
 ```json
-"mcp": {
-  "servers": {
+{
+  "mcpServers": {
     "rosetta": {
-      "command": "/path/to/rosetta"
+      "command": "bunx",
+      "args": ["@tikoci/rosetta"]
     }
   }
 }
 ```
 
-### 4. Try It
+</details>
+
+<details>
+<summary><b>OpenAI Codex</b></summary>
+
+```sh
+codex mcp add rosetta -- bunx @tikoci/rosetta
+```
+
+> **Note:** ChatGPT Apps require a remote HTTPS MCP endpoint and cannot use local stdio servers like this one. Codex (CLI and desktop app) supports stdio and works with `bunx`.
+
+</details>
+
+**That's it.** First launch takes a moment to download the database; subsequent starts are instant. The database is stored in `~/.rosetta/ros-help.db`.
+
+> **Verify it works:** Run `bunx @tikoci/rosetta --setup` to see the database status and print config for all MCP clients.
+>
+> **Auto-update:** `bunx` checks the npm registry each session and uses the latest published version automatically. No manual update needed. (Note: the `~/.rosetta/ros-help.db` database persists across updates — it's re-downloaded only when missing or when you run `--setup --force`.)
+
+### Option B: Pre-built binary (no runtime needed)
+
+Download a compiled binary from [Releases](https://github.com/tikoci/rosetta/releases) — no Bun, Node.js, or other tools required.
+
+**1. Download** the ZIP for your platform from the [latest release](https://github.com/tikoci/rosetta/releases/latest):
+
+| Platform | File |
+|----------|------|
+| macOS (Apple Silicon) | `rosetta-macos-arm64.zip` |
+| macOS (Intel) | `rosetta-macos-x64.zip` |
+| Windows | `rosetta-windows-x64.zip` |
+| Linux | `rosetta-linux-x64.zip` |
+
+Extract the ZIP to a permanent location (e.g., `~/rosetta` or `C:\rosetta`).
+
+**2. Run setup** to download the database and see MCP client config:
+
+```sh
+./rosetta --setup
+```
+
+On Windows: `.\rosetta.exe --setup`
+
+> **macOS Gatekeeper:** If macOS blocks the binary: `xattr -d com.apple.quarantine ./rosetta` or go to **System Settings → Privacy & Security → Allow Anyway**.
+>
+> **Windows SmartScreen:** Click **More info → Run anyway**.
+
+**3. Configure your MCP client** using the config printed by `--setup`. It uses the full path to the binary — paste it into your MCP client's config as shown.
+
+### Try It
 
 Ask your AI assistant questions like:
 
@@ -117,7 +207,7 @@ Ask your AI assistant questions like:
 
 ## MCP Tools
 
-The server provides 10 tools, designed to work together:
+The server provides 11 tools, designed to work together:
 
 | Tool | What it does |
 |------|-------------|
@@ -127,6 +217,7 @@ The server provides 10 tools, designed to work together:
 | `routeros_search_properties` | Search across 4,860 property names and descriptions |
 | `routeros_command_tree` | Browse the `/ip/firewall/filter` style command hierarchy |
 | `routeros_search_callouts` | Search warnings, notes, and tips across all pages |
+| `routeros_search_changelogs` | Search parsed changelog entries — filter by version range, category, breaking changes |
 | `routeros_command_version_check` | Check which RouterOS versions include a command |
 | `routeros_device_lookup` | Hardware specs for 144 MikroTik products — filter by architecture, RAM, storage, PoE, wireless, LTE |
 | `routeros_stats` | Database health: page/property/command counts, coverage stats |
@@ -134,78 +225,79 @@ The server provides 10 tools, designed to work together:
 
 The AI assistant typically starts with `routeros_search`, then drills into specific pages, properties, or the command tree based on what it finds. Each tool's description includes workflow hints (e.g., "→ use `routeros_get_page` to read full content") and empty-result suggestions so the AI knows how to chain tools together — this is where most of the tuning effort goes.
 
-## Alternative: Run with Bun
+## Troubleshooting
 
-If you have [Bun](https://bun.sh/) installed and prefer not to use the pre-built binary — for example, to avoid Gatekeeper/SmartScreen warnings, or to inspect the code you're running — you can run the MCP server directly from source. No HTML export or command tree data is needed; the database is downloaded from GitHub Releases just like the binary option.
+| Issue | Solution |
+|-------|----------|
+| **First launch is slow** | One-time database download (~50 MB). Subsequent starts are instant. |
+| **`npx @tikoci/rosetta` fails** | This package requires Bun, not Node.js. Use `bunx` instead of `npx`. |
+| **`npm install -g` then `rosetta` fails** | Global npm install works if Bun is on PATH — it delegates to `bun` at runtime. But prefer `bunx` — it's simpler and auto-updates. |
+| **ChatGPT Apps can't connect with `bunx @tikoci/rosetta`** | Expected: ChatGPT Apps supports remote HTTPS MCP endpoints, not local stdio command launch. Use OpenAI Codex for local stdio, or deploy/tunnel a remote MCP URL for ChatGPT. |
+| **Claude Desktop can't find `bunx`** | Claude Desktop on macOS may not inherit shell PATH. Use the full path to bunx (run `which bunx` to find it, typically `~/.bun/bin/bunx`). `bunx @tikoci/rosetta --setup` prints the full-path config. |
+| **macOS Gatekeeper blocks binary** | Use `bunx` install (no Gatekeeper issues), or: `xattr -d com.apple.quarantine ./rosetta` |
+| **Windows SmartScreen warning** | Use `bunx` install (no SmartScreen issues), or click **More info → Run anyway** |
+| **How to update** | `bunx` always uses the latest published version. For binaries, re-download from [Releases](https://github.com/tikoci/rosetta/releases/latest). |
 
-### 1. Install Bun
+## HTTP Transport
 
-```sh
-# macOS / Linux
-curl -fsSL https://bun.sh/install | bash
-# or: brew install oven-sh/bun/bun
+Most MCP clients use stdio (the default). Some — like the OpenAI platform and remote/LAN setups — require an HTTP endpoint instead. Rosetta supports the [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) via the `--http` flag:
 
-# Windows
-powershell -c "irm bun.sh/install.ps1 | iex"
+```sh
+rosetta --http                    # http://localhost:8080/mcp
+rosetta --http --port 9090        # custom port
+rosetta --http --host 0.0.0.0    # accessible from LAN
 ```
 
-### 2. Download and Install
+Then point your MCP client at the URL:
 
-```sh
-git clone https://github.com/tikoci/rosetta.git
-cd rosetta
-bun install
+```json
+{ "url": "http://localhost:8080/mcp" }
 ```
 
-Or download the source archive from the [latest release](https://github.com/tikoci/rosetta/releases/latest) ("Source code" ZIP or tarball), extract it, and run `bun install`.
+**Key facts:**
 
-### 3. Run Setup
+- **Read-only** — the server queries a local SQLite database. It does not store data, accept uploads, or modify anything.
+- **No authentication** — designed for local/trusted-network use. For public exposure, put it behind a reverse proxy (nginx, caddy) with TLS and auth.
+- **TLS built-in** — for direct HTTPS without a proxy: `--tls-cert cert.pem --tls-key key.pem` (or `TLS_CERT_PATH` + `TLS_KEY_PATH` env vars)
+- **Defaults to localhost** — binding to all interfaces (`--host 0.0.0.0`) requires an explicit flag and logs a warning.
+- **Origin validation** — rejects cross-origin requests to prevent DNS rebinding attacks.
+- **Stdio remains default** — `--http` is opt-in. Existing stdio configs are unaffected.
 
-```sh
-bun run src/mcp.ts --setup
-```
+The `PORT`, `HOST`, `TLS_CERT_PATH`, and `TLS_KEY_PATH` environment variables are supported (lower precedence than CLI flags).
 
-This downloads the documentation database and prints MCP client configuration. The config uses `bun` as the command with `src/mcp.ts` as the entrypoint:
+## Container Images
 
-#### Claude Desktop
+Release CI publishes multi-arch OCI images to:
 
-```json
-{
-  "mcpServers": {
-    "rosetta": {
-      "command": "bun",
-      "args": ["run", "src/mcp.ts"],
-      "cwd": "/path/to/rosetta"
-    }
-  }
-}
-```
+- Docker Hub: `ammo74/rosetta`
+- GHCR: `ghcr.io/tikoci/rosetta`
 
-#### Claude Code
+Tags per release:
 
-```sh
-claude mcp add rosetta -- bun run src/mcp.ts --cwd /path/to/rosetta
-```
+- `${version}` (example: `v0.2.1`)
+- `latest`
+- `sha-<12-char-commit>`
 
-#### VS Code Copilot
+Container defaults:
 
-Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), choose **"MCP: Add Server…"**, select **"Command (stdio)"**, and enter `bun run src/mcp.ts` with the working directory set to the rosetta folder.
+- Starts in HTTP mode (`--http`) on `0.0.0.0`
+- Uses `PORT` if set, otherwise 8080
+- Uses HTTPS only when both `TLS_CERT_PATH` and `TLS_KEY_PATH` are set
 
-Or add to your User Settings JSON:
+Examples:
 
-```json
-"mcp": {
-  "servers": {
-    "rosetta": {
-      "command": "bun",
-      "args": ["run", "src/mcp.ts"],
-      "cwd": "/path/to/rosetta"
-    }
-  }
-}
+```sh
+docker run --rm -p 8080:8080 ghcr.io/tikoci/rosetta:latest
 ```
 
-Replace `/path/to/rosetta` with the actual path (printed by `--setup`).
+```sh
+docker run --rm -p 8443:8443 \
+  -e PORT=8443 \
+  -e TLS_CERT_PATH=/certs/cert.pem \
+  -e TLS_KEY_PATH=/certs/key.pem \
+  -v "$PWD/certs:/certs:ro" \
+  ghcr.io/tikoci/rosetta:latest
+```
 
 ## Building from Source
 
@@ -267,11 +359,13 @@ make release VERSION=v0.1.0
 
 This cross-compiles to macOS (arm64 + x64), Windows (x64), and Linux (x64), creates ZIP archives, compresses the database, tags the commit, and creates a GitHub Release with all artifacts.
 
+The release workflow also publishes OCI images to Docker Hub (`ammo74/rosetta`) and GHCR (`ghcr.io/tikoci/rosetta`) using crane (no Docker daemon required in CI).
+
 ## Project Structure
 
 ```text
 src/
-├── mcp.ts                  # MCP server (10 tools, stdio) + CLI dispatch
+├── mcp.ts                  # MCP server (11 tools, stdio + HTTP) + CLI dispatch
 ├── setup.ts                # --setup: DB download + MCP client config
 ├── query.ts                # NL → FTS5 query planner, BM25 ranking
 ├── db.ts                   # SQLite schema, WAL mode, FTS5 triggers
@@ -285,6 +379,7 @@ src/
 
 scripts/
 └── build-release.ts        # Cross-compile + package releases
+└── container-entrypoint.sh # OCI image runtime entrypoint (HTTP default)
 ```
 
 ## Data Sources

package/bin/rosetta.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 /**
- * bin/rosetta.js — Entry point for `npx @tikoci/rosetta` and `bunx @tikoci/rosetta`.
+ * bin/rosetta.js — Entry point for `bunx @tikoci/rosetta` (and npx fallback).
  *
  * The server uses bun:sqlite and other Bun APIs, so it requires the Bun runtime.
  * When run under Bun (via bunx), this imports src/mcp.ts directly.
- * When run under Node (via npx), this spawns `bun run src/mcp.ts` as a subprocess.
+ * When run under Node (via npx), this spawns `bun` as a subprocess if available.
  */
 
 import { dirname, join } from "node:path";
@@ -17,17 +17,23 @@ if (typeof Bun !== "undefined") {
   // Running under Bun — import TypeScript entry directly
   await import(entry);
 } else {
-  // Running under Node — delegate to Bun subprocess
+  // Running under Node — try to delegate to Bun, but warn the user
+  console.error("Note: rosetta requires the Bun runtime. Attempting to run via bun...");
+  console.error();
   const { spawn } = await import("node:child_process");
   const proc = spawn("bun", ["run", entry, ...process.argv.slice(2)], {
     stdio: "inherit",
   });
   proc.on("error", (err) => {
     if (err.code === "ENOENT") {
-      console.error("rosetta requires the Bun runtime (bun:sqlite is not available in Node.js).");
+      console.error("rosetta requires Bun (bun:sqlite is not available in Node.js).\n");
+      console.error("Recommended: install Bun, then use bunx instead of npx:\n");
+      console.error("  curl -fsSL https://bun.sh/install | bash");
+      console.error("  bunx @tikoci/rosetta --setup\n");
       console.error("Install Bun: https://bun.sh");
       process.exit(1);
     }
+    console.error(`Failed to start bun: ${err.message}`);
     process.exit(1);
   });
   proc.on("exit", (code) => process.exit(code ?? 1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/rosetta",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "RouterOS documentation as SQLite FTS5 — RAG search + command glossary via MCP",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,9 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^4.3.6"
   },
+  "engines": {
+    "bun": ">=1.1"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.4.7",
     "@types/bun": "^1.3.10",

package/src/db.ts

@@ -20,22 +20,9 @@
  */
 
 import sqlite from "bun:sqlite";
-import path from "node:path";
+import { resolveDbPath } from "./paths.ts";
 
-declare const IS_COMPILED: boolean;
-
-/**
- * Resolve the base directory for finding ros-help.db:
- * - Compiled binary: directory containing the executable
- * - Dev mode: project root (one level up from src/)
- */
-const baseDir =
-  typeof IS_COMPILED !== "undefined" && IS_COMPILED
-    ? path.dirname(process.execPath)
-    : path.resolve(import.meta.dirname, "..");
-
-export const DB_PATH =
-  process.env.DB_PATH?.trim() || path.join(baseDir, "ros-help.db");
+export const DB_PATH = resolveDbPath(import.meta.dirname);
 
 export const db = new sqlite(DB_PATH);
 

package/src/mcp.ts

@@ -9,38 +9,63 @@
  *   --setup [--force]  Download database + print MCP client config
  *   --version          Print version
  *   --help             Print usage
+ *   --http             Start with Streamable HTTP transport (instead of stdio)
+ *   --port <N>         HTTP listen port (default: 8080, env: PORT)
+ *   --host <ADDR>      HTTP bind address (default: localhost, env: HOST)
+ *   --tls-cert <PATH>  TLS certificate PEM file (enables HTTPS, env: TLS_CERT_PATH)
+ *   --tls-key <PATH>   TLS private key PEM file (requires --tls-cert, env: TLS_KEY_PATH)
  *   (default)          Start MCP server (stdio transport)
  *
  * Environment variables:
  *   DB_PATH — absolute path to ros-help.db (default: next to binary or project root)
+ *   PORT    — HTTP listen port (lower precedence than --port)
+ *   HOST    — HTTP bind address (lower precedence than --host)
+ *   TLS_CERT_PATH — TLS certificate path (lower precedence than --tls-cert)
+ *   TLS_KEY_PATH  — TLS private key path (lower precedence than --tls-key)
  */
 
-declare const VERSION: string;
-declare const IS_COMPILED: boolean;
+import { resolveVersion } from "./paths.ts";
+
+const RESOLVED_VERSION = resolveVersion(import.meta.dirname);
 
 // ── CLI dispatch (before MCP server init) ──
 
 const args = process.argv.slice(2);
 
+/** Extract the value following a named flag (e.g. --port 8080 → "8080") */
+function getArg(name: string): string | undefined {
+  const idx = args.indexOf(name);
+  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+
 if (args.includes("--version") || args.includes("-v")) {
-  const ver = typeof VERSION !== "undefined" ? VERSION : "dev";
-  console.log(`rosetta ${ver}`);
+  console.log(`rosetta ${RESOLVED_VERSION}`);
   process.exit(0);
 }
 
 if (args.includes("--help") || args.includes("-h")) {
-  const ver = typeof VERSION !== "undefined" ? VERSION : "dev";
-  console.log(`rosetta ${ver} — MCP server for RouterOS documentation`);
+  console.log(`rosetta ${RESOLVED_VERSION} — MCP server for RouterOS documentation`);
   console.log();
   console.log("Usage:");
   console.log("  rosetta              Start MCP server (stdio transport)");
+  console.log("  rosetta --http       Start with Streamable HTTP transport");
   console.log("  rosetta --setup      Download database + print MCP client config");
   console.log("  rosetta --setup --force  Re-download database");
   console.log("  rosetta --version    Print version");
   console.log("  rosetta --help       Print this help");
   console.log();
+  console.log("HTTP options (require --http):");
+  console.log("  --port <N>           Listen port (default: 8080, env: PORT)");
+  console.log("  --host <ADDR>        Bind address (default: localhost, env: HOST)");
+  console.log("  --tls-cert <PATH>    TLS certificate PEM file (env: TLS_CERT_PATH)");
+  console.log("  --tls-key <PATH>     TLS private key PEM file (env: TLS_KEY_PATH)");
+  console.log();
   console.log("Environment:");
   console.log("  DB_PATH  Absolute path to ros-help.db (optional)");
+  console.log("  PORT     HTTP listen port (lower precedence than --port)");
+  console.log("  HOST     HTTP bind address (lower precedence than --host)");
+  console.log("  TLS_CERT_PATH  TLS certificate path (lower precedence than --tls-cert)");
+  console.log("  TLS_KEY_PATH   TLS private key path (lower precedence than --tls-key)");
   process.exit(0);
 }
 
@@ -55,8 +80,9 @@ if (args.includes("--setup")) {
 
 // ── MCP Server ──
 
+const useHttp = args.includes("--http");
+
 const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
-const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
 const { z } = await import("zod/v3");
 
 // Dynamic imports — db.ts eagerly opens the DB file on import,
@@ -65,12 +91,8 @@ const { z } = await import("zod/v3");
 //
 // Check if DB has data BEFORE importing db.ts. If empty/missing,
 // auto-download so db.ts opens the real database.
-const _baseDir =
-  typeof IS_COMPILED !== "undefined" && IS_COMPILED
-    ? (await import("node:path")).dirname(process.execPath)
-    : (await import("node:path")).resolve(import.meta.dirname, "..");
-const _dbPath =
-  process.env.DB_PATH?.trim() || (await import("node:path")).join(_baseDir, "ros-help.db");
+const { resolveDbPath } = await import("./paths.ts");
+const _dbPath = resolveDbPath(import.meta.dirname);
 
 const _pageCount = (() => {
   try {
@@ -116,7 +138,7 @@ initDb();
 
 const server = new McpServer({
   name: "rosetta",
-  version: typeof VERSION !== "undefined" ? VERSION : "0.2.0",
+  version: RESOLVED_VERSION,
 });
 
 // ---- routeros_search ----
@@ -180,19 +202,17 @@ Use after routeros_search identifies a relevant page. Pass the numeric page ID
 Returns: plain text, code blocks, and callout blocks (notes, warnings, info, tips).
 Callouts contain crucial caveats and edge-case details — always review them.
 
-**Large page handling:** Always set max_length (e.g., 30000) on the first call.
-Some pages are 100K+ chars. When max_length is set and the page exceeds it,
+**Large page handling:** max_length defaults to 16000. When page content exceeds it,
 pages with sections return a **table of contents** instead of truncated text.
 The TOC lists each section's heading, hierarchy level, character count, and
 deep-link URL. Re-call with the section parameter to retrieve specific sections.
 
 **Section parameter:** Pass a section heading or anchor_id (from the TOC)
-to get that section's content. Parent sections automatically include all
-sub-section content, so requesting a top-level heading gives you everything
-under it.
+to get that section's content. If a section is still too large, its sub-section
+TOC is returned instead — request a more specific sub-section.
 
 Recommended workflow for large pages:
-1. Call with max_length=30000 → get TOC if page is large
+1. First call → get TOC if page is large (automatic with default max_length)
 2. Review section headings to find the relevant section
 3. Call again with section="Section Name" to get that section's content
 
@@ -209,12 +229,12 @@ Workflow — what to do with this content:
         .number()
         .int()
         .min(1000)
-        .optional()
-        .describe("Recommended: set to 30000. Max combined text+code length. If exceeded and page has sections, returns a TOC instead of truncated text. Omit only if you need the entire page."),
+        .default(16000)
+        .describe("Max combined text+code length (default: 16000). If exceeded and page has sections, returns a TOC instead of truncated text. Set higher (e.g. 50000) to get more content in one call."),
       section: z
         .string()
         .optional()
-        .describe("Section heading or anchor_id from TOC. Returns only that section's content."),
+        .describe("Section heading or anchor_id from TOC. Returns only that section's content (also subject to max_length)."),
     },
   },
   async ({ page, max_length, section }) => {
@@ -451,6 +471,29 @@ Examples:
 
 // ---- routeros_search_changelogs ----
 
+/** Group flat changelog results by version for compact output. */
+function groupChangelogsByVersion(results: Array<{ version: string; released: string | null; category: string; is_breaking: number; description: string }>) {
+  const byVersion = new Map<string, { released: string | null; entries: Array<{ category: string; is_breaking: number; description: string }> }>();
+  for (const r of results) {
+    let group = byVersion.get(r.version);
+    if (!group) {
+      group = { released: r.released, entries: [] };
+      byVersion.set(r.version, group);
+    }
+    group.entries.push({ category: r.category, is_breaking: r.is_breaking, description: r.description });
+  }
+  return {
+    total_entries: results.length,
+    versions: Array.from(byVersion.entries()).map(([version, { released, entries }]) => ({
+      version,
+      released,
+      entry_count: entries.length,
+      breaking_count: entries.filter(e => e.is_breaking).length,
+      entries,
+    })),
+  };
+}
+
 server.registerTool(
   "routeros_search_changelogs",
   {
@@ -484,7 +527,7 @@ Coverage depends on which versions were extracted — typically matches ros_vers
       from_version: z
         .string()
         .optional()
-        .describe("Start of version range, inclusive (e.g., '7.21')"),
+        .describe("Start of version range, EXCLUSIVE — returns changes AFTER this version (e.g., from_version='7.21.3' excludes 7.21.3 entries, includes 7.22+)"),
       to_version: z
         .string()
         .optional()
@@ -501,10 +544,10 @@ Coverage depends on which versions were extracted — typically matches ros_vers
         .number()
         .int()
         .min(1)
-        .max(100)
+        .max(500)
         .optional()
-        .default(20)
-        .describe("Max results (default 20)"),
+        .default(50)
+        .describe("Max results (default 50, max 500). Version-range queries often need higher limits."),
     },
   },
   async ({ query, version, from_version, to_version, category, breaking_only, limit }) => {
@@ -535,8 +578,10 @@ Coverage depends on which versions were extracted — typically matches ros_vers
         ],
       };
     }
+    // Group by version for compact output — avoids repeating version/released on every entry
+    const grouped = groupChangelogsByVersion(results);
     return {
-      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+      content: [{ type: "text", text: JSON.stringify(grouped, null, 2) }],
     };
   },
 );
@@ -719,7 +764,94 @@ Requires network access to upgrade.mikrotik.com.`,
 
 // ---- Start ----
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
+if (useHttp) {
+  const { existsSync } = await import("node:fs");
+  const { WebStandardStreamableHTTPServerTransport } = await import(
+    "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"
+  );
+
+  const port = Number(getArg("--port") ?? process.env.PORT ?? 8080);
+  const hostname = getArg("--host") ?? process.env.HOST ?? "localhost";
+  const tlsCert = getArg("--tls-cert") ?? process.env.TLS_CERT_PATH;
+  const tlsKey = getArg("--tls-key") ?? process.env.TLS_KEY_PATH;
+
+  if ((tlsCert && !tlsKey) || (!tlsCert && tlsKey)) {
+    process.stderr.write(
+      "Error: TLS cert and key must both be provided (via flags or TLS_CERT_PATH/TLS_KEY_PATH)\n"
+    );
+    process.exit(1);
+  }
+  if (tlsCert && !existsSync(tlsCert)) {
+    process.stderr.write(`Error: TLS certificate not found: ${tlsCert}\n`);
+    process.exit(1);
+  }
+  if (tlsKey && !existsSync(tlsKey)) {
+    process.stderr.write(`Error: TLS private key not found: ${tlsKey}\n`);
+    process.exit(1);
+  }
+
+  const useTls = !!(tlsCert && tlsKey);
+  const scheme = useTls ? "https" : "http";
+
+  const httpTransport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+    enableJsonResponse: false,
+  });
+
+  await server.connect(httpTransport);
+
+  const isLAN = hostname === "0.0.0.0" || hostname === "::";
+  if (isLAN) {
+    process.stderr.write(
+      "Warning: Binding to all interfaces — the MCP server will be accessible from the network.\n"
+    );
+    if (!useTls) {
+      process.stderr.write(
+        "  Consider using --tls-cert/--tls-key or a reverse proxy for production use.\n"
+      );
+    }
+  }
+
+  Bun.serve({
+    port,
+    hostname,
+    ...(useTls && tlsCert && tlsKey
+      ? { tls: { cert: Bun.file(tlsCert), key: Bun.file(tlsKey) } }
+      : {}),
+    async fetch(req: Request): Promise<Response> {
+      const url = new URL(req.url);
+
+      // DNS rebinding protection: reject browser-origin requests
+      const origin = req.headers.get("origin");
+      if (origin) {
+        try {
+          const originHost = new URL(origin).host;
+          const serverHost = `${hostname === "0.0.0.0" || hostname === "::" ? "localhost" : hostname}:${port}`;
+          if (originHost !== serverHost && originHost !== `localhost:${port}` && originHost !== `127.0.0.1:${port}`) {
+            return new Response("Forbidden: Origin not allowed", { status: 403 });
+          }
+        } catch {
+          return new Response("Forbidden: Invalid Origin", { status: 403 });
+        }
+      }
+
+      if (url.pathname === "/mcp") {
+        return httpTransport.handleRequest(req);
+      }
+
+      return new Response("Not Found", { status: 404 });
+    },
+  });
+
+  const displayHost = isLAN ? "localhost" : hostname;
+  process.stderr.write(`rosetta ${RESOLVED_VERSION} — Streamable HTTP\n`);
+  process.stderr.write(`  ${scheme}://${displayHost}:${port}/mcp\n`);
+} else {
+  const { StdioServerTransport } = await import(
+    "@modelcontextprotocol/sdk/server/stdio.js"
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
 
 })();

package/src/paths.ts

@@ -0,0 +1,92 @@
+/**
+ * paths.ts — Shared DB path resolution for all entry points.
+ *
+ * Three modes:
+ *   1. Compiled binary (IS_COMPILED) → next to executable
+ *   2. Dev mode (.git exists in project root) → project root
+ *   3. Package mode (bunx / bun add -g) → ~/.rosetta/
+ *
+ * DB_PATH env var overrides all modes.
+ * This module must NOT import db.ts or bun:sqlite — it's used before the DB is opened.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+declare const IS_COMPILED: boolean;
+declare const VERSION: string;
+
+/** True when running as a compiled binary (bun build --compile) */
+export function isCompiled(): boolean {
+  try {
+    return typeof IS_COMPILED !== "undefined" && IS_COMPILED;
+  } catch {
+    return false;
+  }
+}
+
+/** True when running from a git checkout (dev mode) */
+function isDevMode(projectRoot: string): boolean {
+  return existsSync(path.join(projectRoot, ".git"));
+}
+
+/**
+ * Resolve the directory where ros-help.db should live.
+ * - Compiled: directory containing the executable
+ * - Dev: project root (one level up from src/)
+ * - Package (bunx / global install): ~/.rosetta/
+ */
+export function resolveBaseDir(srcDir: string): string {
+  if (isCompiled()) {
+    return path.dirname(process.execPath);
+  }
+
+  const projectRoot = path.resolve(srcDir, "..");
+  if (isDevMode(projectRoot)) {
+    return projectRoot;
+  }
+
+  // Package mode — stable user-local directory
+  const dataDir = path.join(homedir(), ".rosetta");
+  mkdirSync(dataDir, { recursive: true });
+  return dataDir;
+}
+
+/**
+ * Resolve the full path to ros-help.db.
+ * DB_PATH env var overrides all detection logic.
+ */
+export function resolveDbPath(srcDir: string): string {
+  const envPath = process.env.DB_PATH?.trim();
+  if (envPath) return envPath;
+  return path.join(resolveBaseDir(srcDir), "ros-help.db");
+}
+
+/** Detect invocation mode: "compiled" | "dev" | "package" */
+export type InvocationMode = "compiled" | "dev" | "package";
+
+export function detectMode(srcDir: string): InvocationMode {
+  if (isCompiled()) return "compiled";
+  const projectRoot = path.resolve(srcDir, "..");
+  if (isDevMode(projectRoot)) return "dev";
+  return "package";
+}
+
+/**
+ * Resolve the version string.
+ * Compiled mode: injected at build time via --define.
+ * Dev/package mode: read from package.json.
+ */
+export function resolveVersion(srcDir: string): string {
+  try {
+    if (typeof VERSION !== "undefined") return VERSION;
+  } catch {}
+  try {
+    const pkgPath = path.join(srcDir, "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}

package/src/query.test.ts

@@ -877,13 +877,13 @@ describe("searchChangelogs", () => {
     }
   });
 
-  test("version range filter works", () => {
-    const results = searchChangelogs("", { fromVersion: "7.22", toVersion: "7.22.1" });
+  test("version range filter works (from_version exclusive, to_version inclusive)", () => {
+    const results = searchChangelogs("", { fromVersion: "7.21", toVersion: "7.22.1" });
     expect(results.length).toBeGreaterThan(0);
     for (const r of results) {
       expect(["7.22", "7.22.1"]).toContain(r.version);
     }
-    // Should not include 7.21
+    // Should not include 7.21 (from_version is exclusive)
     expect(results.some((r) => r.version === "7.21")).toBe(false);
   });
 
@@ -902,7 +902,8 @@ describe("searchChangelogs", () => {
   });
 
   test("FTS combined with version range", () => {
-    const results = searchChangelogs("MLAG", { fromVersion: "7.22", toVersion: "7.22" });
+    // from_version is exclusive, so use 7.21 to include 7.22
+    const results = searchChangelogs("MLAG", { fromVersion: "7.21", toVersion: "7.22" });
     expect(results.length).toBe(1);
     expect(results[0].category).toBe("bridge");
   });

package/src/query.ts

@@ -184,6 +184,7 @@ export function getPage(idOrTitle: string | number, maxLength?: number, section?
   word_count: number;
   code_lines: number;
   callouts: Array<{ type: string; content: string }>;
+  callout_summary?: { count: number; types: Record<string, number> };
   truncated?: { text_total: number; code_total: number };
   sections?: SectionTocEntry[];
   section?: { heading: string; level: number; anchor_id: string };
@@ -221,11 +222,11 @@ export function getPage(idOrTitle: string | number, maxLength?: number, section?
 
       const descendants = db
         .prepare(
-          `SELECT heading, level, text, code, word_count
+          `SELECT heading, level, anchor_id, text, code, word_count
            FROM sections WHERE page_id = ? AND sort_order > ? AND level > ? AND sort_order < ?
            ORDER BY sort_order`,
         )
-        .all(page.id, sec.sort_order, sec.level, upperBound) as Array<{ heading: string; level: number; text: string; code: string; word_count: number }>;
+        .all(page.id, sec.sort_order, sec.level, upperBound) as Array<{ heading: string; level: number; anchor_id: string; text: string; code: string; word_count: number }>;
 
       let fullText = sec.text;
       let fullCode = sec.code;
@@ -237,6 +238,34 @@ export function getPage(idOrTitle: string | number, maxLength?: number, section?
         totalWords += child.word_count;
       }
 
+      // If section+descendants exceed maxLength and there are subsections, return sub-TOC
+      if (maxLength && (fullText.length + fullCode.length) > maxLength && descendants.length > 0) {
+        const subToc: SectionTocEntry[] = [
+          { heading: sec.heading, level: sec.level, anchor_id: sec.anchor_id, char_count: sec.text.length + sec.code.length, url: `${page.url}#${sec.anchor_id}` },
+          ...descendants.map((d) => ({ heading: d.heading, level: d.level, anchor_id: d.anchor_id, char_count: d.text.length + d.code.length, url: `${page.url}#${d.anchor_id}` })),
+        ];
+        const totalChars = fullText.length + fullCode.length;
+        return {
+          id: page.id, title: page.title, path: page.path, url: `${page.url}#${sec.anchor_id}`,
+          text: "", code: "",
+          word_count: totalWords, code_lines: 0,
+          callouts: [], callout_summary: calloutSummary(callouts),
+          sections: subToc,
+          section: { heading: sec.heading, level: sec.level, anchor_id: sec.anchor_id },
+          note: `Section "${sec.heading}" content (${totalChars} chars) exceeds max_length (${maxLength}). Showing ${subToc.length} sub-sections. Re-call with a more specific section heading or anchor_id.`,
+        };
+      }
+
+      // If section exceeds maxLength but has no sub-sections, truncate
+      if (maxLength && (fullText.length + fullCode.length) > maxLength) {
+        const textTotal = fullText.length;
+        const codeTotal = fullCode.length;
+        const codeBudget = Math.min(codeTotal, Math.floor(maxLength * 0.2));
+        const textBudget = maxLength - codeBudget;
+        fullText = `${fullText.slice(0, textBudget)}\n\n[... truncated — ${textTotal} chars total, showing first ${textBudget}]`;
+        fullCode = codeTotal > codeBudget ? `${fullCode.slice(0, codeBudget)}\n# [... truncated — ${codeTotal} chars total]` : fullCode;
+      }
+
       return {
         id: page.id,
         title: page.title,
@@ -258,7 +287,8 @@ export function getPage(idOrTitle: string | number, maxLength?: number, section?
         id: page.id, title: page.title, path: page.path, url: page.url,
         text: "", code: "",
         word_count: page.word_count, code_lines: page.code_lines,
-        callouts, sections: toc,
+        callouts: [], callout_summary: calloutSummary(callouts),
+        sections: toc,
         note: `Section "${section}" not found. ${toc.length} sections available — use a heading or anchor_id from the list.`,
       };
     }
@@ -284,7 +314,8 @@ export function getPage(idOrTitle: string | number, maxLength?: number, section?
         id: page.id, title: page.title, path: page.path, url: page.url,
         text: "", code: "",
         word_count: page.word_count, code_lines: page.code_lines,
-        callouts, sections: toc,
+        callouts: [], callout_summary: calloutSummary(callouts),
+        sections: toc,
         truncated: { text_total: text.length, code_total: code.length },
         note: `Page content (${totalChars} chars) exceeds max_length (${maxLength}). Showing table of contents with ${toc.length} sections. Re-call with section parameter to retrieve specific sections.`,
       };
@@ -303,6 +334,13 @@ export function getPage(idOrTitle: string | number, maxLength?: number, section?
   return { id: page.id, title: page.title, path: page.path, url: page.url, text, code, word_count: page.word_count, code_lines: page.code_lines, callouts, ...(truncated ? { truncated } : {}) };
 }
 
+/** Build compact callout summary (count + type breakdown) for TOC-mode responses. */
+function calloutSummary(callouts: Array<{ type: string; content: string }>): { count: number; types: Record<string, number> } {
+  const types: Record<string, number> = {};
+  for (const c of callouts) types[c.type] = (types[c.type] || 0) + 1;
+  return { count: callouts.length, types };
+}
+
 /** Build section TOC for a page. */
 function getPageToc(pageId: number, pageUrl: string): SectionTocEntry[] {
   const rows = db
@@ -825,14 +863,14 @@ function getChangelogVersions(): string[] {
   return rows.map((r) => r.version).sort(compareVersions);
 }
 
-/** Filter versions to those within [fromVersion, toVersion] range (inclusive). */
+/** Filter versions to those within (fromVersion, toVersion] range (fromVersion exclusive, toVersion inclusive). */
 function filterVersionRange(
   versions: string[],
   fromVersion?: string,
   toVersion?: string,
 ): string[] {
   return versions.filter((v) => {
-    if (fromVersion && compareVersions(v, fromVersion) < 0) return false;
+    if (fromVersion && compareVersions(v, fromVersion) <= 0) return false;
     if (toVersion && compareVersions(v, toVersion) > 0) return false;
     return true;
   });

package/src/release.test.ts

@@ -88,25 +88,27 @@ describe("bin/rosetta.js", () => {
 // ---------------------------------------------------------------------------
 
 describe("build-time constants", () => {
-  test("mcp.ts declares VERSION", () => {
+  test("mcp.ts imports resolveVersion from paths.ts", () => {
     const src = readText("src/mcp.ts");
-    expect(src).toContain("declare const VERSION");
+    expect(src).toContain("resolveVersion");
   });
 
-  test("mcp.ts declares IS_COMPILED", () => {
+  test("mcp.ts does not have hardcoded version fallback", () => {
     const src = readText("src/mcp.ts");
-    expect(src).toContain("declare const IS_COMPILED");
+    expect(src).not.toContain('"0.2.0"');
+    expect(src).not.toContain("\"dev\"");
   });
 
-  test("db.ts declares IS_COMPILED", () => {
-    const src = readText("src/db.ts");
+  test("paths.ts declares IS_COMPILED and VERSION", () => {
+    const src = readText("src/paths.ts");
     expect(src).toContain("declare const IS_COMPILED");
+    expect(src).toContain("declare const VERSION");
   });
 
-  test("setup.ts declares REPO_URL and VERSION", () => {
+  test("setup.ts declares REPO_URL and imports resolveVersion", () => {
     const src = readText("src/setup.ts");
     expect(src).toContain("declare const REPO_URL");
-    expect(src).toContain("declare const VERSION");
+    expect(src).toContain("resolveVersion");
   });
 
   test("build script injects all three constants", () => {

package/src/setup.ts

@@ -1,51 +1,22 @@
 /**
  * setup.ts — Download the RouterOS documentation database and print MCP client config.
  *
- * Called by `rosetta --setup` (compiled binary) or `bun run src/setup.ts` (dev).
+ * Called by `rosetta --setup` (compiled binary), `bunx @tikoci/rosetta --setup`,
+ * or `bun run src/setup.ts` (dev).
  * Downloads ros-help.db.gz from the latest GitHub Release, decompresses it,
  * validates the DB, and prints config snippets for each MCP client.
  */
 
+import { execSync } from "node:child_process";
 import { existsSync, writeFileSync } from "node:fs";
-import path from "node:path";
 import { gunzipSync } from "bun";
+import { detectMode, resolveBaseDir, resolveDbPath, resolveVersion } from "./paths.ts";
 
 declare const REPO_URL: string;
-declare const VERSION: string;
 
 const GITHUB_REPO =
   typeof REPO_URL !== "undefined" ? REPO_URL : "tikoci/rosetta";
-const RELEASE_VERSION =
-  typeof VERSION !== "undefined" ? VERSION : "dev";
-
-/** Where the binary (or dev project root) lives */
-function getBaseDir(): string {
-  // If IS_COMPILED is defined, use the executable's directory
-  // Otherwise use project root (one level up from src/)
-  try {
-    // @ts-expect-error IS_COMPILED defined at build time
-    if (typeof IS_COMPILED !== "undefined" && IS_COMPILED) {
-      return path.dirname(process.execPath);
-    }
-  } catch {
-    // not compiled
-  }
-  return path.resolve(import.meta.dirname, "..");
-}
-
-/** The binary/script path for MCP config */
-function getServerCommand(): string {
-  try {
-    // @ts-expect-error IS_COMPILED defined at build time
-    if (typeof IS_COMPILED !== "undefined" && IS_COMPILED) {
-      return process.execPath;
-    }
-  } catch {
-    // not compiled
-  }
-  // Dev mode — bun run src/mcp.ts
-  return path.resolve(import.meta.dirname, "mcp.ts");
-}
+const RELEASE_VERSION = resolveVersion(import.meta.dirname);
 
 /** Check if a DB file exists and has actual page data */
 function dbHasData(dbPath: string): boolean {
@@ -90,10 +61,8 @@ export async function downloadDb(
 }
 
 export async function runSetup(force = false) {
-  const baseDir = getBaseDir();
-  const dbPath = path.join(baseDir, "ros-help.db");
-  const serverCmd = getServerCommand();
-  const isCompiled = serverCmd === process.execPath;
+  const mode = detectMode(import.meta.dirname);
+  const dbPath = resolveDbPath(import.meta.dirname);
 
   console.log(`rosetta ${RELEASE_VERSION}`);
   console.log();
@@ -118,7 +87,8 @@ export async function runSetup(force = false) {
     console.log(`✓ Database ready (${row.c} pages, ${cmdRow.c} commands)`);
   } catch (e) {
     console.error(`✗ Database validation failed: ${e}`);
-    console.error(`  Try re-downloading with: ${isCompiled ? path.basename(serverCmd) : "bun run src/setup.ts"} --setup --force`);
+    const retryCmd = mode === "compiled" ? "rosetta" : mode === "package" ? "bunx @tikoci/rosetta" : "bun run src/setup.ts";
+    console.error(`  Try re-downloading with: ${retryCmd} --setup --force`);
     process.exit(1);
   }
 
@@ -128,10 +98,21 @@ export async function runSetup(force = false) {
   console.log("Configure your MCP client:");
   console.log("─".repeat(60));
 
-  if (isCompiled) {
-    printCompiledConfig(serverCmd);
+  if (mode === "compiled") {
+    printCompiledConfig(process.execPath);
+  } else if (mode === "package") {
+    printPackageConfig();
   } else {
-    printDevConfig(baseDir);
+    printDevConfig(resolveBaseDir(import.meta.dirname));
+  }
+}
+
+/** Try to resolve the absolute path to bunx (for clients that don't inherit PATH) */
+function resolveBunxPath(): string | null {
+  try {
+    return execSync("which bunx", { encoding: "utf-8" }).trim() || null;
+  } catch {
+    return null;
   }
 }
 
@@ -175,6 +156,82 @@ function printCompiledConfig(serverCmd: string) {
   console.log(`    }`);
   console.log(`  }`);
   console.log();
+
+  // Copilot CLI
+  console.log("▸ GitHub Copilot CLI");
+  console.log(`  Inside a copilot session, type /mcp add:`);
+  console.log(`    Name: routeros-rosetta  |  Type: STDIO  |  Command: ${serverCmd}`);
+  console.log();
+
+  // OpenAI Codex
+  console.log("▸ OpenAI Codex");
+  console.log(`  codex mcp add rosetta -- ${serverCmd}`);
+  console.log();
+
+  printHttpConfig(`${serverCmd} --http`);
+}
+
+function printPackageConfig() {
+  // Resolve full path to bunx — Claude Desktop doesn't inherit shell PATH
+  const bunxFullPath = resolveBunxPath();
+
+  // Claude Desktop
+  const isMac = process.platform === "darwin";
+  const configPath = isMac
+    ? "~/Library/Application\\ Support/Claude/claude_desktop_config.json"
+    : "%APPDATA%\\Claude\\claude_desktop_config.json";
+
+  const bunxCmd = bunxFullPath ? JSON.stringify(bunxFullPath) : "\"bunx\"";
+  console.log();
+  console.log("▸ Claude Desktop");
+  console.log(`  Edit: ${configPath}`);
+  console.log();
+  console.log(`  {`);
+  console.log(`    "mcpServers": {`);
+  console.log(`      "rosetta": {`);
+  console.log(`        "command": ${bunxCmd},`);
+  console.log(`        "args": ["@tikoci/rosetta"]`);
+  console.log(`      }`);
+  console.log(`    }`);
+  console.log(`  }`);
+  console.log();
+  if (bunxFullPath) {
+    console.log(`  Note: Full path used because Claude Desktop may not inherit shell PATH.`);
+    console.log();
+  }
+  console.log(`  Then restart Claude Desktop.`);
+
+  // Claude Code (inherits PATH — short form is fine)
+  console.log();
+  console.log("▸ Claude Code");
+  console.log(`  claude mcp add rosetta -- bunx @tikoci/rosetta`);
+
+  // VS Code Copilot (inherits PATH)
+  console.log();
+  console.log("▸ VS Code Copilot (User Settings JSON)");
+  console.log();
+  console.log(`  "mcp": {`);
+  console.log(`    "servers": {`);
+  console.log(`      "rosetta": {`);
+  console.log(`        "command": "bunx",`);
+  console.log(`        "args": ["@tikoci/rosetta"]`);
+  console.log(`      }`);
+  console.log(`    }`);
+  console.log(`  }`);
+  console.log();
+
+  // Copilot CLI (inherits PATH)
+  console.log("▸ GitHub Copilot CLI");
+  console.log(`  Inside a copilot session, type /mcp add:`);
+  console.log(`    Name: routeros-rosetta  |  Type: STDIO  |  Command: bunx @tikoci/rosetta`);
+  console.log();
+
+  // OpenAI Codex (inherits PATH)
+  console.log("▸ OpenAI Codex");
+  console.log(`  codex mcp add rosetta -- bunx @tikoci/rosetta`);
+  console.log();
+
+  printHttpConfig("bunx @tikoci/rosetta --http");
 }
 
 function printDevConfig(baseDir: string) {
@@ -212,6 +269,38 @@ function printDevConfig(baseDir: string) {
   console.log("▸ VS Code Copilot");
   console.log(`  The repo includes .vscode/mcp.json — just open the folder in VS Code.`);
   console.log();
+
+  // Copilot CLI
+  console.log("▸ GitHub Copilot CLI");
+  console.log(`  Inside a copilot session, type /mcp add:`);
+  console.log(`    Name: routeros-rosetta  |  Type: STDIO  |  Command: bun run src/mcp.ts`);
+  console.log();
+
+  // OpenAI Codex
+  console.log("▸ OpenAI Codex");
+  console.log(`  codex mcp add rosetta -- bun run src/mcp.ts`);
+  console.log();
+
+  printHttpConfig(`bun run src/mcp.ts --http`);
+}
+
+function printHttpConfig(startCmd: string) {
+  console.log("─".repeat(60));
+  console.log("Streamable HTTP transport (for HTTP-only MCP clients):");
+  console.log("─".repeat(60));
+  console.log();
+  console.log("▸ Start in HTTP mode");
+  console.log(`  ${startCmd}`);
+  console.log(`  ${startCmd} --port 9090`);
+  console.log(`  ${startCmd} --host 0.0.0.0          # LAN access`);
+  console.log(`  ${startCmd} --tls-cert cert.pem --tls-key key.pem  # HTTPS`);
+  console.log();
+  console.log("▸ URL-based MCP clients (OpenAI, etc.)");
+  console.log(`  { "url": "http://localhost:8080/mcp" }`);
+  console.log();
+  console.log("  For LAN access, replace localhost with the server's IP address.");
+  console.log("  Use a reverse proxy (nginx, caddy) for production HTTPS.");
+  console.log();
 }
 
 // Run directly