shadowjoin 0.3.0 → 0.3.2

package/README.md

@@ -17,11 +17,11 @@ npx shadowjoin scan \
   --right crm_export.csv  --right-key account_name
 ```
 
-[![shadowjoin measuring a country-name join: 205 of 249 matched exactly, which looks fine, while five real matches were being dropped including Vietnam, spelled Viet Nam by the UN](assets/brag.gif)](https://github.com/harsh-chandak/shadowjoin/blob/main/assets/brag.mp4)
+[![shadowjoin measuring a country-name join: 205 of 249 matched exactly, which looks fine, while five real matches were being dropped including Vietnam, spelled Viet Nam by the UN](assets/brag.gif)](https://github.com/harsh-chandak/shadowjoin/blob/main/assets/brag.gif)
 
 <sub>Fourteen seconds, no sound. Every figure in it is verbatim CLI output from
 the committed example below — [higher-resolution
-version](https://github.com/harsh-chandak/shadowjoin/blob/main/assets/brag.mp4).</sub>
+version](https://github.com/harsh-chandak/shadowjoin/blob/main/assets/brag.gif).</sub>
 
 The progress output above is real: shadowjoin shows what it is doing while it
 works. All of it is suppressed automatically when stdout is not a terminal, so
@@ -219,6 +219,19 @@ const key = (value) => normalize(value, rules);
 toSql("company_name", rules);                     // the same thing as Postgres SQL
 ```
 
+### Claude Code plugin (easiest)
+
+One command installs the skill and the MCP server together, and prompts for your
+config path:
+
+```bash
+claude plugin marketplace add harsh-chandak/shadowjoin
+claude plugin install shadowjoin@harsh-chandak
+```
+
+Also listed in the [official MCP registry](https://registry.modelcontextprotocol.io)
+as `io.github.harsh-chandak/shadowjoin`.
+
 ### MCP server
 
 Lets an agent measure a join, look at real examples, propose a fix, and then
@@ -230,7 +243,7 @@ not something it writes.
   "mcpServers": {
     "shadowjoin": {
       "command": "npx",
-      "args": ["-y", "-p", "shadowjoin", "shadowjoin-mcp"],
+      "args": ["-y", "-p", "shadowjoin", "-p", "@modelcontextprotocol/sdk", "shadowjoin-mcp"],
       "env": { "SHADOWJOIN_CONFIG": "/abs/path/to/shadowjoin.config.json" }
     }
   }

package/dist/mcp.js

@@ -11,14 +11,42 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { randomUUID } from "node:crypto";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { createRequire } from "node:module";
 import { scan } from "./scan.js";
 import { ALL_RULE_IDS, rulesByIds, toSql } from "./normalize.js";
 import { rowsFromCsv } from "./adapters/csv.js";
 import { rowsFromJson } from "./adapters/json.js";
-const CONFIG_PATH = resolve(process.env.SHADOWJOIN_CONFIG ?? "shadowjoin.config.json");
+const VERSION = createRequire(import.meta.url)("../package.json").version;
+/**
+ * The SDK is an optional peer, so the core library and CLI stay dependency-free.
+ * Import it dynamically to turn a missing install into an instruction rather
+ * than a module-resolution stack trace, which is what an MCP client shows the
+ * user as nothing more than "Connection closed".
+ */
+async function loadSdk() {
+    try {
+        const [{ Server }, { StdioServerTransport }, types] = await Promise.all([
+            import("@modelcontextprotocol/sdk/server/index.js"),
+            import("@modelcontextprotocol/sdk/server/stdio.js"),
+            import("@modelcontextprotocol/sdk/types.js"),
+        ]);
+        return { Server, StdioServerTransport, ...types };
+    }
+    catch {
+        process.stderr.write("shadowjoin-mcp needs @modelcontextprotocol/sdk, which is an optional peer dependency.\n" +
+            "Run it with the SDK provided:\n" +
+            "  npx -y -p shadowjoin -p @modelcontextprotocol/sdk shadowjoin-mcp\n" +
+            "or install it alongside shadowjoin:\n" +
+            "  npm i shadowjoin @modelcontextprotocol/sdk\n");
+        process.exit(1);
+    }
+}
+// `||`, not `??`: the Claude Code plugin maps this to a user setting, and an
+// unset setting arrives as an empty string rather than as undefined. `??`
+// let "" through, and resolve("") is the working DIRECTORY — so the default
+// install read a directory as its config and told the user to create a file
+// at a path that was already a folder.
+const CONFIG_PATH = resolve(process.env.SHADOWJOIN_CONFIG?.trim() || "shadowjoin.config.json");
 async function loadConfig() {
     try {
         const parsed = JSON.parse(await readFile(CONFIG_PATH, "utf8"));
@@ -133,7 +161,8 @@ const TOOLS = [
         },
     },
 ];
-const server = new Server({ name: "shadowjoin", version: "0.1.0" }, { capabilities: { tools: {} } });
+const { Server, StdioServerTransport, CallToolRequestSchema, ListToolsRequestSchema } = await loadSdk();
+const server = new Server({ name: "shadowjoin", version: VERSION }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name } = request.params;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadowjoin",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Measure the matches your exact join is silently dropping. Runs a shadow matcher alongside your real join key and reports a verified floor on lost matches, plus the normalization rule that would recover each one.",
   "keywords": [
     "entity-resolution",
@@ -45,7 +45,7 @@
   "scripts": {
     "build": "tsc",
     "test": "node --test test/*.test.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "node scripts/prepublish-guard.mjs && npm run build && npm test"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1",