collimer-mcp - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

LICENSE

+MIT License
+
+Copyright (c) 2026 Sandcastle Labs
+
+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.

dist/index.js

 #!/usr/bin/env node
-// Collimer MCP server (#408) — exposes one tool, `beacon_free_scan`, that runs a
-// free AI-search visibility scan via the public REST API and returns the
-// depth-gated teaser. Never returns the full report (gated behind a free account).
+// Collimer MCP server — exposes `collimer_scan`, which runs a free AI-search
+// visibility scan via the public REST API and returns the depth-gated teaser.
+// Never returns the full report (gated behind a free account).
+// `beacon_free_scan` is kept as a deprecated hidden alias (removed in a future release).
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -10,11 +11,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 const OVERALL_TIMEOUT_MS = 5 * 60 * 1000;
-const server = new McpServer({ name: "collimer", version: "0.1.0" });
-server.registerTool("beacon_free_scan", {
-    title: "Collimer free AI-visibility scan",
+const server = new McpServer({ name: "collimer", version: "0.2.0" });
+const scanToolConfig = {
+    title: "Collimer AI-visibility scan",
     description: "Run a free Collimer scan on a website to measure how visible its brand is in AI " +
-        "search — ChatGPT, Perplexity, Google AI Overviews, etc. Returns an AI-visibility " +
-        "score (0–100), a confidence interval, the single biggest gap, and a branded report " +
-        "URL. The full report (share of voice across each engine + every recommendation) " +
-        "unlocks with a free account on the web. Tip: after the site makes changes, re-run " +
-        "the scan to measure the delta.",
+        "search — ChatGPT, Claude, Gemini, Perplexity, and Google AI Overviews. Returns an " +
+        "AI-visibility score (0–100), a confidence interval, the single biggest gap, and a " +
+        "branded report URL. The full report (share of voice across each engine + every " +
+        "recommendation) unlocks with a free account on the web. Tip: after the site makes " +
+        "changes, re-run the scan to measure the delta.",
     inputSchema: {
@@ -32,6 +33,7 @@ domain: z
     annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ domain, email }) => {
+};
+async function handleScan({ domain, email }) {
     try {
-        // Bound the whole call (#2) — composed into every fetch inside runScan —
-        // so a hung scan can't block the MCP client indefinitely.
+        // Bound the whole call — composed into every fetch inside runScan — so a
+        // hung scan can't block the MCP client indefinitely.
         const teaser = await runScan(domain, email, AbortSignal.timeout(OVERALL_TIMEOUT_MS));
@@ -44,3 +46,7 @@ return { content: [{ type: "text", text: formatTeaser(teaser) }] };
     }
-});
+}
+// Primary tool.
+server.registerTool("collimer_scan", scanToolConfig, handleScan);
+// Deprecated alias — kept one release for clients pinned to the old name.
+server.registerTool("beacon_free_scan", { ...scanToolConfig, description: `${scanToolConfig.description} (Deprecated alias for collimer_scan.)` }, handleScan);
 async function main() {
@@ -47,0 +53,0 @@ const transport = new StdioServerTransport();

dist/protocol-test.js

 // MCP protocol test: spawn the server over stdio, list tools, and call
-// beacon_free_scan via a real MCP client. Proves the transport + tool
+// collimer_scan via a real MCP client. Proves the transport + tool
 // registration work (not just the core). Run: node dist/protocol-test.js
@@ -14,9 +14,10 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
     const { tools } = await client.listTools();
-    const tool = tools.find((t) => t.name === "beacon_free_scan");
-    assert(tool, "beacon_free_scan tool is not registered");
+    const tool = tools.find((t) => t.name === "collimer_scan");
+    assert(tool, "collimer_scan tool is not registered");
     assert(tool.inputSchema, "tool has no input schema");
     console.log(`✓ tool registered: ${tool.name} — ${(tool.description ?? "").slice(0, 60)}...`);
+    assert(tools.some((t) => t.name === "beacon_free_scan"), "beacon_free_scan deprecated alias missing");
     // 2. Calling it returns the teaser. notion.so was just scanned → cache hit → fast.
     const result = await client.callTool({
-        name: "beacon_free_scan",
+        name: "collimer_scan",
         arguments: { domain: "notion.so" },
@@ -23,0 +24,0 @@ });

dist/scan.js

@@ -5,3 +5,3 @@ // Core scan logic — wraps the Collimer public free-scan REST API.
 export const SOURCE = process.env.COLLIMER_SCAN_SOURCE ?? "mcp";
-export const USER_AGENT = "collimer-mcp/0.1.0";
+export const USER_AGENT = "collimer-mcp/0.2.0";
 /** Parse a positive-number env override, falling back when missing/invalid (#7). */
@@ -8,0 +8,0 @@ function num(value, fallback) {

package.json

 {
   "name": "collimer-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for Collimer — run a free AI-search visibility scan on any website and get the score, top gap, and a branded report.",
   "license": "MIT",
+  "homepage": "https://collimer.com",
+  "repository": { "type": "git", "url": "git+https://github.com/sandcastlelabs/collimer-mcp.git" },
+  "bugs": { "url": "https://github.com/sandcastlelabs/collimer-mcp/issues" },
+  "author": "Sandcastle Labs (https://sandcastlelabs.ai)",
   "type": "module",
@@ -7,0 +11,0 @@ "bin": {

README.md

 # collimer-mcp
 
-An [MCP](https://modelcontextprotocol.io) server that lets AI agents run a **free Collimer AI-search visibility scan** on any website — how visible a brand is in ChatGPT, Perplexity, Google AI Overviews, and other answer engines.
+[![npm](https://img.shields.io/npm/v/collimer-mcp)](https://www.npmjs.com/package/collimer-mcp) · MIT · [Model Context Protocol](https://modelcontextprotocol.io)
 
-It exposes one tool, **`beacon_free_scan`**, which returns a depth-gated teaser: an AI-visibility score, a confidence interval, the single biggest gap, and a branded report URL. The full report (share of voice across each engine + every recommendation) unlocks with a free account on the web.
+**Let any AI agent run a free AI-search visibility scan on any website** — how visible a brand is in ChatGPT, Claude, Gemini, Perplexity, and Google AI Overviews.
 
+Trackers tell you you're invisible. Collimer tells you *why*, and what to fix.
+
+It exposes one tool, **`collimer_scan`**, which returns a depth-gated teaser: an AI-visibility score (0–100), a confidence interval, the single biggest gap, and a branded report URL. The full report — share of voice across every engine + every recommendation — unlocks with a free account at [collimer.com](https://collimer.com).
+
 ## Install
 
-### Claude Desktop / Claude Code (and any MCP client)
+Add Collimer to any MCP client. It runs on-demand via `npx` — no install step.
 
-Add to your MCP config (e.g. `claude_desktop_config.json`):
+**Claude Desktop / Claude Code** — add to your MCP config (`claude_desktop_config.json`, or `.mcp.json` in your project):
 
@@ -24,12 +28,22 @@ ```json
 
-Then ask your assistant something like *"How visible is example.com in AI search?"* — it will call `beacon_free_scan`.
+**Cursor / Windsurf / VS Code** — same block, in the editor's MCP settings (`~/.cursor/mcp.json`, Windsurf MCP settings, or `.vscode/mcp.json`).
 
+Then ask your assistant:
+
+> *"How visible is stripe.com in AI search?"*
+> *"Run a Collimer scan on example.com and tell me the biggest AI-visibility gap."*
+> *"Does ChatGPT cite acme.com when asked about its category?"*
+
+Your assistant will call `collimer_scan` and return the teaser.
+
 ## The tool
 
-`beacon_free_scan(domain, email?)`
+**`collimer_scan(domain, email?)`**
 
-- `domain` — the website to scan, e.g. `example.com` or `https://example.com`.
-- `email` *(optional)* — emails the report and speeds claiming the account later.
+| Arg | | |
+|---|---|---|
+| `domain` | required | The website to scan — `example.com` or `https://example.com`. |
+| `email` | optional | Emails the report and speeds claiming the account later. |
 
-Returns the teaser (score, confidence interval, top gap, report URL, and an unlock link). It **never** returns the full report — that is gated behind a free account.
+Returns the teaser — score, confidence interval, top gap, report URL, and an unlock link. It **never** returns the full report; that's gated behind a free account.
 
@@ -41,3 +55,3 @@ ## Configuration (env)
 | `COLLIMER_API_BASE` | `https://app.collimer.com` | API base URL |
-| `COLLIMER_SCAN_SOURCE` | `mcp` | Funnel attribution channel |
+| `COLLIMER_SCAN_SOURCE` | `mcp` | Funnel-attribution channel (set per distribution) |
 | `COLLIMER_MAX_POLLS` | `60` | Max poll attempts |
@@ -47,2 +61,10 @@ | `COLLIMER_POLL_INTERVAL_MS` | `5000` | Poll interval |
 
+## What is Collimer?
+
+[Collimer](https://collimer.com) measures and improves how often AI answer engines cite your brand — generative engine optimization (GEO), the AI-search successor to SEO. This MCP server is the free front door: scan any site from inside your assistant, see the score and the biggest gap, then open the full report and start tracking at [collimer.com](https://collimer.com). API docs: [app.collimer.com/docs](https://app.collimer.com/docs).
+
+## Privacy
+
+The server calls Collimer's public scan API for the domain you pass and returns the result. It doesn't read your files or your conversation. Scans carry a `source` tag (default `mcp`) so we can see which channels are useful — no personal data beyond the optional email you provide.
+
 ## Develop
@@ -57,6 +79,4 @@
 
-The public API it wraps is documented at <https://app.collimer.com/docs> (OpenAPI: `/api/v1/openapi.json`).
-
 ## License
 
-MIT
+MIT © [Sandcastle Labs](https://sandcastlelabs.ai)

Fixed alerts

No contributors or author data

Maintenance

Package does not specify a list of contributors or an author in package.json.

No bug tracker

Maintenance

Package does not have a linked bug tracker in package.json.

No repository

Supply chain risk

Package does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.

No website

Quality

Package does not have a website.

Improved metrics

Total package byte prevSize

17519

22.48%

Number of package files

7

16.67%

Lines of code

266

2.7%

Number of low maintenance alerts

0

-100%

Number of low quality alerts

2

-33.33%

Number of lines in readme file

79

33.9%

Number of low supply chain risk alerts

6

-14.29%

No dependency changes