# hive-rank

Crowdsourced SEO intelligence for AI agents. Real-time SERP data from anonymous contributors.

## Connect

```
npx hive-rank
```

Installs MCP server, contribution hooks, and slash commands. Restart Claude Code after installation.

## MCP Tools

### hive_rankings

Get aggregated search rankings from the network.

**Parameters:**
- `query` (string, required) - Search query to look up
- `days` (number, default: 30) - Look back N days
- `limit` (number, default: 50) - Max results

**Returns:**
```json
{
  "query": "best crm software",
  "results": [
    {
      "url": "https://example.com/crm",
      "avgPosition": 2.3,
      "contributorCount": 47,
      "observationCount": 156
    }
  ],
  "networkContributors": 47,
  "totalObservations": 156
}
```

### hive_trending

See trending queries across the network.

**Parameters:**
- `days` (number, default: 7) - Look back N days
- `limit` (number, default: 20) - Max queries
- `category` (string, default: "active") - One of: "active", "volatile", "new"

**Returns:**
```json
{
  "category": "active",
  "queries": [
    {
      "query": "ai coding assistant",
      "observationCount": 234,
      "contributorCount": 89
    }
  ]
}
```

### hive_domain

Get network intelligence for a specific domain.

**Parameters:**
- `domain` (string, required) - Domain to look up (e.g., "notion.so")
- `days` (number, default: 30) - Look back N days
- `limit` (number, default: 50) - Max queries

**Returns:**
```json
{
  "domain": "notion.so",
  "results": [
    {
      "query": "project management tool",
      "avgPosition": 4.2,
      "observationCount": 89
    }
  ]
}
```

### hive_stats

Get network-wide statistics.

**Parameters:** None

**Returns:**
```json
{
  "totalContributors": 1234,
  "totalQueries": 56789,
  "totalObservations": 234567,
  "oldestData": "2024-01-15",
  "newestData": "2024-03-20"
}
```

### hive_contributors

Get contributor activity stats.

**Parameters:** None

**Returns:**
```json
{
  "totalContributors": 1234,
  "activeLastWeek": 456,
  "activeLastMonth": 890
}
```

### hive_score

Get a 0-100 domain authority score from the hive network. Computed from position strength, query diversity, contributor consensus, and data freshness.

**Parameters:**
- `domain` (string, required) - Domain to score (e.g., "example.com")

**Returns:**
```json
{
  "domain": "example.com",
  "score": 72,
  "confidence": "high",
  "breakdown": {
    "visibility": 81.3,
    "breadth": 65.2,
    "consensus": 70.1,
    "freshness": 88.4
  },
  "signals": {
    "queryCount": 15,
    "avgPosition": 4.2,
    "top3Count": 6,
    "top10Count": 12,
    "contributorCount": 8,
    "observationCount": 45
  },
  "summary": "example.com has a Hive Score of 72/100 (high confidence)..."
}
```

### hive_contribute

Submit anonymized search data to the network. Called automatically by contribution hooks — not typically invoked manually.

**Parameters:**
- `contributions` (array, required) - Array of search result observations

**Returns:**
```json
{
  "accepted": 5,
  "message": "Contributions accepted"
}
```

### hive_search

Full-text search across network queries.

**Parameters:**
- `query` (string, required) - Search text
- `limit` (number, default: 20) - Max results

**Returns:**
```json
{
  "query": "crm",
  "results": [
    {
      "query": "best crm software 2024",
      "observationCount": 156,
      "contributorCount": 47
    }
  ]
}
```

### hive_whoami

Check whether this MCP connection is authenticated to a Hive Rank workspace.
No parameters.

**Returns (authenticated):**
```json
{
  "authenticated": true,
  "tier": "hatchling",
  "scopes": ["read", "contribute"]
}
```

**Returns (anonymous):**
```json
{
  "authenticated": false,
  "note": "Anonymous — generate a token at https://app.hive-rank.com/dashboard/settings/tokens and run `npx hive-rank auth` to wire it in."
}
```

### hive_my_monitors

List the authenticated workspace's monitors with a 30-day probe rollup.
Requires a bearer token — anonymous calls return guidance, not data.

**Parameters:**
- `limit` (number, default: 50, max: 100) - Max monitors to return

**Returns (authenticated):**
```json
{
  "workspace_tier": "hatchling",
  "monitor_count": 2,
  "monitors": [
    {
      "id": "uuid",
      "name": "agenticworkers.com",
      "target": "agenticworkers.com",
      "queries": ["..."],
      "frameworks": ["claude-code"],
      "surfaces": ["hive", "exa"],
      "stats_30d": {
        "total_runs": 28,
        "successful_runs": 28,
        "brand_surfaced": 12,
        "best_position": 1
      }
    }
  ]
}
```

## Slash Commands

Research commands:

- `/hive:kickstart [domain]` - Bootstrap SEO research
- `/hive:baseline [domain] [keywords...]` - Establish ranking baselines
- `/hive:grow [domain]` - Weekly growth check
- `/hive:spy [competitor]` - Deep competitor analysis
- `/hive:content [topic]` - Generate SEO content brief
- `/hive:learn [topic]` - Learn SEO with real examples
- `/hive:audit-site [domain]` - Technical SEO audit

Analysis commands (query network intelligence):

- `/hive:report [domain]` - Full SEO report from network data
- `/hive:audit` - Check contribution status
- `/hive:competitors [domain]` - Discover competitors
- `/hive:rankings [query]` - Network ranking data for a query
- `/hive:score [domain]` - Domain authority score 0–100
- `/hive:keywords [domain]` - Keyword opportunities
- `/hive:trends` - Trending queries
- `/hive:status` - Network status
- `/hive:whoami` - Show this session's MCP auth state
- `/hive:monitors` - List this workspace's monitors (authed)
- `/hive:privacy` - View contribution + data-collection status
- `/hive:delete-data` - Request deletion of contributed data
- `/hive:backlinks [domain]` - Backlink opportunity analysis
- `/hive:schema [type]` - Generate JSON-LD schema markup
- `/hive:glossary [term]` - Look up an SEO term
- `/hive:help` - Full reference (all 23 skills)

## Constraints

| Constraint | Value |
|------------|-------|
| Rate limit | 100 requests / 60 seconds per contributor |
| Query length | 1-500 characters |
| URL length | 1-2000 characters |
| Contributor hash | 64-char lowercase hex (SHA256) |
| Date format | YYYY-MM-DD only |

## How It Works

1. **You search** - WebSearch or WebFetch triggers data collection
2. **Anonymized** - Query normalized, contributor ID hashed, no PII
3. **Aggregated** - Rankings from all contributors combined
4. **Everyone benefits** - Query the network for collective intelligence

## Links

- Dashboard: https://hive-rank.com/dashboard
- Documentation: https://hive-rank.com/docs