mcp-server-markview 1.1.3

package/README.md

@@ -0,0 +1,115 @@
+# mcp-server-markview
+
+MCP (Model Context Protocol) server for [MarkView](https://github.com/paulhkang94/markview) — a native macOS Markdown previewer.
+
+Lets AI assistants (Claude, etc.) preview Markdown files and open them in the MarkView app directly from the conversation.
+
+## Requirements
+
+- macOS (arm64 or x86_64)
+- Node.js 18+
+- MarkView.app (auto-fetched on install, or install manually from [Releases](https://github.com/paulhkang94/markview/releases))
+
+## Quick Start
+
+Run without installing:
+
+```bash
+npx mcp-server-markview
+```
+
+Or install globally:
+
+```bash
+npm install -g mcp-server-markview
+mcp-server-markview
+```
+
+The binary is downloaded automatically during installation. If the download fails (e.g. offline install), the wrapper falls back to a locally installed MarkView.app at `/Applications` or `~/Applications`.
+
+## Claude Code Configuration
+
+Add to your Claude Code MCP config (usually `~/.claude/mcp.json` or via `claude mcp add`):
+
+```json
+{
+  "mcpServers": {
+    "markview": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-markview"]
+    }
+  }
+}
+```
+
+Or if you have installed it globally:
+
+```json
+{
+  "mcpServers": {
+    "markview": {
+      "command": "mcp-server-markview"
+    }
+  }
+}
+```
+
+### Using `claude mcp add`
+
+```bash
+claude mcp add markview -- npx -y mcp-server-markview
+```
+
+## Available Tools
+
+### `preview_markdown`
+
+Renders a Markdown string and opens a live preview in MarkView.
+
+| Parameter | Type   | Description                     |
+|-----------|--------|---------------------------------|
+| `content` | string | Markdown source text to preview |
+| `title`   | string | Optional window title           |
+
+### `open_file`
+
+Opens a Markdown file from disk in MarkView.
+
+| Parameter | Type   | Description                          |
+|-----------|--------|--------------------------------------|
+| `path`    | string | Absolute path to the `.md` file      |
+
+## Transport
+
+The server uses **stdio transport** (JSON-RPC 2.0 over stdin/stdout), which is the standard MCP transport and compatible with all MCP clients.
+
+## How It Works
+
+1. `npm install` runs `scripts/postinstall.js`, which downloads the prebuilt `MarkView` release archive from GitHub and extracts the `markview-mcp-server` binary.
+2. The binary is placed at `bin/markview-mcp-server-binary` inside the package.
+3. `bin/mcp-server-markview` (the shell wrapper registered in `bin`) locates the binary and `exec`s it, preserving stdio.
+
+## Troubleshooting
+
+**Binary not found after install**
+
+Re-run the postinstall script manually:
+
+```bash
+node "$(npm root -g)/mcp-server-markview/scripts/postinstall.js"
+```
+
+**Download failed (corporate proxy / offline)**
+
+Install MarkView.app manually from the [Releases page](https://github.com/paulhkang94/markview/releases) and place it in `/Applications`. The wrapper will find it automatically.
+
+**Permission denied**
+
+```bash
+chmod +x "$(npm root -g)/mcp-server-markview/bin/markview-mcp-server-binary"
+chmod +x "$(npm root -g)/mcp-server-markview/bin/mcp-server-markview"
+```
+
+## License
+
+MIT — see [LICENSE](https://github.com/paulhkang94/markview/blob/main/LICENSE).

package/bin/mcp-server-markview

@@ -0,0 +1,70 @@
+#!/bin/sh
+# mcp-server-markview
+#
+# Shell wrapper that locates the MarkView MCP server binary and exec's it,
+# passing through all arguments and preserving stdio (required for JSON-RPC
+# over stdio transport).
+#
+# Resolution order:
+#   1. Downloaded binary next to this script (placed by postinstall.js)
+#   2. MarkView.app installed at /Applications (system install)
+#   3. MarkView.app installed in ~/Applications (user install)
+
+set -e
+
+# Resolve the real directory of this script, following symlinks.
+# This is important when the script is invoked via `npx` which may symlink bin/.
+resolve_dir() {
+  local target="$1"
+  # Loop until target is not a symlink.
+  while [ -L "$target" ]; do
+    local link
+    link="$(readlink "$target")"
+    case "$link" in
+      /*) target="$link" ;;
+      *)  target="$(dirname "$target")/$link" ;;
+    esac
+  done
+  dirname "$target"
+}
+
+SCRIPT_DIR="$(resolve_dir "$0")"
+
+# --- Candidate 1: binary downloaded by postinstall ---
+DOWNLOADED_BINARY="$SCRIPT_DIR/markview-mcp-server-binary"
+
+if [ -x "$DOWNLOADED_BINARY" ]; then
+  exec "$DOWNLOADED_BINARY" "$@"
+fi
+
+# --- Candidate 2: /Applications (system-wide install) ---
+SYSTEM_APP_BINARY="/Applications/MarkView.app/Contents/MacOS/markview-mcp-server"
+
+if [ -x "$SYSTEM_APP_BINARY" ]; then
+  exec "$SYSTEM_APP_BINARY" "$@"
+fi
+
+# --- Candidate 3: ~/Applications (user install) ---
+USER_APP_BINARY="$HOME/Applications/MarkView.app/Contents/MacOS/markview-mcp-server"
+
+if [ -x "$USER_APP_BINARY" ]; then
+  exec "$USER_APP_BINARY" "$@"
+fi
+
+# --- Not found ---
+cat >&2 <<'EOF'
+mcp-server-markview: could not find the MarkView MCP server binary.
+
+To fix this, try one of the following:
+
+  1. Re-run postinstall to download the binary:
+       node "$(npm root -g)/mcp-server-markview/scripts/postinstall.js"
+
+  2. Install MarkView.app from:
+       https://github.com/paulhkang94/markview/releases
+
+  3. If postinstall failed during `npm install`, re-install the package:
+       npm install -g mcp-server-markview
+
+EOF
+exit 1

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "mcp-server-markview",
+  "version": "1.1.3",
+  "description": "MCP server for MarkView — preview Markdown files in a native macOS viewer",
+  "license": "MIT",
+  "author": "Paul Kang <contact@paulkang.dev>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paulhkang94/markview.git",
+    "directory": "npm"
+  },
+  "homepage": "https://github.com/paulhkang94/markview#readme",
+  "bugs": {
+    "url": "https://github.com/paulhkang94/markview/issues"
+  },
+  "bin": {
+    "mcp-server-markview": "bin/mcp-server-markview"
+  },
+  "mcpName": "io.github.paulhkang94/markview",
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "markdown",
+    "markview",
+    "preview",
+    "macos",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js
+ *
+ * Downloads the MarkView MCP server binary from GitHub Releases and places it
+ * at ./bin/markview-mcp-server-binary so the shell wrapper can find it.
+ *
+ * Uses only Node.js built-ins — zero runtime dependencies.
+ */
+
+"use strict";
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execFileSync } = require("child_process");
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const GITHUB_OWNER = "paulhkang94";
+const GITHUB_REPO = "markview";
+const VERSION = "1.1.3";
+const ARCHIVE_NAME = `MarkView-${VERSION}.tar.gz`;
+const DOWNLOAD_URL = `https://github.com/${GITHUB_OWNER}/${GITHUB_REPO}/releases/download/v${VERSION}/${ARCHIVE_NAME}`;
+
+// Path inside the tar.gz where the MCP server binary lives
+const BINARY_IN_ARCHIVE = `MarkView.app/Contents/MacOS/markview-mcp-server`;
+
+// Destination: placed next to the shell wrapper in bin/
+const PKG_ROOT = path.resolve(__dirname, "..");
+const DEST_BINARY = path.join(PKG_ROOT, "bin", "markview-mcp-server-binary");
+
+// ---------------------------------------------------------------------------
+// Platform guard
+// ---------------------------------------------------------------------------
+
+if (process.platform !== "darwin") {
+  console.error(
+    "[mcp-server-markview] MarkView is a macOS-only application. " +
+      "This package is not supported on " +
+      process.platform +
+      ".",
+  );
+  // Exit 0 so npm install does not fail on non-macOS CI environments.
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Follow HTTP redirects and return a Promise that resolves with the final
+ * IncomingMessage once we land on a non-redirect response.
+ */
+function followRedirects(url, maxRedirects) {
+  maxRedirects = maxRedirects === undefined ? 10 : maxRedirects;
+
+  return new Promise((resolve, reject) => {
+    if (maxRedirects === 0) {
+      return reject(new Error("Too many redirects"));
+    }
+
+    https
+      .get(
+        url,
+        { headers: { "User-Agent": "mcp-server-markview-postinstall" } },
+        (res) => {
+          if (
+            res.statusCode >= 300 &&
+            res.statusCode < 400 &&
+            res.headers.location
+          ) {
+            res.resume(); // drain the response body so the socket is freed
+            resolve(followRedirects(res.headers.location, maxRedirects - 1));
+          } else {
+            resolve(res);
+          }
+        },
+      )
+      .on("error", reject);
+  });
+}
+
+/**
+ * Download a URL to a local file. Returns a Promise.
+ */
+function downloadFile(url, destPath) {
+  return new Promise((resolve, reject) => {
+    followRedirects(url)
+      .then((res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode} downloading ${url}`));
+        }
+
+        const total = parseInt(res.headers["content-length"] || "0", 10);
+        let received = 0;
+        let lastPct = -1;
+
+        const out = fs.createWriteStream(destPath);
+
+        res.on("data", (chunk) => {
+          received += chunk.length;
+          if (total > 0) {
+            const pct = Math.floor((received / total) * 100);
+            if (pct !== lastPct && pct % 10 === 0) {
+              process.stdout.write(`\r  ${pct}%`);
+              lastPct = pct;
+            }
+          }
+        });
+
+        res.pipe(out);
+
+        out.on("finish", () => {
+          process.stdout.write("\r       \r"); // clear progress line
+          resolve();
+        });
+
+        out.on("error", reject);
+        res.on("error", reject);
+      })
+      .catch(reject);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  // Skip if the binary is already present (e.g. re-running postinstall).
+  if (fs.existsSync(DEST_BINARY)) {
+    console.log(
+      "[mcp-server-markview] Binary already present, skipping download.",
+    );
+    return;
+  }
+
+  // Ensure the bin/ directory exists (it should, since it ships with the package).
+  fs.mkdirSync(path.dirname(DEST_BINARY), { recursive: true });
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-server-markview-"));
+  const archivePath = path.join(tmpDir, ARCHIVE_NAME);
+
+  try {
+    console.log(`[mcp-server-markview] Downloading MarkView v${VERSION}...`);
+    console.log(`  ${DOWNLOAD_URL}`);
+
+    await downloadFile(DOWNLOAD_URL, archivePath);
+
+    console.log("[mcp-server-markview] Extracting MCP server binary...");
+
+    // Extract only the MCP server binary from the archive.
+    // Path is MarkView.app/Contents/MacOS/markview-mcp-server (3 dirs deep).
+    execFileSync(
+      "tar",
+      [
+        "-xzf",
+        archivePath,
+        "--strip-components=3",
+        "-C",
+        path.dirname(DEST_BINARY),
+        BINARY_IN_ARCHIVE,
+      ],
+      { stdio: "pipe" },
+    );
+
+    // The extracted file will be named "markview-mcp-server"; rename if needed.
+    const extractedName = path.join(
+      path.dirname(DEST_BINARY),
+      "markview-mcp-server",
+    );
+    if (fs.existsSync(extractedName) && extractedName !== DEST_BINARY) {
+      fs.renameSync(extractedName, DEST_BINARY);
+    }
+
+    // Make executable.
+    fs.chmodSync(DEST_BINARY, 0o755);
+
+    console.log("[mcp-server-markview] Binary installed successfully.");
+    console.log(`  Location: ${DEST_BINARY}`);
+  } catch (err) {
+    console.error("[mcp-server-markview] Installation failed:", err.message);
+    console.error(
+      "\nYou can still use MarkView's MCP server if MarkView.app is installed at /Applications.\n" +
+        "Run `npx mcp-server-markview` and the wrapper will fall back to the app bundle automatically.",
+    );
+    // Exit 0 — a postinstall failure should not block npm install entirely.
+    process.exit(0);
+  } finally {
+    // Clean up temp directory.
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch (_) {
+      // Ignore cleanup errors.
+    }
+  }
+}
+
+main();