hive-rank 3.0.1 → 3.1.0

package/README.md

@@ -17,7 +17,7 @@ npx hive-rank
 Or add the MCP server directly:
 
 ```bash
-claude mcp add --transport sse hive-rank https://mcp.hive-rank.com/mcp
+claude mcp add --transport http hive-rank https://mcp.hive-rank.com/mcp
 ```
 
 ## What you get
@@ -35,7 +35,7 @@ claude mcp add --transport sse hive-rank https://mcp.hive-rank.com/mcp
 
 ### 15 Slash Commands
 
-Research commands that generate data for the network:
+Research commands:
 
 - `/hive:kickstart [domain]` — Bootstrap your SEO research
 - `/hive:baseline [domain] [keywords...]` — Establish baseline rankings

package/bin/install.js

@@ -98,10 +98,10 @@ function registerMcpServer() {
       spawnSync('claude', ['mcp', 'remove', oldName], { stdio: 'pipe' });
     }
 
-    // Register remote MCP server via SSE
+    // Register remote MCP server via Streamable HTTP
     const result = spawnSync(
       'claude',
-      ['mcp', 'add', '--scope', 'user', '--transport', 'sse', MCP_NAME, MCP_URL],
+      ['mcp', 'add', '--scope', 'user', '--transport', 'http', MCP_NAME, MCP_URL],
       { stdio: 'pipe', timeout: 10000 }
     );
 
