obscura-mcp-server 0.1.0 → 0.1.2

package/INSTALL.md

@@ -6,14 +6,14 @@ This guide covers how to configure the Obscura MCP server with various AI client
 
 ### Method 1: Using bunx (recommended - no installation needed)
 
-Once published to npm (coming soon):
+Once published to npm:
 
 ```json
 {
   "mcpServers": {
     "obscura": {
       "command": "bunx",
-      "args": ["obscura-mcp-server"]
+      "args": ["-y", "obscura-mcp-server"]
     }
   }
 }
@@ -89,7 +89,7 @@ bun install
     "servers": {
       "obscura": {
         "command": "bunx",
-        "args": ["obscura-mcp-server"]
+        "args": ["-y", "obscura-mcp-server"]
       }
     }
   }
@@ -114,7 +114,7 @@ Restart VSCode after editing.
     "obscura": {
       "type": "stdio",
       "command": "bunx",
-      "args": ["obscura-mcp-server"]
+      "args": ["-y", "obscura-mcp-server"]
     }
   }
 }
@@ -150,7 +150,7 @@ Cursor also supports UI configuration: Settings → Features → Model Context P
   "mcp": {
     "obscura": {
       "type": "local",
-      "command": ["bunx", "obscura-mcp-server"],
+      "command": ["bunx", "-y", "obscura-mcp-server"],
       "environment": {
         "OBSCURA_PATH": "/usr/local/bin/obscura"
       },
@@ -175,7 +175,7 @@ Cursor also supports UI configuration: Settings → Features → Model Context P
   "mcpServers": {
     "obscura": {
       "command": "bunx",
-      "args": ["obscura-mcp-server"]
+      "args": ["-y", "obscura-mcp-server"]
     }
   }
 }
@@ -202,7 +202,7 @@ claude mcp list
   "mcpServers": {
     "obscura": {
       "command": "bunx",
-      "args": ["obscura-mcp-server"]
+      "args": ["-y", "obscura-mcp-server"]
     }
   }
 }
@@ -227,7 +227,7 @@ Then configure the adapter to point to the Obscura MCP server:
   "mcpServers": {
     "obscura": {
       "command": "bunx",
-      "args": ["obscura-mcp-server"]
+      "args": ["-y", "obscura-mcp-server"]
     }
   }
 }

package/README.md

@@ -40,34 +40,47 @@ Query a webpage using CSS selectors or text search.
 
 ## Installation
 
+Add to your MCP servers config:
+
+```json
+{
+  "mcpServers": {
+    "obscura": {
+      "command": "bunx",
+      "args": ["-y", "obscura-mcp-server"]
+    }
+  }
+}
+```
+
 See [INSTALL.md](./INSTALL.md) for setup with VSCode, Cursor, OpenCode, Claude Code, Codex, and Pi.
 
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                      MCP Client                             │
-│                    (Claude Desktop)                          │
+│                        MCP Client                           │
+│                       Coding Agent                          │
 └─────────────────────────┬───────────────────────────────────┘
                           │ JSON-RPC
                           ▼
 ┌─────────────────────────────────────────────────────────────┐
-│                   Obscura MCP Server                         │
-│  ┌─────────┐  ┌─────────┐  ┌─────────┐                      │
-│  │  fetch  │  │ search  │  │  query  │  ← Tools            │
-│  └───┬─────┘  └───┬─────┘  └───┬─────┘                     │
-│      │            │            │                            │
-│      ▼            ▼            ▼                            │
+│                   Obscura MCP Server                        │
+│        ┌─────────┐   ┌─────────┐   ┌─────────┐              │
+│        │  fetch  │   │ search  │   │  query  │  ← Tools     │
+│        └───┬─────┘   └───┬─────┘   └───┬─────┘              │
+│            │             │             │                    │
+│            ▼             ▼             ▼                    │
 │  ┌─────────────────────────────────────────────────────────┐│
-│  │              checkObscura()                             ││
-│  └────────────────────┬────────────────────────────────────┘│
-│                       │                                      │
-│          ┌────────────┴────────────┐                        │
-│          ▼                         ▼                        │
-│   ┌────────────┐           ┌────────────┐                   │
-│   │  Obscura   │           │   Native   │                   │
-│   │ (headless) │           │   fetch    │                   │
-│   └────────────┘           └────────────┘                   │
+│  │                     checkObscura()                      ││
+│  └──────────────────────────┬──────────────────────────────┘│
+│                             │                               │
+│                ┌────────────┴────────────┐                  │
+│                ▼                         ▼                  │
+│         ┌────────────┐           ┌────────────┐             │
+│         │  Obscura   │           │   Native   │             │
+│.        │ (headless) │           │   fetch    │             │
+│         └────────────┘           └────────────┘             │
 └─────────────────────────────────────────────────────────────┘
 ```
 

