annas-mcp 0.1.1 → 0.1.2

package/README.md

@@ -2,6 +2,7 @@
 
 [![Tests](https://github.com/SokolskyNikita/annas-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/SokolskyNikita/annas-mcp/actions/workflows/test.yml)
 [![Release](https://img.shields.io/github/v/release/SokolskyNikita/annas-mcp)](https://github.com/SokolskyNikita/annas-mcp/releases)
+[![npm](https://img.shields.io/npm/v/annas-mcp)](https://www.npmjs.com/package/annas-mcp)
 
 An MCP server that lets Claude, Cursor, Codex and other AI clients search [Anna's Archive](https://annas-archive.gl) for books and papers and download the file you pick. It also works as a command-line tool.
 
@@ -37,19 +38,21 @@ claude mcp add annas-mcp \
   --env ANNAS_ACCOUNT_COOKIE=your-cookie \
   --env ANNAS_SECRET_KEY=your-api-key \
   --env ANNAS_DOWNLOAD_PATH=/absolute/path/to/downloads \
-  -- npx -y github:SokolskyNikita/annas-mcp
+  -- npx -y annas-mcp
 ```
 
-On native Windows (not WSL), end the command with `-- cmd /c npx -y github:SokolskyNikita/annas-mcp`.
+On native Windows (not WSL), end the command with `-- cmd /c npx -y annas-mcp`.
 
-**Claude Desktop and Cursor.** Add this to Claude Desktop's config (Settings → Developer → Edit Config) or to Cursor's `~/.cursor/mcp.json`:
+**Claude Desktop, one click.** Download [annas-mcp.mcpb](https://github.com/SokolskyNikita/annas-mcp/releases/latest/download/annas-mcp.mcpb) and open it, or drag it onto Settings → Extensions. Claude Desktop asks for the cookie, API key and download folder.
+
+**Claude Desktop and Cursor, by hand.** Add this to Claude Desktop's config (Settings → Developer → Edit Config) or to Cursor's `~/.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "annas-mcp": {
       "command": "npx",
-      "args": ["-y", "github:SokolskyNikita/annas-mcp"],
+      "args": ["-y", "annas-mcp"],
       "env": {
         "ANNAS_ACCOUNT_COOKIE": "your-cookie",
         "ANNAS_SECRET_KEY": "your-api-key",
@@ -65,7 +68,7 @@ On native Windows (not WSL), end the command with `-- cmd /c npx -y github:Sokol
 ```toml
 [mcp_servers.annas-mcp]
 command = "npx"
-args = ["-y", "github:SokolskyNikita/annas-mcp"]
+args = ["-y", "annas-mcp"]
 
 [mcp_servers.annas-mcp.env]
 ANNAS_ACCOUNT_COOKIE = "your-cookie"
@@ -147,17 +150,17 @@ Errors start with a code:
 
 A failed download lists every server it tried and why each one failed. A server starting up cleanly doesn't prove your credentials work; only a search or download tests them.
 
-If the server doesn't start at all, run `npx -y github:SokolskyNikita/annas-mcp --version` in a terminal to see the error. The launcher unpacks releases with the system's `tar`, which comes preinstalled on macOS, Windows 10 and later, and mainstream Linux distributions.
+If the server doesn't start at all, run `npx -y annas-mcp --version` in a terminal to see the error. The launcher unpacks releases with the system's `tar`, which comes preinstalled on macOS, Windows 10 and later, and mainstream Linux distributions.
 
 ## Command line
 
 Every tool is also a command. Set the same variables (or put them in a `.env` file), then:
 
 ```bash
-npx -y github:SokolskyNikita/annas-mcp book-search "pride and prejudice" --language en
-npx -y github:SokolskyNikita/annas-mcp article-search 10.1038/nature14539
-npx -y github:SokolskyNikita/annas-mcp book-download <hash> "Pride and Prejudice.epub"
-npx -y github:SokolskyNikita/annas-mcp article-download 10.1038/nature14539
+npx -y annas-mcp book-search "pride and prejudice" --language en
+npx -y annas-mcp article-search 10.1038/nature14539
+npx -y annas-mcp book-download <hash> "Pride and Prejudice.epub"
+npx -y annas-mcp article-download 10.1038/nature14539
 ```
 
 Add `--json` for machine-readable output, `--timeout 10m` to change the timeout, and `--help` to any command for all of its options.

package/lib/archive.js

@@ -34,9 +34,25 @@ export function validateArchiveEntryName(rawName) {
   return name;
 }
 
+// Releases ship .tar.gz because gzip is present on minimal systems where xz
+// often is not. .tar.xz is still understood for older releases.
+function compressionFlag(extension) {
+  switch (extension) {
+    case "zip":
+      return "";
+    case "tar.gz":
+      return "z";
+    case "tar.xz":
+      return "J";
+    default:
+      throw new Error(`Unsupported archive format: ${extension}`);
+  }
+}
+
 export function validateArchiveEntries(archive, extension, spawnSync = defaultSpawnSync) {
   const tar = tarExecutable();
-  const listingArgs = extension === "zip" ? ["-tf", archive] : ["-tJf", archive];
+  const compression = compressionFlag(extension);
+  const listingArgs = [`-t${compression}f`, archive];
   const listing = spawnSync(tar, listingArgs, { encoding: "utf8" });
   if (listing.error || listing.status !== 0) {
     throw tarFailure("inspect", archive, listing);
@@ -47,7 +63,7 @@ export function validateArchiveEntries(archive, extension, spawnSync = defaultSp
     }
   }
 
-  const verboseArgs = extension === "zip" ? ["-tvf", archive] : ["-tvJf", archive];
+  const verboseArgs = [`-tv${compression}f`, archive];
   const verbose = spawnSync(tar, verboseArgs, { encoding: "utf8" });
   if (verbose.error || verbose.status !== 0) {
     throw tarFailure("inspect", archive, verbose);
@@ -66,10 +82,7 @@ export function validateArchiveEntries(archive, extension, spawnSync = defaultSp
 export function extractArchive(archive, destination, extension, spawnSync = defaultSpawnSync) {
   validateArchiveEntries(archive, extension, spawnSync);
   const tar = tarExecutable();
-  const args =
-    extension === "zip"
-      ? ["-xf", archive, "-C", destination]
-      : ["-xJf", archive, "-C", destination];
+  const args = [`-x${compressionFlag(extension)}f`, archive, "-C", destination];
   const result = spawnSync(tar, args, { encoding: "utf8" });
   if (result.error || result.status !== 0) {
     throw tarFailure("extract", archive, result);

package/lib/launcher.js

@@ -27,6 +27,7 @@ import {
   selectAsset,
   selectChecksumAsset,
   sha256Digest,
+  targetForRelease,
 } from "./target.js";
 
 export const GITHUB_REPO = "SokolskyNikita/annas-mcp";
@@ -70,12 +71,17 @@ export function isDirectRun(moduleURL = import.meta.url, argv = process.argv) {
   }
 }
 
+// Windows refuses to replace or open a file while another process is
+// replacing it, so concurrent launchers can briefly collide on current.json.
+const SHARING_ERROR_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
+const CACHE_META_RENAME_ATTEMPTS = 10;
+
 export async function readCacheMeta(dir) {
   try {
     const meta = JSON.parse(await readFile(path.join(dir, "current.json"), "utf8"));
     return meta && typeof meta === "object" && !Array.isArray(meta) ? meta : null;
   } catch (error) {
-    if (error.code === "ENOENT" || error instanceof SyntaxError) {
+    if (error.code === "ENOENT" || SHARING_ERROR_CODES.has(error.code) || error instanceof SyntaxError) {
       return null;
     }
     throw error;
@@ -221,11 +227,21 @@ export async function expectedArchiveChecksum(
   return expected;
 }
 
-export async function writeCacheMeta(dir, meta) {
+export async function writeCacheMeta(dir, meta, { renameImpl = rename, retryDelayMs = 25 } = {}) {
   const temporary = path.join(dir, `.current.json.${process.pid}.${randomUUID()}.tmp`);
   try {
     await writeFile(temporary, `${JSON.stringify(meta)}\n`);
-    await rename(temporary, path.join(dir, "current.json"));
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        await renameImpl(temporary, path.join(dir, "current.json"));
+        return;
+      } catch (error) {
+        if (!SHARING_ERROR_CODES.has(error.code) || attempt >= CACHE_META_RENAME_ATTEMPTS) {
+          throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, retryDelayMs * attempt));
+      }
+    }
   } finally {
     await rm(temporary, { force: true });
   }
@@ -297,7 +313,12 @@ export async function installBinary(
         binaryName: target.binaryName,
       },
     };
-    await writeCacheMeta(root, meta);
+    try {
+      await writeCacheMeta(root, meta);
+    } catch (error) {
+      // current.json only points later launches at this verified binary.
+      console.error(`annas-mcp: could not record the cached binary. ${error.message}`);
+    }
     return binaryPath;
   } finally {
     await rm(work, { recursive: true, force: true });
@@ -326,7 +347,8 @@ export async function resolveBinary(
   }
   try {
     const release = await fetchLatestRelease({ env, fetchImpl });
-    const asset = selectAsset(release.assets, target);
+    const releaseTarget = targetForRelease(release.assets, target);
+    const asset = selectAsset(release.assets, releaseTarget);
     const expectedAssetSha256 = await expectedArchiveChecksum(release, asset, { env, fetchImpl });
     const currentRelease = await cachedBinary(
       dir,
@@ -339,7 +361,7 @@ export async function resolveBinary(
     if (currentRelease) {
       return currentRelease;
     }
-    return await installBinaryImpl(release, asset, target, expectedAssetSha256, {
+    return await installBinaryImpl(release, asset, releaseTarget, expectedAssetSha256, {
       env,
       fetchImpl,
     });

package/lib/target.js

@@ -23,7 +23,7 @@ export function goreleaserTarget(platform = process.platform, arch = process.arc
   return {
     os: osName,
     arch: archName,
-    extension: osName === "windows" ? "zip" : "tar.xz",
+    extension: osName === "windows" ? "zip" : "tar.gz",
     binaryName: osName === "windows" ? "annas-mcp.exe" : "annas-mcp",
   };
 }
@@ -98,6 +98,21 @@ export function checksumFor(text, filename) {
   throw new Error(`Checksum file has no entry for ${filename}`);
 }
 
+// Releases before v0.1.2 ship only .tar.xz for non-Windows targets.
+export function targetForRelease(assets, target) {
+  if (target.extension !== "tar.gz") {
+    return target;
+  }
+  const suffix = `_${target.os}_${target.arch}.tar.gz`;
+  const hasGzip = (assets || []).some(
+    (asset) =>
+      typeof asset?.name === "string" &&
+      asset.name.startsWith("annas-mcp_") &&
+      asset.name.endsWith(suffix),
+  );
+  return hasGzip ? target : { ...target, extension: "tar.xz" };
+}
+
 export function selectAsset(assets, target) {
   const suffix = `_${target.os}_${target.arch}.${target.extension}`;
   const matches = (assets || []).filter(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "annas-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "description": "MCP server and CLI for searching and downloading books and articles from Anna's Archive",
   "mcpName": "io.github.SokolskyNikita/annas-mcp",
@@ -27,7 +27,8 @@
     "check:version": "node scripts/check-version.mjs",
     "coverage": "go test -race -coverprofile coverage.out ./... && node scripts/check-coverage.mjs coverage.out",
     "smoke": "node scripts/smoke-mcp.mjs",
-    "pack:mcpb": "node scripts/pack-mcpb.mjs"
+    "pack:mcpb": "node scripts/pack-mcpb.mjs",
+    "publish:smithery": "node scripts/publish-smithery.mjs"
   },
   "bin": {
     "annas-mcp": "bin/annas-mcp.js"