@imagin.studio/api-docs-mcp 0.1.12

package/README.md

@@ -0,0 +1,71 @@
+# IMAGIN.studio API Docs MCP Server
+
+Semantic search over [IMAGIN.studio](https://www.imaginstudio.com/)
+[documentation](https://docs.imagin.studio/) — CDN, API, integration guides, and more.
+
+This is a thin **npx wrapper** that finds `uvx` on your system and launches
+the Python MCP server. It solves the common problem of GUI apps (Claude
+Desktop, Cursor, etc.) not finding `uvx` in PATH.
+
+## Dependency note — `fastembed-imagin`
+
+This package depends on `fastembed-imagin`, a temporary fork of
+[`fastembed`](https://github.com/qdrant/fastembed) by Qdrant.
+
+**Why:** upstream fastembed 0.7.4 pins `pillow<12.0`, which blocks
+Pillow 12.x security fixes (CVE-2026-25990). The fix PR
+([#599](https://github.com/qdrant/fastembed/pull/599)) is open but
+unreleased.
+
+**What changed:** only the pillow version constraint — relaxed from
+`<12.0` to `<13.0` for Python 3.10+. No logic changes. Source:
+[IMAGIN-studio/fastembed-imagin](https://github.com/IMAGIN-studio/fastembed-imagin).
+
+**Revert plan:** once upstream releases fastembed 0.7.5+ with the
+pillow fix, this package will switch back to `fastembed` and
+`fastembed-imagin` will be retired.
+
+## Prerequisites
+
+- **Node.js 18+** (for npx)
+- **uv** — install from [astral.sh/uv](https://docs.astral.sh/uv/):
+  ```sh
+  curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
+  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows
+  ```
+
+## Usage
+
+```sh
+npx -y @imagin.studio/api-docs-mcp
+```
+
+Or in your agent's MCP config:
+
+```json
+{
+  "imagin-docs": {
+    "command": "npx",
+    "args": ["-y", "@imagin.studio/api-docs-mcp"]
+  }
+}
+```
+
+## Full setup guide
+
+For step-by-step instructions for 7 coding agents (Claude Code, Claude
+Desktop, Cursor, Windsurf, VS Code + Copilot, Cline, Zed), see the full
+setup guide on PyPI:
+
+**https://pypi.org/project/imagin-studio-api-docs-mcp/**
+
+## How it works
+
+The npx wrapper probes common `uvx` install locations (`~/.local/bin`,
+Homebrew, cargo) and spawns `uvx imagin-studio-api-docs-mcp`, which downloads and
+runs the Python MCP server. On first run, the server clones the docs and
+builds a local vector index (~20-30 seconds).
+
+## License
+
+Proprietary — see [LICENSE](https://github.com/IMAGIN-studio/api-docs-mcp/blob/main/LICENSE).

package/bin/imagin-studio-api-docs-mcp.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// Thin wrapper that finds uvx and spawns the imagin-studio-api-docs-mcp Python server.
+// Used by: npx imagin-studio-api-docs-mcp, Claude Desktop config, .mcpb bundles.
+//
+// Why Node.js? GUI apps (Claude Desktop, Cursor, etc.) don't inherit shell
+// PATH, so bare "uvx" fails with ENOENT. This script probes common install
+// locations before falling back to PATH lookup.
+
+"use strict";
+
+const { spawn, execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+// -- Configuration -----------------------------------------------------------
+
+const PACKAGE = "imagin-studio-api-docs-mcp";
+
+const UVX_ARGS = [PACKAGE];
+
+// -- Find uvx ----------------------------------------------------------------
+
+function findUvx() {
+  const home = os.homedir();
+  const isWin = process.platform === "win32";
+  const bin = isWin ? "uvx.exe" : "uvx";
+
+  // Common install locations (ordered by likelihood)
+  const candidates = [
+    path.join(home, ".local", "bin", bin),       // default uv install (Linux/macOS)
+    path.join(home, ".cargo", "bin", bin),        // cargo install uv
+    "/opt/homebrew/bin/uvx",                      // Homebrew on Apple Silicon
+    "/usr/local/bin/uvx",                         // Homebrew on Intel / manual symlink
+  ];
+
+  if (isWin) {
+    const localAppData = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+    candidates.unshift(path.join(localAppData, "uv", "bin", "uvx.exe"));
+  }
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  // Fall back to PATH lookup — works when launched from a terminal
+  try {
+    const cmd = isWin ? "where" : "which";
+    const result = execFileSync(cmd, [bin], { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] });
+    const resolved = result.trim().split("\n")[0];
+    if (resolved && fs.existsSync(resolved)) {
+      return resolved;
+    }
+  } catch {
+    // which/where failed — uvx not in PATH
+  }
+
+  return null;
+}
+
+// -- Main --------------------------------------------------------------------
+
+const uvx = findUvx();
+
+if (!uvx) {
+  // Write to stderr only — stdout is reserved for MCP JSON-RPC
+  process.stderr.write(
+    `Error: uvx not found.\n\n` +
+    `The imagin-studio-api-docs-mcp server requires uv (https://docs.astral.sh/uv/).\n\n` +
+    `Install uv:\n` +
+    `  macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh\n` +
+    `  Windows:     powershell -c "irm https://astral.sh/uv/install.ps1 | iex"\n` +
+    `  Homebrew:    brew install uv\n`
+  );
+  process.exit(1);
+}
+
+const child = spawn(uvx, UVX_ARGS, {
+  stdio: "inherit",
+  env: { ...process.env },
+});
+
+// Forward signals to the child process
+process.on("SIGINT", () => child.kill("SIGINT"));
+process.on("SIGTERM", () => child.kill("SIGTERM"));
+
+// Propagate exit code
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 1);
+  }
+});
+
+child.on("error", (err) => {
+  process.stderr.write(`Failed to start uvx: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@imagin.studio/api-docs-mcp",
+  "version": "0.1.12",
+  "description": "IMAGIN.studio documentation search — MCP server (npx wrapper)",
+  "bin": {
+    "imagin-studio-api-docs-mcp": "bin/imagin-studio-api-docs-mcp.js"
+  },
+  "files": [
+    "bin/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": {
+    "name": "IMAGIN.studio",
+    "email": "service@imagin.studio",
+    "url": "https://imagin.studio"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IMAGIN-studio/api-docs-mcp"
+  },
+  "keywords": [
+    "mcp",
+    "imagin",
+    "documentation",
+    "search",
+    "rag",
+    "model-context-protocol"
+  ]
+}