@tikoci/rosetta 0.2.0 → 0.2.1

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 transport.
 
 ## What's Inside
 
@@ -24,45 +24,53 @@ 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.
+### Option A: Install with Bun (recommended)
 
-### 1. Download
+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.
 
-Go to the [latest release](https://github.com/tikoci/rosetta/releases/latest) and download the ZIP for your platform:
+**1. Install Bun** (if you don't have it):
 
-| 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` |
+```sh
+# macOS / Linux
+curl -fsSL https://bun.sh/install | bash
 
-Extract the ZIP to a permanent location (e.g., `~/rosetta` or `C:\rosetta`).
+# Windows
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
 
-### 2. Run 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).
 
-Open a terminal in the extracted folder and run:
+<details>
+<summary><b>VS Code Copilot</b></summary>
 
-```sh
-./rosetta --setup
-```
+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)"):
 
-On Windows:
-```powershell
-.\rosetta.exe --setup
+```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 +82,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>
 
-#### VS Code Copilot
+Inside a `copilot` session, type `/mcp add` to open the interactive form:
 
-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.
+- **Server Name:** `routeros-rosetta`
+- **Server Type:** 2 (STDIO)
+- **Command:** `bunx @tikoci/rosetta`
 
-Or add to your User Settings JSON (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"):
+Press <kbd>Tab</kbd> to navigate fields, <kbd>Ctrl+S</kbd> to save.
+
+</details>
+
+<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 +185,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 +195,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 +203,18 @@ 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
-
-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.
-
-### 1. Install Bun
-
-```sh
-# macOS / Linux
-curl -fsSL https://bun.sh/install | bash
-# or: brew install oven-sh/bun/bun
-
-# Windows
-powershell -c "irm bun.sh/install.ps1 | iex"
-```
-
-### 2. Download and Install
-
-```sh
-git clone https://github.com/tikoci/rosetta.git
-cd rosetta
-bun install
-```
-
-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`.
-
-### 3. Run Setup
-
-```sh
-bun run src/mcp.ts --setup
-```
-
-This downloads the documentation database and prints MCP client configuration. The config uses `bun` as the command with `src/mcp.ts` as the entrypoint:
-
-#### Claude Desktop
-
-```json
-{
-  "mcpServers": {
-    "rosetta": {
-      "command": "bun",
-      "args": ["run", "src/mcp.ts"],
-      "cwd": "/path/to/rosetta"
-    }
-  }
-}
-```
-
-#### Claude Code
-
-```sh
-claude mcp add rosetta -- bun run src/mcp.ts --cwd /path/to/rosetta
-```
-
-#### VS Code Copilot
-
-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.
-
-Or add to your User Settings JSON:
-
-```json
-"mcp": {
-  "servers": {
-    "rosetta": {
-      "command": "bun",
-      "args": ["run", "src/mcp.ts"],
-      "cwd": "/path/to/rosetta"
-    }
-  }
-}
-```
+## Troubleshooting
 
-Replace `/path/to/rosetta` with the actual path (printed by `--setup`).
+| 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). |
 
 ## Building from Source
 
@@ -271,7 +280,7 @@ This cross-compiles to macOS (arm64 + x64), Windows (x64), and Linux (x64), crea
 
 ```text
 src/
-├── mcp.ts                  # MCP server (10 tools, stdio) + CLI dispatch
+├── mcp.ts                  # MCP server (11 tools, stdio) + 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

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.2.1",
   "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

@@ -15,22 +15,21 @@
  *   DB_PATH — absolute path to ros-help.db (default: next to binary or project root)
  */
 
-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);
 
 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)");
@@ -65,12 +64,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 +111,7 @@ initDb();
 
 const server = new McpServer({
   name: "rosetta",
-  version: typeof VERSION !== "undefined" ? VERSION : "0.2.0",
+  version: RESOLVED_VERSION,
 });
 
 // ---- routeros_search ----
@@ -451,6 +446,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 +502,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 +519,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 +553,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) }],
     };
   },
 );

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

@@ -825,14 +825,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,78 @@ 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();
+}
+
+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();
 }
 
 function printDevConfig(baseDir: string) {
@@ -212,6 +265,17 @@ 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();
 }
 
 // Run directly