@@ -130,7 +130,7 @@ function registerMcpServer() {
 
   if (!config.mcpServers) config.mcpServers = {};
   config.mcpServers[MCP_NAME] = {
-    type: 'sse',
+    type: 'http',
     url: MCP_URL
   };
 
@@ -262,7 +262,7 @@ if (FLAG_HELP) {
   What it does:
     1. Copies dist + commands to ~/.hive-rank/
     2. Registers hooks in ~/.claude/settings.json
-    3. Registers remote MCP server via \`claude mcp add\` (SSE transport)
+    3. Registers remote MCP server via \`claude mcp add\` (HTTP transport)
     4. Installs slash commands to ~/.claude/commands/hive/
 
   Config locations:
@@ -421,7 +421,7 @@ async function install() {
 
   if (FLAG_DRY_RUN) {
     if (hasClaudeCli()) {
-      dryLog(`Would run: claude mcp add --scope user --transport sse ${MCP_NAME} ${MCP_URL}`);
+      dryLog(`Would run: claude mcp add --scope user --transport http ${MCP_NAME} ${MCP_URL}`);
     } else {
       dryLog('Would register MCP server in ~/.claude.json');
     }
@@ -429,7 +429,7 @@ async function install() {
     log('Registering remote MCP server...');
     const mcpMethod = registerMcpServer();
     if (mcpMethod === 'cli') {
-      success('MCP server registered via `claude mcp add` (SSE transport)');
+      success('MCP server registered via `claude mcp add` (HTTP transport)');
     } else if (mcpMethod === 'direct') {
       success('MCP server registered in ~/.claude.json');
     } else {
@@ -506,7 +506,7 @@ async function install() {
 
   Config:
     Hooks:      ${SETTINGS_FILE}
-    MCP server: ${MCP_URL} (via SSE)
+    MCP server: ${MCP_URL} (via HTTP)
     Commands:   ${COMMANDS_DIR}/
 
   To uninstall: node ~/.hive-rank/bin/install.js --uninstall

package/commands/backlinks.md

@@ -0,0 +1,84 @@
+---
+name: backlinks
+description: Analyze backlink opportunities for a domain
+allowed-tools:
+  - mcp: hive-rank
+    tools:
+      - hive_domain
+      - hive_search
+      - hive_rankings
+---
+
+# Backlink Opportunity Analysis
+
+Analyze backlink opportunities for: $ARGUMENTS
+
+## Instructions
+
+You are a link building strategist. Conduct a thorough backlink opportunity analysis for the given domain or topic area. Provide actionable strategies the user can execute.
+
+### 1. Domain Link Profile Assessment
+
+Start by evaluating the domain's current backlink situation:
+- What type of site is this? (SaaS, e-commerce, blog, local business, etc.)
+- What kinds of content would naturally attract links in this niche?
+- What is the competitive landscape for links in this space?
+
+Use `hive_domain` to understand the domain's current search presence and competitive position.
+
+### 2. Competitor Link Source Analysis
+
+Identify where competitors in this space typically earn backlinks:
+- **Resource pages** — directories, tool lists, and curated resource pages in the niche
+- **Guest posting targets** — blogs and publications that accept contributor content
+- **Industry roundups** — newsletters, weekly digests, and "best of" lists
+- **Partnership opportunities** — complementary (non-competing) businesses for co-marketing
+- **News and PR** — journalists, bloggers, and publications covering this space
+
+Use `hive_rankings` to identify which competitors rank well and are worth analyzing.
+
+For each source type, provide 3-5 specific, actionable suggestions with the reasoning behind why they would be effective.
+
+### 3. Unlinked Brand Mention Opportunities
+
+Suggest strategies for finding and converting unlinked mentions:
+- Search operators to find unlinked mentions (e.g., `"brand name" -site:yourdomain.com`)
+- Types of content where unlinked mentions commonly occur (forums, reviews, comparison posts)
+- Outreach template approach for converting mentions into links
+- Tools and techniques for monitoring new brand mentions
+
+### 4. Link-Worthy Content Strategies
+
+Recommend content types proven to attract backlinks in this niche:
+- **Original research and data** — surveys, studies, industry benchmarks
+- **Visual assets** — infographics, diagrams, charts that others embed
+- **Free tools and calculators** — interactive resources people link to
+- **Definitive guides** — comprehensive resources that become go-to references
+- **Newsjacking** — timely commentary on industry news and trends
+
+For each strategy, explain what to create and why it would earn links.
+
+### 5. Link Building Action Plan
+
+Provide a prioritized 30-day action plan:
+- **Week 1:** Quick wins (unlinked mentions, broken link opportunities, existing relationships)
+- **Week 2:** Outreach campaign setup (prospect lists, email templates, tracking)
+- **Week 3:** Content creation for link magnets (start the highest-ROI piece)
+- **Week 4:** Active outreach and relationship building
+
+### 6. Links to Avoid
+
+Warn about link building tactics that can harm the site:
+- Paid links without `rel="sponsored"`
+- Private blog networks (PBNs)
+- Excessive reciprocal link exchanges
+- Low-quality directory submissions
+- Exact-match anchor text over-optimization
+
+## Guidelines
+
+- Focus on sustainable, white-hat link building strategies
+- Prioritize recommendations by effort vs. impact
+- Be specific with suggestions — generic advice like "create great content" is not helpful
+- Consider the domain's size and resources when making recommendations
+- Use Hive Rank's crowdsourced SERP data to identify which competitors are ranking well and worth analyzing for backlink sources

package/commands/glossary.md

@@ -0,0 +1,40 @@
+---
+name: glossary
+description: Look up any SEO term and get a clear definition
+allowed-tools:
+  - mcp: hive-rank
+    tools:
+      - hive_search
+      - hive_stats
+---
+
+# SEO Glossary Lookup
+
+Look up and explain the SEO term: $ARGUMENTS
+
+## Instructions
+
+You are an SEO educator. The user wants to understand an SEO term or concept. Provide a clear, practical explanation following this structure:
+
+### 1. Definition
+Give a concise, jargon-free definition of the term. If the term has multiple meanings in SEO, cover each one.
+
+### 2. Why It Matters
+Explain why this concept is important for SEO performance. Be specific about the impact on rankings, traffic, or visibility.
+
+### 3. Practical Example
+Provide a real-world example showing how this concept works in practice. Use a concrete scenario a website owner or marketer would recognize.
+
+### 4. AI Search Relevance
+If this concept is relevant to AI-powered search (ChatGPT, Perplexity, Google AI Overviews, etc.), explain how it applies in that context. AI search engines process and surface content differently than traditional search — highlight any differences in how this term applies. If the term has no particular AI search relevance, skip this section.
+
+### 5. Quick Action
+Give one specific, actionable step the user can take right now related to this concept.
+
+## Guidelines
+
+- Keep the explanation accessible to someone new to SEO, but don't oversimplify for advanced concepts
+- Use concrete numbers and examples where possible
+- Avoid circular definitions (don't define a term using the term itself)
+- If the term is commonly confused with another term, clarify the distinction
+- Reference how Hive Rank data (crowdsourced SERP intelligence) can help track or measure this concept when relevant

package/commands/schema.md

@@ -0,0 +1,78 @@
+---
+name: schema
+description: Generate JSON-LD schema markup for any content type
+allowed-tools: []
+---
+
+# JSON-LD Schema Markup Generator
+
+Generate JSON-LD structured data markup for: $ARGUMENTS
+
+## Instructions
+
+You are a structured data specialist. Generate complete, valid JSON-LD schema markup based on the user's request.
+
+### Step 1: Identify the Schema Type
+
+Determine the most appropriate schema type from the user's description. Common types include:
+
+- **Article** / **BlogPosting** / **NewsArticle** — for written content
+- **Product** — for product pages with pricing, reviews, availability
+- **FAQPage** — for frequently asked questions
+- **HowTo** — for step-by-step guides and tutorials
+- **Organization** / **LocalBusiness** — for company and business pages
+- **BreadcrumbList** — for navigation breadcrumbs
+- **WebSite** with **SearchAction** — for sitelinks search box
+- **Person** — for author or profile pages
+- **Event** — for events with dates, locations, ticket info
+- **Recipe** — for recipe pages
+- **VideoObject** — for video content
+- **SoftwareApplication** — for apps and tools
+- **Review** / **AggregateRating** — for review content
+
+If the user hasn't specified a type, ask them. If they describe their content, infer the best type and explain your choice.
+
+### Step 2: Generate the Markup
+
+Output a complete, valid JSON-LD script tag:
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "...",
+  ...
+}
+</script>
+```
+
+**Requirements:**
+- Include ALL required properties for the chosen type per Google's structured data guidelines
+- Include recommended properties that improve rich result eligibility
+- Use realistic placeholder values clearly marked with brackets like `[Your Title Here]`
+- Nest related types properly (e.g., `author` as a `Person` object, not a plain string)
+- Include `@id` properties for entities that may be referenced elsewhere on the site
+
+### Step 3: Explain the Markup
+
+After the JSON-LD block, briefly explain:
+- Which rich result this schema is eligible for in Google Search
+- Any required properties the user must fill in with real data
+- Common mistakes to avoid with this schema type
+- How to test the markup (mention Google's Rich Results Test)
+
+### Step 4: AI Search Considerations
+
+Note any structured data practices that help with AI search visibility:
+- Clear entity relationships help AI models understand your content
+- Comprehensive schema helps your content get cited in AI-generated answers
+- Proper use of `sameAs` links helps establish entity authority
+
+## Guidelines
+
+- Always validate against https://schema.org specifications
+- Follow Google's structured data guidelines for rich result eligibility
+- Do not include deprecated properties
+- Use ISO 8601 format for dates
+- Use proper nesting rather than flat structures
+- If multiple schema types apply to a single page, show how to combine them using `@graph`

package/dist/hooks/capture-seo-data.js

@@ -135,15 +135,16 @@ async function contributeToHive(hiveConfig, toolName, toolInput, parsedResponse)
       signal: controller.signal
     });
     if (!response.ok) {
-      let body = "";
-      try {
-        body = await response.text();
-      } catch {
-      }
-      throw new Error(
-        `Hive contribution failed: HTTP ${response.status}${body ? ` \u2014 ${body.slice(0, 200)}` : ""}`
-      );
+      return null;
+    }
+    try {
+      const data = await response.json();
+      return data;
+    } catch {
+      return null;
     }
+  } catch {
+    return null;
   } finally {
     clearTimeout(timeout);
   }
