> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/mcp.md).

# Trend Finder MCP

Trend Finder exposes a local stdio MCP server so an assistant can query the generated Trend Finder payload without opening the browser UI.

## Boundary

* Reads `LiveData.extensions.items["trend-finder"]` from `src/data/live-data.json` by default.
* Reuses the static Brief export loader and projection, including schema validation and the static Brief privacy scan.
* Does not trigger collection, call source adapters, read raw logs, read raw source rows, or inspect private enrichment/snapshot caches.
* Emits provenance in every tool response: `dataState`, `analysisState`, `sourceState`, labels, run id, and last update time.
* Remote published-data fallback is not included here. That remains tied to the Cloudflare Pages published snapshot plan.

## Run

```bash
bun --silent run trend-finder:mcp
```

Equivalent direct command:

```bash
bun --silent scripts/extensions/trend-finder/mcp/server.ts
```

Options:

```
--root-dir <path>      Project root. Defaults to current working directory.
--live-data <path>     Live-data JSON path. Defaults to src/data/live-data.json.
--asset-root <path>    Evidence asset root. Defaults to .cache/extensions/trend-finder/assets.
--cache-ttl-ms <ms>    In-memory payload cache TTL. Defaults to 600000.
```

## Claude Code

Register the local server from the repository root:

```bash
claude mcp add trend-finder -- bun --silent run trend-finder:mcp
```

For a non-default payload path:

```bash
claude mcp add trend-finder -- bun --silent run trend-finder:mcp --live-data src/data/live-data.json
```

## Antigravity And Other MCP Clients

Use a stdio MCP server entry that runs the same command:

```json
{
  "mcpServers": {
    "trend-finder": {
      "command": "bun",
      "args": ["--silent", "run", "trend-finder:mcp"]
    }
  }
}
```

Run the client from the repository root, or pass `--root-dir` with an absolute project path.

## Tools

### `trend_finder_top_opportunities`

Returns ranked opportunities plus hidden gems from the current generated payload.

Input:

* `limit`: optional number from 1 to 15, default `8`.
* `verdict`: optional `all`, `act_now`, `monitor`, `review`, or `ignore`.

Output includes rank, score, movement, action verdict, next step, saturation, lifecycle, sample confidence, risk flags, source/evidence counts, and public evidence links to verify.

### `trend_finder_check_topic`

Fuzzy-matches a topic and returns the closest generated topic.

Input:

* `topic`: required topic phrase or id.

Output includes the match score, action verdict, saturation, lifecycle, sample confidence, risk flags, alternatives, and evidence links.

### `trend_finder_run_summary`

Returns an at-a-glance run summary: today's pick, run mood, banded posting window, movement groups, top riser, top cooler, action verdict mix, source health, prediction calibration, spend, enrichment, asset, and warning summaries.

`runMood` is projected from existing movement, action verdict, saturation, and camp-share fields. It is current-run display context only; the posting-window value is `Wide`, `Closing`, `Closed`, or `Unavailable`, never a day-count forecast.

## Verification

```bash
bun test ./scripts/extensions/trend-finder/__tests__/mcp-server.test.ts
bun run typecheck:scripts
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.