Skip to main content
Glama
README.md
# advisorscope

Look up the people and firms behind investment advice.
advisorscope is a keyless forwarding client for the hosted
AdvisorFinder MCP endpoint, which serves SEC registration
data: individual adviser representatives, the firms they
work for, marketplace-listed advisors you can actually
book, and statistics across the whole database.

There is nothing local to configure and no account to
create. This package holds the tool definitions and a
small set of guard rails; every lookup is forwarded to the
hosted endpoint and the answer comes back exactly as the
remote server produced it, serialized as JSON text.

## How forwarding works

Each tool call opens a fresh session with the remote MCP
server and closes the loop in three steps:

1. An `initialize` JSON-RPC POST (protocol version
   `2025-03-26`, client `advisorscope/0.1.0`); the
   `mcp-session-id` response header is captured.
2. A `notifications/initialized` POST carrying that session
   header.
3. A `tools/call` POST with the tool name and your
   arguments, forwarded verbatim — nothing is added,
   renamed or dropped.

Responses in plain JSON and in SSE framing are both
understood. A remote JSON-RPC error surfaces as an error
result carrying the remote message; a non-2xx reply fails
with `advisorfinder error: HTTP <status>`; an unreachable
endpoint fails with `advisorfinder unreachable`. There are
no retries.

## Configuration

- No API key, no account, and no `Authorization` header is
  ever sent.
- `ADVISORFINDER_MCP_URL` (optional) — the remote MCP
  endpoint. Defaults to `https://mcp.advisorfinder.com/mcp`.

## Tools

- `search_advisors` — adviser representatives matching a
  `name`, `firm`, `city` and/or `state`. Each match carries
  a CRD, the linked firm(s), a four-state disclosure
  status, and an SEC IAPD link.
- `get_advisor` — the full profile for one `crd`:
  employment history, exams passed, states of registration,
  self-reported designations, years in the industry, and
  disclosure status.
- `check_advisor` — a fast registration check by `crd` or
  `name`, optionally narrowed by `firm` and/or `state`:
  active or not, which states, how long in the industry,
  disclosure status. Facts only — never a numeric risk
  score.
- `find_bookable_advisors` — advisors listed on the
  AdvisorFinder marketplace, filtered by `specialty`,
  `city` and/or `state`, with self-provided profile details
  and the regulatory facts behind their CRD (or a labelled
  note when a listing is not in the SEC dataset).
- `search_firms` — registered firms matching a `name`
  and/or `state`, with CRD, city/state, AUM band, advisor
  headcount, and an SEC IAPD link.
- `get_firm` — the full profile for one firm `crd`:
  locations, other and prior names, the fee schedule from
  Form ADV Part 2A where available, disciplinary flags,
  and advisor roster count.
- `get_database_stats` — totals for firms and advisors,
  the data vintage of each upstream source, and the full
  four-state disclosure tally. Takes no arguments.

### Local guards

Two checks run locally, before anything is sent:

- `get_advisor` and `get_firm` need a non-empty `crd`;
  without one they fail with `crd must be a non-empty
  string` and no request is made.
- `check_advisor` needs at least one of `crd` or `name`;
  with neither it fails with `check_advisor requires crd
  or name` and no request is made.

Everything else is forwarded as given — validation of the
remaining arguments is the remote server's job.

### Provenance

The tool list and each tool's meaning come from the
upstream package's published description. Two parts are
reconstructions, labelled as such: the per-tool argument
sets follow the description's documented parameter
semantics rather than a tabulated schema, and the
Streamable HTTP session handshake follows the standard
session pattern for hosted MCP endpoints.

## CLI

Each tool is a subcommand taking one JSON argument string:

```bash
npx @reneturcios/advisorscope search_advisors '{"state":"CA","city":"San Francisco"}'
npx @reneturcios/advisorscope get_advisor '{"crd":"123456"}'
npx @reneturcios/advisorscope check_advisor '{"name":"Jane Doe","state":"NY"}'
npx @reneturcios/advisorscope find_bookable_advisors '{"specialty":"retirement","state":"TX"}'
npx @reneturcios/advisorscope search_firms '{"name":"Acme","state":"DE"}'
npx @reneturcios/advisorscope get_firm '{"crd":"789012"}'
npx @reneturcios/advisorscope get_database_stats '{}'
npx @reneturcios/advisorscope --version
```

Output is the tool's result text (the remote result,
serialized as JSON, on success). Exit codes: `0` on
success, `1` on an error result (including a guard,
remote or transport failure), `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/advisorscope mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "advisorscope": {
      "command": "npx",
      "args": ["-y", "@reneturcios/advisorscope", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/advisorscope
docker run --rm ghcr.io/cloudcorprecords/advisorscope get_database_stats '{}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios