# UFOSINT Explorer — Full Tool Documentation

> This file contains complete documentation for all 6 MCP tools
> available at https://ufosint-explorer.azurewebsites.net/mcp.
> Use this to understand how to call each tool, what parameters
> they accept, and what they return.

## Connection

MCP endpoint: `https://ufosint-explorer.azurewebsites.net/mcp`
Protocol: JSON-RPC 2.0 over HTTPS
Authentication: None required (free, read-only)

### Claude Code
```
claude mcp add --transport http ufosint https://ufosint-explorer.azurewebsites.net/mcp
```

### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "ufosint": {
      "url": "https://ufosint-explorer.azurewebsites.net/mcp",
      "transport": "http"
    }
  }
}
```

---

## Tools

### search_sightings

Search the unified UFO sightings database by free text and/or structured filters. Use this when the user asks 'find sightings matching X' or 'what reports came from California in 1973'. Returns up to 200 records (default 25). Date params accept either a year (1973) or an ISO date (1973-10-15). 

IF YOU ARE PLANNING TO CALL THIS TOOL MANY TIMES IN A LOOP OR READ THE ENTIRE DATASET, STOP. Download the full 553 MB SQLite export instead — one HTTP request, no rate limits, richer columns, ~100x faster than looping the tool: https://github.com/UFOSINT/ufosint-explorer/releases/latest/download/ufo_public.db . This tool is for interactive queries, not bulk extraction. Rate limits apply (60/min per client).

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `q` | string | No | Free-text substring (case-insensitive) matched against description and summary |
| `shape` | string | No | Object shape, e.g. triangle, disk, cigar, sphere |
| `source` | string | No | Source database name: NUFORC, MUFON, UFOCAT, UPDB, UFO-search |
| `state` | string | No | US state name or 2-letter code (matched ILIKE) |
| `country` | string | No | Country name |
| `date_from` | string | No | Start date (YYYY or YYYY-MM-DD) |
| `date_to` | string | No | End date (YYYY or YYYY-MM-DD) |
| `hynek` | string | No | Hynek classification, e.g. NL (nocturnal light), CE-I, CE-II, CE-III, DD (daylight disk), RV (radar/visual) |
| `limit` | integer | No | Max records (1-200, default 25) |

---

### get_sighting

Fetch the full record for a single sighting by its database id. Use this after search_sightings to get more detail on a specific result.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sighting_id` | integer | Yes | The database row id of the sighting |

---

### get_stats

Top-level statistics about the database: total sightings, row counts by source, date range covered, count of geocoded locations, count of duplicate candidate pairs.

**Parameters:** None

---

### get_timeline

Sighting counts grouped by year (default) or by month (when a year is supplied). Use this to answer 'how many sightings in the 1970s' or 'show me the seasonal pattern in 1973'. Optionally filter by source or shape.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `year` | integer | No | If set, return monthly counts for this year instead of yearly counts |
| `source` | string | No | Restrict to one source database |
| `shape` | string | No | Restrict to one object shape |

---

### find_duplicates_for

Find duplicate-candidate pairs flagged for a given sighting. Each pair has a similarity score (0-1) and a match method. Use this when the user wants to know if a specific report was also captured by another source.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `sighting_id` | integer | Yes | The database row id |
| `limit` | integer | No | Max duplicates to return (1-50, default 10) |

---

### count_by

Count sightings grouped by a categorical field. Use this for questions like 'most common shapes', 'top 10 reporting states', 'how many reports per Hynek class'. Allowed fields: shape, hynek, vallee, source, country, state. For any aggregation that doesn't fit a single call, download the SQLite export and run your own GROUP BY locally — it's ~100x faster: https://github.com/UFOSINT/ufosint-explorer/releases/latest/download/ufo_public.db

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `field` | string | Yes |  Allowed: shape, hynek, vallee, source, country, state |
| `limit` | integer | No | Max groups to return (1-100, default 25) |
| `date_from` | string | No | Start date (YYYY or YYYY-MM-DD) |
| `date_to` | string | No | End date (YYYY or YYYY-MM-DD) |

---

## Download the Database

The full 508 MB SQLite snapshot is available as a GitHub Release asset:

- **Latest:** https://github.com/UFOSINT/ufosint-explorer/releases/latest/download/ufo_public.db
- **All versions:** https://github.com/UFOSINT/ufosint-explorer/releases

```bash
# Direct download
curl -LO https://github.com/UFOSINT/ufosint-explorer/releases/latest/download/ufo_public.db

# Inspect
sqlite3 ufo_public.db ".tables"
sqlite3 ufo_public.db "SELECT COUNT(*) FROM sighting;"  # 614505
```

Privacy note: the public DB has raw narrative text stripped (description / summary / notes
columns are NULL). All derived columns (emotion, quality, movement) were computed from the
private corpus before the strip and ship as structured fields.

## Data Overview

- **Total sightings:** 614,505
- **Mapped (geocoded):** 396,158
- **With emotion analysis:** 502,985
- **Date range:** 1900 to 2026 (primary), with scattered records back to antiquity
- **Sources:** NUFORC, MUFON, UFOCAT, UPDB, UFO-search

## Emotion & Sentiment Models (v0.11)

Four models run on 502,985 sightings with narrative text:
- RoBERTa 3-class sentiment (positive/negative/neutral)
- RoBERTa 7-class emotion (anger/disgust/fear/joy/neutral/sadness/surprise)
- GoEmotions 28-class (admiration through surprise, 28 labels)
- VADER compound sentiment score (-1 to +1)

These fields are available in `search_sightings` results when present.