package/bun.lock

@@ -15,6 +15,7 @@
         "@biomejs/biome": "^2.4.13",
         "@types/bun": "latest",
         "@types/turndown": "^5.0.6",
+        "lefthook": "^2.1.6",
       },
       "peerDependencies": {
         "typescript": "^6.0.3",
@@ -172,6 +173,28 @@
 
     "json-schema-typed": ["json-schema-typed@8.0.2", "", {}, "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA=="],
 
+    "lefthook": ["lefthook@2.1.6", "", { "optionalDependencies": { "lefthook-darwin-arm64": "2.1.6", "lefthook-darwin-x64": "2.1.6", "lefthook-freebsd-arm64": "2.1.6", "lefthook-freebsd-x64": "2.1.6", "lefthook-linux-arm64": "2.1.6", "lefthook-linux-x64": "2.1.6", "lefthook-openbsd-arm64": "2.1.6", "lefthook-openbsd-x64": "2.1.6", "lefthook-windows-arm64": "2.1.6", "lefthook-windows-x64": "2.1.6" }, "bin": { "lefthook": "bin/index.js" } }, "sha512-w9sBoR0mdN+kJc3SB85VzpiAAl451/rxdCRcZlwW71QLjkeH3EBQFgc4VMj5apePychYDHAlqEWTB8J8JK/j1Q=="],
+
+    "lefthook-darwin-arm64": ["lefthook-darwin-arm64@2.1.6", "", { "os": "darwin", "cpu": "arm64" }, "sha512-hyB7eeiX78BS66f70byTJacDLC/xV1vgMv9n+idFUsrM7J3Udd/ag9Ag5NP3t0eN0EqQqAtrNnt35EH01lxnRQ=="],
+
+    "lefthook-darwin-x64": ["lefthook-darwin-x64@2.1.6", "", { "os": "darwin", "cpu": "x64" }, "sha512-5Ka6cFxiH83krt+OMRQtmS6zqoZR5SLXSudLjTbZA1c3ZqF0+dqkeb4XcB6plx6WR0GFizabuc6Bi3iXPIe1eQ=="],
+
+    "lefthook-freebsd-arm64": ["lefthook-freebsd-arm64@2.1.6", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-VswyOg5CVN3rMaOJ2HtnkltiMKgFHW/wouWxXsV8RxSa4tgWOKxM0EmSXi8qc2jX+LRga6B0uOY6toXS01zWxA=="],
+
+    "lefthook-freebsd-x64": ["lefthook-freebsd-x64@2.1.6", "", { "os": "freebsd", "cpu": "x64" }, "sha512-vXsCUFYuVwrVWwcypB7Zt2Hf+5pl1V1la7ZfvGYZaTRURu0zF/XUnMF/nOz/PebGv0f4x/iOWXWwP7E42xRWsg=="],
+
+    "lefthook-linux-arm64": ["lefthook-linux-arm64@2.1.6", "", { "os": "linux", "cpu": "arm64" }, "sha512-WDJiQhJdZOvKORZd+kF/ms2l6NSsXzdA9ahflyr65V90AC4jES223W8VtEMbGPUtHuGWMEZ/v/XvwlWv0Ioz9g=="],
+
+    "lefthook-linux-x64": ["lefthook-linux-x64@2.1.6", "", { "os": "linux", "cpu": "x64" }, "sha512-C18nCd7nTX1AVL4TcvwMmLAO1VI1OuGluIOTjiPkBQ746Ls1HhL5rl//jMPACmT28YmxIQJ2ZcLPNmhvEVBZvw=="],
+
+    "lefthook-openbsd-arm64": ["lefthook-openbsd-arm64@2.1.6", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-mZOMxM8HiPxVFXDO3PtCUbH4GB8rkveXhsgXF27oAZTYVzQ3gO9vT6r/pxit6msqRXz3fvcwimLVJgb8eRsa8A=="],
+
+    "lefthook-openbsd-x64": ["lefthook-openbsd-x64@2.1.6", "", { "os": "openbsd", "cpu": "x64" }, "sha512-sG9ALLZSnnMOfXu+B7SmxFhJhuoAh4bqi5En5aaHJET48TqrLOcWWZuH+7ArFM6gr/U5KfSUvdmHFmY8WqCcIg=="],
+
+    "lefthook-windows-arm64": ["lefthook-windows-arm64@2.1.6", "", { "os": "win32", "cpu": "arm64" }, "sha512-lD8yFWY4Csuljd0Rqs7EQaySC0VvDf7V3rN1FhRMUISTRDHutebIom1Loc8ckQPvKYGC6mftT9k0GvipsS+Brw=="],
+
+    "lefthook-windows-x64": ["lefthook-windows-x64@2.1.6", "", { "os": "win32", "cpu": "x64" }, "sha512-q4z2n3xucLscoWiyMwFViEj3N8MDSkPulMwcJYuCYFHoPhP1h+icqNu7QRLGYj6AnVrCQweiUJY3Tb2X+GbD/A=="],
+
     "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
 
     "media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],

package/dist/index.js

@@ -52886,7 +52886,7 @@ async function queryWithObscura(url2, options) {
   const allElements = root.querySelectorAll("p, h1, h2, h3, h4, h5, h6, li, a, span, div");
   const allText = allElements.map((el) => el.text.trim()).filter((t) => t.length > 0);
   const fuse = new Fuse(allText, { threshold: 0.3 });
-  const matches = fuse.search(text);
+  const matches = fuse.search(text || "").slice(0, 10);
   return {
     content: [
       {
@@ -53103,7 +53103,7 @@ function registerTools(server) {
 // src/index.ts
 var server = new McpServer({
   name: "obscura-mcp-server",
-  version: "0.1.0"
+  version: "0.1.2"
 });
 registerTools(server);
 var transport = new StdioServerTransport;

package/lefthook.yml

@@ -0,0 +1,11 @@
+pre-commit:
+  commands:
+    lint-fix:
+      run: bun biome check --write {staged_files}
+      glob: "**/*.{ts,tsx,js,jsx,json}"
+
+pre-push:
+  commands:
+    lint-check:
+      run: bun biome check
+      glob: "**/*.{ts,tsx,js,jsx,json}"

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "obscura-mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sthbryan/obscura-mcp-server"
+  },
+  "author": {
+    "name": "sthbryan",
+    "url": "https://justcallmebryan.com"
+  },
   "description": "MCP server for Obscura - web scraping, HTML to Markdown conversion, and URL content processing",
   "main": "./dist/index.js",
   "bin": {
@@ -15,12 +23,14 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "check": "biome check --diagnostic-level=error .",
-    "prepublish": "bun run build"
+    "prepublish": "bun run build",
+    "postinstall": "[ -d .git ] && lefthook install || true"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
     "@types/bun": "latest",
-    "@types/turndown": "^5.0.6"
+    "@types/turndown": "^5.0.6",
+    "lefthook": "^2.1.6"
   },
   "peerDependencies": {
     "typescript": "^6.0.3"

package/src/index.ts

@@ -5,7 +5,7 @@ import { registerTools } from "./tools";
 
 const server = new McpServer({
   name: "obscura-mcp-server",
-  version: "0.1.0",
+  version: "0.1.2",
 });
 
 registerTools(server);

package/src/tools/fetch/index.ts

@@ -40,4 +40,4 @@ export function createFetchHandler() {
       };
     }
   };
-}
+}

package/src/tools/query/fetch.ts

@@ -29,10 +29,7 @@ function findBestSelector(html: string): string {
   return DEFAULT_CONTENT_SELECTORS;
 }
 
-export async function queryWithNative(
-  url: string,
-  options: QueryOptions
-): Promise<CallToolResult> {
+export async function queryWithNative(url: string, options: QueryOptions): Promise<CallToolResult> {
   const { selector, text } = options;
 
   if (!selector && !text) {
@@ -73,11 +70,11 @@ export async function queryWithNative(
 
     const html = await response.text();
     let resolvedSelector = selector;
-    
+
     if (!resolvedSelector) {
       resolvedSelector = text ? DEFAULT_CONTENT_SELECTORS : findBestSelector(html);
     }
-    
+
     const result = parseHtml(html, { selector: resolvedSelector, text });
 
     return {
@@ -137,4 +134,4 @@ function parseHtml(html: string, options: { selector?: string; text?: string }):
   }
 
   return [];
-}
+}

package/src/tools/query/index.ts

@@ -63,4 +63,4 @@ export function createQueryHandler() {
       };
     }
   };
-}
+}

package/src/tools/query/obscura.ts

@@ -1,6 +1,6 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types";
-import { parse } from "node-html-parser";
 import Fuse from "fuse.js";
+import { parse } from "node-html-parser";
 import { execAsync } from "@/utils/exec";
 
 interface QueryOptions {
@@ -79,7 +79,7 @@ export async function queryWithObscura(
   const allText = allElements.map((el) => el.text.trim()).filter((t) => t.length > 0);
 
   const fuse = new Fuse(allText, { threshold: 0.3 });
-  const matches = fuse.search(text!);
+  const matches = fuse.search(text || "").slice(0, 10);
 
   return {
     content: [
@@ -100,4 +100,4 @@ export async function queryWithObscura(
       },
     ],
   };
-}
+}

package/src/tools/search/index.ts

@@ -40,4 +40,4 @@ export function createSearchHandler() {
       };
     }
   };
-}
+}