@@ -391,13 +392,47 @@ async function main() {
       debugLog(`Parsed WebFetch response`);
     }
     const { contributeToHive: contributeToHive2 } = await Promise.resolve().then(() => (init_client(), client_exports));
-    await contributeToHive2(
+    const result = await contributeToHive2(
       { enabled: true, endpoint: config.endpoint, contributorId: config.contributorId },
       tool_name,
       tool_input,
       parsedResponse
     );
     debugLog("Contribution sent");
+    if (result?.contributor) {
+      const hiveDir = path.join(os.homedir(), ".hive-rank");
+      try {
+        fs.mkdirSync(hiveDir, { recursive: true });
+      } catch {
+      }
+      const feedbackPath = path.join(hiveDir, "last-feedback.json");
+      let showFull = true;
+      try {
+        const prev = JSON.parse(fs.readFileSync(feedbackPath, "utf-8"));
+        if (prev.sessionId === hookInput.session_id) showFull = false;
+      } catch {
+      }
+      if (showFull) {
+        const c = result.contributor;
+        const totalContributors = result.network?.contributors ?? 0;
+        const topPercent = Math.max(1, 100 - c.percentile);
+        const streakPart = c.streak > 0 ? ` | streak: ${c.streak} day${c.streak !== 1 ? "s" : ""}` : "";
+        const rankPart = totalContributors > 0 ? ` | rank #${c.rank} of ${totalContributors.toLocaleString()} (top ${topPercent}%)` : "";
+        process.stderr.write(`[hive] +${result.inserted} observations${streakPart}${rankPart}
+`);
+        fs.writeFileSync(feedbackPath, JSON.stringify({ sessionId: hookInput.session_id, timestamp: (/* @__PURE__ */ new Date()).toISOString() }));
+      } else {
+        process.stderr.write(`[hive] +${result.inserted}
+`);
+      }
+      try {
+        fs.writeFileSync(
+          path.join(hiveDir, "last-receipt.json"),
+          JSON.stringify({ timestamp: (/* @__PURE__ */ new Date()).toISOString(), inserted: result.inserted, contributor: result.contributor, network: result.network })
+        );
+      } catch {
+      }
+    }
   } catch (error) {
     const errorMsg = error instanceof Error ? error.message : String(error);
     debugLog(`Error: ${errorMsg}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-rank",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Crowdsourced SEO intelligence for AI agents. Network-powered hooks contribute data to the hive. 6 hive_* tools via remote MCP server.",
   "author": "hive-rank",
   "license": "MIT",