annas-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Sokolsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# annas-mcp
+
+[![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)
+
+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.
+
+| Tool | What it does |
+| --- | --- |
+| `book_search` | Finds books, textbooks, manuals and standards by title, author or topic |
+| `article_search` | Finds journal articles by keyword, or looks one up by DOI |
+| `book_download` | Downloads a book using the hash from a search result |
+| `article_download` | Downloads an article by DOI or hash |
+
+Use it only for material you are entitled to obtain, under the laws and terms that apply to you.
+
+## Setup
+
+You need Node.js 18 or newer and an Anna's Archive [membership](https://annas-archive.gl/donate):
+
+| To… | Membership |
+| --- | --- |
+| Search | **Lucky Librarian** or higher |
+| Download | Any tier |
+
+### 1. Get your credentials
+
+- **Account cookie.** Sign in to Anna's Archive, open your browser's developer tools and go to Application (Chrome, Edge) or Storage (Firefox, Safari) → Cookies. Copy the value of `aa_account_id2`. It expires weekly; see [Renewing the cookie](#renewing-the-cookie).
+- **API key.** Copy it from your Anna's Archive account page. See the [API FAQ](https://annas-archive.gl/faq#api). Only needed for downloads.
+
+### 2. Add the server to your client
+
+**Claude Code**
+
+```bash
+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
+```
+
+On native Windows (not WSL), end the command with `-- cmd /c npx -y github:SokolskyNikita/annas-mcp`.
+
+**Claude Desktop and Cursor.** 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"],
+      "env": {
+        "ANNAS_ACCOUNT_COOKIE": "your-cookie",
+        "ANNAS_SECRET_KEY": "your-api-key",
+        "ANNAS_DOWNLOAD_PATH": "/absolute/path/to/downloads"
+      }
+    }
+  }
+}
+```
+
+**Codex.** Add this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.annas-mcp]
+command = "npx"
+args = ["-y", "github:SokolskyNikita/annas-mcp"]
+
+[mcp_servers.annas-mcp.env]
+ANNAS_ACCOUNT_COOKIE = "your-cookie"
+ANNAS_SECRET_KEY = "your-api-key"
+ANNAS_DOWNLOAD_PATH = "/absolute/path/to/downloads"
+```
+
+Pick a permanent `ANNAS_DOWNLOAD_PATH`. Folders under `/tmp` are cleared by the operating system.
+
+### 3. Try it
+
+Restart your client and ask something like *"Find the EPUB of Pride and Prejudice and download it."* The AI searches, picks a copy and returns the path of the saved file.
+
+`npx` downloads the latest release on first run, verifies its checksum and caches it. Later runs start from the cache and pick up new releases automatically.
+
+## Renewing the cookie
+
+The `aa_account_id2` cookie expires every week. When searches start failing with `[UPSTREAM_BLOCKED]`:
+
+1. Copy a fresh `aa_account_id2` value from your browser, as in [step 1](#1-get-your-credentials).
+2. Replace `ANNAS_ACCOUNT_COOKIE` in your client's config.
+3. Restart the MCP server from your client.
+
+`ANNAS_ACCOUNT_COOKIE` accepts the bare value, `aa_account_id2=…` or a whole `Cookie` header copied from the Network tab. Only `aa_account_id2` is ever sent. Keep the cookie and API key private.
+
+## Configuration
+
+| Variable | Needed for | Description |
+| --- | --- | --- |
+| `ANNAS_ACCOUNT_COOKIE` | Everything | Your `aa_account_id2` cookie. |
+| `ANNAS_SECRET_KEY` | Downloads | Your Anna's Archive API key. |
+| `ANNAS_DOWNLOAD_PATH` | Downloads | Absolute folder for downloaded files. Created if missing. |
+| `ANNAS_BASE_URL` | Optional | Mirror to fall back on when automatic selection fails. Defaults to `annas-archive.gl`. |
+| `ANNAS_AUTO_BASE_URL` | Optional | Set to `false` to always use `ANNAS_BASE_URL` instead of picking a mirror automatically. |
+| `ANNAS_MCP_CACHE_DIR` | Optional | Where `npx` caches release binaries. |
+
+The server picks a working mirror by itself, and only among the official domains `annas-archive.gl`, `.pk` and `.gd`. Whatever host you set in `ANNAS_BASE_URL` receives your credentials, so only use one you trust.
+
+The server and CLI also read a `.env` file from their working directory. Variables already set in the environment take precedence.
+
+## Tools
+
+Every tool accepts `timeout_seconds`, covering the whole operation including retries. Searches default to 60 seconds and downloads to 30 minutes.
+
+### Searching
+
+`book_search` and `article_search` take a `query` and return one page of results. Each result includes a `hash`, title, authors, format, size and language, and books also include a publisher. Optional fields:
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `limit` | 10 | Results to return from the page. Raise this before asking for another page. |
+| `page` | 1 | Result page. |
+| `language` | Any | Two-letter code such as `en`. |
+| `content` | Any | `book_fiction`, `book_nonfiction`, `book_unknown`, `book_comic`, `magazine` or `standards_document`. |
+
+Give `article_search` a DOI (`10.1038/nature14539`, `doi:…` or `https://doi.org/…`) to get that one article instead of a page of results.
+
+### Downloading
+
+`book_download` takes the `hash` and a `title`. `article_download` takes either a `doi` or a `hash`, plus an optional `title`. Both return the saved file's `path` and size in `bytes`.
+
+- **Filename.** `title` becomes the filename. Pass `format` (such as `epub` or `pdf`) to set the extension; this doesn't convert the file. Without it, the extension is detected from the download.
+- **No overwrites.** An existing file is never overwritten: a name clash gets a short suffix.
+- **Integrity.** Files are checked against the archive's MD5 hash, and incomplete or corrupt downloads are deleted.
+- **DOI fallback.** When the fast download servers don't have a paper, `article_download` by DOI falls back to the PDF on Anna's SciDB page.
+
+## Troubleshooting
+
+Errors start with a code:
+
+| Code | What to do |
+| --- | --- |
+| `[CONFIG]` | A variable is missing or invalid. Check [Configuration](#configuration). |
+| `[UPSTREAM_BLOCKED]` | The archive refused access. Usually the cookie has expired: [renew it](#renewing-the-cookie). Also check your membership tier. |
+| `[NOT_FOUND]` | Nothing matched, or that copy has no fast download. Try another query, or another copy from the search results. |
+| `[INVALID_ARGUMENT]` | Fix the hash, DOI, format, page, limit or timeout. |
+| `[REQUEST_TIMEOUT]` | Retry, or raise `timeout_seconds`. |
+| `[UPSTREAM]` | The archive or a download server failed. Check your daily download quota and API key, then retry. |
+
+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.
+
+## 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
+```
+
+Add `--json` for machine-readable output, `--timeout 10m` to change the timeout, and `--help` to any command for all of its options.
+
+## Privacy
+
+annas-mcp runs on your machine and has no telemetry. It sends your cookie and API key only to Anna's Archive, and downloads files from the servers Anna's Archive points it to. DOI lookups may contact doi.org. The `npx` launcher and the MCP Bundle contact GitHub to fetch and verify release binaries. Downloaded files stay in `ANNAS_DOWNLOAD_PATH`; nothing else is stored apart from the cached binary. Questions: [open an issue](https://github.com/SokolskyNikita/annas-mcp/issues).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for building from source, tests and releases.
+
+## Credits
+
+The idea for this project comes from [iosifache/annas-mcp](https://github.com/iosifache/annas-mcp), which first exposed Anna's Archive as an MCP server. This repository is a complete rewrite and shares no code with it.
+
+## License
+
+[MIT](LICENSE)

package/bin/annas-mcp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { isDirectRun, main } from "../lib/launcher.js";
+
+if (isDirectRun(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}

package/lib/archive.js

@@ -0,0 +1,102 @@
+import { spawnSync as defaultSpawnSync } from "node:child_process";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+
+function tarFailure(action, archive, result) {
+  if (result.error) {
+    return new Error(`Failed to run tar: ${result.error.message}`);
+  }
+  const detail = (result.stderr || result.stdout || "").trim();
+  return new Error(`Failed to ${action} ${path.basename(archive)}${detail ? `: ${detail}` : ""}`);
+}
+
+// Git Bash can put its GNU tar before the Windows native tar on PATH. GNU tar
+// treats a drive-qualified path such as C:\\tmp\\archive.zip as a remote
+// archive name, so use the native bsdtar explicitly on Windows.
+export function tarExecutable(platform = process.platform, env = process.env) {
+  if (platform !== "win32") {
+    return "tar";
+  }
+  const systemRoot = env.SystemRoot || env.WINDIR || "C:\\Windows";
+  return path.win32.join(systemRoot, "System32", "tar.exe");
+}
+
+export function validateArchiveEntryName(rawName) {
+  const name = rawName.trim().replaceAll("\\", "/").replace(/\/+$/, "");
+  if (
+    !name ||
+    name.startsWith("/") ||
+    /^[A-Za-z]:\//.test(name) ||
+    name.split("/").includes("..")
+  ) {
+    throw new Error(`Refusing to extract an unsafe archive path: ${rawName}`);
+  }
+  return name;
+}
+
+export function validateArchiveEntries(archive, extension, spawnSync = defaultSpawnSync) {
+  const tar = tarExecutable();
+  const listingArgs = extension === "zip" ? ["-tf", archive] : ["-tJf", archive];
+  const listing = spawnSync(tar, listingArgs, { encoding: "utf8" });
+  if (listing.error || listing.status !== 0) {
+    throw tarFailure("inspect", archive, listing);
+  }
+  for (const rawName of listing.stdout.split(/\r?\n/)) {
+    if (rawName.trim()) {
+      validateArchiveEntryName(rawName);
+    }
+  }
+
+  const verboseArgs = extension === "zip" ? ["-tvf", archive] : ["-tvJf", archive];
+  const verbose = spawnSync(tar, verboseArgs, { encoding: "utf8" });
+  if (verbose.error || verbose.status !== 0) {
+    throw tarFailure("inspect", archive, verbose);
+  }
+  for (const line of verbose.stdout.split(/\r?\n/)) {
+    if (!line.trim()) {
+      continue;
+    }
+    const type = line[0];
+    if (type !== "-" && type !== "d") {
+      throw new Error(`Refusing non-file archive entry: ${line.trim()}`);
+    }
+  }
+}
+
+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 result = spawnSync(tar, args, { encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    throw tarFailure("extract", archive, result);
+  }
+}
+
+export async function findBinary(directory, binaryName, root = directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) {
+      continue;
+    }
+    const fullPath = path.join(directory, entry.name);
+    const relative = path.relative(root, fullPath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+      throw new Error(`Refusing to use a path outside the archive: ${entry.name}`);
+    }
+    if (entry.isDirectory()) {
+      const found = await findBinary(fullPath, binaryName, root);
+      if (found) {
+        return found;
+      }
+      continue;
+    }
+    if (entry.isFile() && entry.name === binaryName) {
+      return fullPath;
+    }
+  }
+  return null;
+}

package/lib/launcher.js

@@ -0,0 +1,380 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn as defaultSpawn } from "node:child_process";
+import { createWriteStream, realpathSync } from "node:fs";
+import {
+  chmod,
+  copyFile,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { extractArchive, findBinary } from "./archive.js";
+import {
+  checksumFor,
+  pathInside,
+  releaseAssetDigest,
+  goreleaserTarget,
+  safePathComponent,
+  selectAsset,
+  selectChecksumAsset,
+  sha256Digest,
+} from "./target.js";
+
+export const GITHUB_REPO = "SokolskyNikita/annas-mcp";
+export const RELEASE_TIMEOUT_MS = 5_000;
+export const DOWNLOAD_TIMEOUT_MS = 120_000;
+
+export function releaseAPI(env = process.env) {
+  return (
+    env.ANNAS_MCP_RELEASE_API ||
+    `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`
+  );
+}
+
+export function cacheDir(
+  env = process.env,
+  platform = process.platform,
+  homeDirectory = os.homedir(),
+) {
+  if (env.ANNAS_MCP_CACHE_DIR) {
+    return env.ANNAS_MCP_CACHE_DIR;
+  }
+  const base =
+    platform === "win32"
+      ? env.LOCALAPPDATA || path.join(homeDirectory, "AppData", "Local")
+      : env.XDG_CACHE_HOME || path.join(homeDirectory, ".cache");
+  return path.join(base, "annas-mcp");
+}
+
+export function isDirectRun(moduleURL = import.meta.url, argv = process.argv) {
+  const entry = argv[1];
+  if (!entry) {
+    return false;
+  }
+  try {
+    // npx may invoke the bin through a symlink. Compare resolved file URLs.
+    const entryPath = realpathSync(entry);
+    const modulePath = realpathSync(fileURLToPath(moduleURL));
+    return pathToFileURL(entryPath).href === pathToFileURL(modulePath).href;
+  } catch {
+    return false;
+  }
+}
+
+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) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function sha256File(file) {
+  const hash = createHash("sha256");
+  hash.update(await readFile(file));
+  return hash.digest("hex");
+}
+
+export async function cachedBinary(
+  dir,
+  release,
+  asset,
+  target,
+  meta = undefined,
+  expectedAssetSha256 = null,
+) {
+  const current = meta === undefined ? await readCacheMeta(dir) : meta;
+  if (
+    !current ||
+    current.tag !== release.tag_name ||
+    current.asset !== asset.name ||
+    (target &&
+      (current.target?.os !== target.os ||
+        current.target?.arch !== target.arch ||
+        current.target?.binaryName !== target.binaryName))
+  ) {
+    return null;
+  }
+
+  const binarySha256 = sha256Digest(current.binarySha256);
+  const assetSha256 = sha256Digest(current.assetSha256);
+  const expectedAssetDigest = expectedAssetSha256 || releaseAssetDigest(asset);
+  if (!binarySha256 || !assetSha256 || (expectedAssetDigest && assetSha256 !== expectedAssetDigest)) {
+    return null;
+  }
+
+  const binary = path.resolve(String(current.binary || ""));
+  if (!pathInside(dir, binary)) {
+    return null;
+  }
+
+  try {
+    const info = await lstat(binary);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      return null;
+    }
+    if ((await sha256File(binary)) !== binarySha256) {
+      return null;
+    }
+    return binary;
+  } catch {
+    return null;
+  }
+}
+
+function getFetch(fetchImpl) {
+  const selected = fetchImpl || globalThis.fetch;
+  if (typeof selected !== "function") {
+    throw new Error("This Node.js runtime does not provide fetch");
+  }
+  return selected;
+}
+
+export async function fetchLatestRelease({
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = RELEASE_TIMEOUT_MS,
+} = {}) {
+  const fetcher = getFetch(fetchImpl);
+  const api = releaseAPI(env);
+  const response = await fetcher(api, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "annas-mcp",
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      `GitHub release request failed (${response.status}) for ${api}: ${body.slice(0, 200)}`,
+    );
+  }
+  const release = await response.json();
+  if (!release?.tag_name || !Array.isArray(release.assets)) {
+    throw new Error(`GitHub release response from ${api} is missing tag_name or assets`);
+  }
+  safePathComponent(release.tag_name, "release tag");
+  return release;
+}
+
+export async function downloadText(
+  url,
+  { fetchImpl = globalThis.fetch, timeoutMs = RELEASE_TIMEOUT_MS } = {},
+) {
+  const response = await getFetch(fetchImpl)(url, {
+    headers: { "User-Agent": "annas-mcp" },
+    signal: AbortSignal.timeout(timeoutMs),
+    redirect: "follow",
+  });
+  if (!response.ok) {
+    throw new Error(`Download failed (${response.status}) for ${url}`);
+  }
+  return response.text();
+}
+
+export async function downloadFile(
+  url,
+  destination,
+  { fetchImpl = globalThis.fetch, timeoutMs = DOWNLOAD_TIMEOUT_MS } = {},
+) {
+  const response = await getFetch(fetchImpl)(url, {
+    headers: { "User-Agent": "annas-mcp" },
+    signal: AbortSignal.timeout(timeoutMs),
+    redirect: "follow",
+  });
+  if (!response.ok || !response.body) {
+    throw new Error(`Download failed (${response.status}) for ${url}`);
+  }
+  await pipeline(Readable.fromWeb(response.body), createWriteStream(destination));
+}
+
+export async function expectedArchiveChecksum(
+  release,
+  asset,
+  { env = process.env, fetchImpl = globalThis.fetch } = {},
+) {
+  const checksumAsset = selectChecksumAsset(release.assets);
+  const checksumText = await downloadText(checksumAsset.browser_download_url, { fetchImpl });
+  const expected = sha256Digest(checksumFor(checksumText, asset.name));
+  if (!expected) {
+    throw new Error(`Invalid checksum for ${asset.name}`);
+  }
+  const advertised = releaseAssetDigest(asset);
+  if (advertised && advertised !== expected) {
+    throw new Error(`Release digest disagrees with checksums for ${asset.name}`);
+  }
+  return expected;
+}
+
+export async function writeCacheMeta(dir, meta) {
+  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"));
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+export async function installBinary(
+  release,
+  asset,
+  target,
+  expectedAssetSha256,
+  {
+    env = process.env,
+    fetchImpl = globalThis.fetch,
+    downloadFileImpl = downloadFile,
+    extractArchiveImpl = extractArchive,
+    findBinaryImpl = findBinary,
+  } = {},
+) {
+  const root = path.resolve(cacheDir(env));
+  const releaseTag = safePathComponent(release.tag_name, "release tag");
+  const assetName = safePathComponent(asset.name, "release asset name");
+  const expected = sha256Digest(expectedAssetSha256);
+  if (!expected) {
+    throw new Error(`Invalid checksum for ${assetName}`);
+  }
+  await mkdir(root, { recursive: true });
+  const work = await mkdtemp(path.join(root, ".tmp-"));
+  const archivePath = path.join(work, assetName);
+  try {
+    await downloadFileImpl(asset.browser_download_url, archivePath, { fetchImpl });
+    const actual = await sha256File(archivePath);
+    if (actual !== expected) {
+      throw new Error(`Checksum mismatch for ${assetName}`);
+    }
+    const extracted = path.join(work, "extracted");
+    await mkdir(extracted);
+    extractArchiveImpl(archivePath, extracted, target.extension);
+    const found = await findBinaryImpl(extracted, target.binaryName);
+    if (!found) {
+      throw new Error(`Archive ${assetName} does not contain ${target.binaryName}`);
+    }
+    const binarySha256 = await sha256File(found);
+    const binaryDir = path.join(root, "versions", releaseTag);
+    await mkdir(binaryDir, { recursive: true });
+    const binaryPath = path.join(binaryDir, `${actual}-${target.binaryName}`);
+    const temporary = `${binaryPath}.${process.pid}.${randomUUID()}.tmp`;
+    await copyFile(found, temporary);
+    await chmod(temporary, 0o755);
+    try {
+      await rename(temporary, binaryPath);
+    } catch (error) {
+      if (!["EEXIST", "EPERM"].includes(error.code)) {
+        throw error;
+      }
+      if ((await sha256File(binaryPath)) !== binarySha256) {
+        throw error;
+      }
+      await rm(temporary, { force: true });
+    }
+    const meta = {
+      tag: releaseTag,
+      asset: assetName,
+      assetSha256: actual,
+      binarySha256,
+      binary: binaryPath,
+      target: {
+        os: target.os,
+        arch: target.arch,
+        binaryName: target.binaryName,
+      },
+    };
+    await writeCacheMeta(root, meta);
+    return binaryPath;
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+export async function resolveBinary(
+  target,
+  {
+    env = process.env,
+    fetchImpl = globalThis.fetch,
+    installBinaryImpl = installBinary,
+  } = {},
+) {
+  const dir = path.resolve(cacheDir(env));
+  const current = await readCacheMeta(dir);
+  let cached = null;
+  if (current) {
+    cached = await cachedBinary(
+      dir,
+      { tag_name: current.tag },
+      { name: current.asset },
+      target,
+      current,
+    );
+  }
+  try {
+    const release = await fetchLatestRelease({ env, fetchImpl });
+    const asset = selectAsset(release.assets, target);
+    const expectedAssetSha256 = await expectedArchiveChecksum(release, asset, { env, fetchImpl });
+    const currentRelease = await cachedBinary(
+      dir,
+      release,
+      asset,
+      target,
+      undefined,
+      expectedAssetSha256,
+    );
+    if (currentRelease) {
+      return currentRelease;
+    }
+    return await installBinaryImpl(release, asset, target, expectedAssetSha256, {
+      env,
+      fetchImpl,
+    });
+  } catch (error) {
+    if (cached) {
+      console.error(`annas-mcp: update check failed, using the cached binary. ${error.message}`);
+      return cached;
+    }
+    throw error;
+  }
+}
+
+export function runBinary(binary, args, { spawnImpl = defaultSpawn, processRef = process } = {}) {
+  const child = spawnImpl(binary, args, { stdio: "inherit" });
+  child.on("error", (error) => {
+    console.error(error.message);
+    processRef.exit(1);
+  });
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    processRef.on(signal, () => {
+      child.kill(signal);
+    });
+  }
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      processRef.exit(1);
+    }
+    processRef.exit(code ?? 1);
+  });
+  return child;
+}
+
+export async function main({ argv = process.argv.slice(2), env = process.env } = {}) {
+  const target = goreleaserTarget();
+  const commandArgs = argv.length === 0 ? ["mcp"] : argv;
+  const binary = await resolveBinary(target, { env });
+  return runBinary(binary, commandArgs);
+}

package/lib/target.js

@@ -0,0 +1,116 @@
+import path from "node:path";
+
+const SUPPORTED_TARGETS = new Set([
+  "darwin-amd64",
+  "darwin-arm64",
+  "linux-amd64",
+  "linux-arm64",
+  "linux-arm",
+  "windows-amd64",
+  "windows-arm64",
+  "freebsd-amd64",
+]);
+
+export function goreleaserTarget(platform = process.platform, arch = process.arch) {
+  const osName = platform === "win32" ? "windows" : platform;
+  const archName = arch === "x64" ? "amd64" : arch;
+  const key = `${osName}-${archName}`;
+  if (!SUPPORTED_TARGETS.has(key)) {
+    throw new Error(
+      `Unsupported platform ${platform}/${arch}. Supported targets: ${[...SUPPORTED_TARGETS].join(", ")}`,
+    );
+  }
+  return {
+    os: osName,
+    arch: archName,
+    extension: osName === "windows" ? "zip" : "tar.xz",
+    binaryName: osName === "windows" ? "annas-mcp.exe" : "annas-mcp",
+  };
+}
+
+export function safePathComponent(value, label) {
+  if (
+    typeof value !== "string" ||
+    !value ||
+    value === "." ||
+    value === ".." ||
+    value.includes("\0") ||
+    value.includes("/") ||
+    value.includes("\\") ||
+    /[<>:"|?*]/.test(value) ||
+    path.basename(value) !== value
+  ) {
+    throw new Error(`Invalid ${label}`);
+  }
+  return value;
+}
+
+export function sha256Digest(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const match = value.trim().match(/^(?:sha256:)?([a-fA-F0-9]{64})$/);
+  return match ? match[1].toLowerCase() : null;
+}
+
+export function releaseAssetDigest(asset) {
+  return sha256Digest(asset?.digest);
+}
+
+export function pathInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+export function validateDownloadAsset(asset) {
+  safePathComponent(asset?.name, "release asset name");
+  if (typeof asset?.browser_download_url !== "string" || !asset.browser_download_url) {
+    throw new Error(`Release asset ${asset?.name || "(unnamed)"} has no download URL`);
+  }
+  return asset;
+}
+
+export function selectChecksumAsset(assets) {
+  const matches = (assets || []).filter(
+    (asset) => typeof asset?.name === "string" && asset.name.endsWith("--checksums.txt"),
+  );
+  if (matches.length !== 1) {
+    const names = (assets || []).map((asset) => asset?.name).filter(Boolean);
+    throw new Error(
+      `Expected one checksums asset, found ${matches.length}. Assets: ${names.join(", ") || "(none)"}`,
+    );
+  }
+  return validateDownloadAsset(matches[0]);
+}
+
+export function checksumFor(text, filename) {
+  const base = path.basename(filename);
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.trim().match(/^([a-fA-F0-9]{64})\s+\*?(.+)$/);
+    if (!match) {
+      continue;
+    }
+    const name = match[2].trim();
+    if (name === filename || name === base || path.basename(name) === base) {
+      return match[1].toLowerCase();
+    }
+  }
+  throw new Error(`Checksum file has no entry for ${filename}`);
+}
+
+export function selectAsset(assets, target) {
+  const suffix = `_${target.os}_${target.arch}.${target.extension}`;
+  const matches = (assets || []).filter(
+    (asset) =>
+      typeof asset?.name === "string" &&
+      asset.name.startsWith("annas-mcp_") &&
+      asset.name.endsWith(suffix),
+  );
+  if (matches.length !== 1) {
+    const names = (assets || []).map((asset) => asset?.name).filter(Boolean);
+    throw new Error(
+      `Expected one release asset ending in ${suffix}, found ${matches.length}. Assets: ${names.join(", ") || "(none)"}`,
+    );
+  }
+  return validateDownloadAsset(matches[0]);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "annas-mcp",
+  "version": "0.1.1",
+  "license": "MIT",
+  "description": "MCP server and CLI for searching and downloading books and articles from Anna's Archive",
+  "mcpName": "io.github.SokolskyNikita/annas-mcp",
+  "author": "Nikita Sokolsky",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "annas-archive",
+    "books",
+    "papers",
+    "doi",
+    "claude",
+    "cursor",
+    "codex"
+  ],
+  "homepage": "https://github.com/SokolskyNikita/annas-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/SokolskyNikita/annas-mcp/issues"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node --test scripts/check-version.test.mjs scripts/release-metadata.test.mjs && node scripts/test-npx-launcher.mjs",
+    "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"
+  },
+  "bin": {
+    "annas-mcp": "bin/annas-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SokolskyNikita/annas-mcp.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}