advisorscope
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
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues