# officelens

officelens is a small local bridge to the Family Office
Registry's hosted MCP server, a sourced and dated
registry of family offices and related firms centred on
Switzerland and Liechtenstein, with coverage extending
to Austria, Germany, Dubai and registered advisers in
the US.

The bridge keeps no registry data and runs no lookups of
its own. It serves the upstream server's tool list
locally, exactly as captured from the live endpoint, and
forwards each tool call upstream, returning the result
untouched. The whole captured surface is read-only: this
rebuild adds no write capability.

## Tools

- `search_registry` — search verified family offices
  and related firms. Everything is optional: `q` (free
  text over the open fields — name, city, register id,
  legal form, focus tags; with a key it also reaches the
  people and the purpose clauses), `country` (`CH`,
  `LI`, `AT`, `DE`, `AE` or `US`), `canton` (a Swiss
  canton code such as `ZH`, `ZG` or `GE`), `type`
  (`SFO`, `MFO` or `intermediary`), `alloc` (how firms
  invest — a subscription-only filter the search refuses
  without a key), `page` (from 1, default 1), `size`
  (1-25 results per page, default 10, capped at 25
  without a subscription key) and `purpose` (one line on
  what the user is trying to do, logged without the
  caller and never changing the answer). One page of
  open records comes back — the same fields the public
  site publishes. Named people, contact channels, source
  lists and verification notes need a subscription.
- `get_record` — one firm by its registry `id` (the id
  `search_registry` returns), plus the same optional
  `purpose` line. Without a subscription key this
  returns the open fields and says how many named roles
  the full record holds; with one it returns the named
  roles, the contact channels, the full source list and
  the verification note.

## Configuration

- `FAMILYOFFICEREGISTRY_MCP_URL` (optional) — override
  the upstream endpoint. Defaults to
  `https://familyofficeregistry.com/api/mcp`. The alias
  `FOR_MCP_URL` is also honoured. (The override hook is
  this rebuild's own labelled reconstruction.)
- `FAMILYOFFICEREGISTRY_API_KEY` (optional) — when set,
  every upstream request carries an
  `Authorization: Bearer <key>` header; the alias
  `FOR_API_KEY` is also honoured. When neither is set,
  no auth header is sent. (This forwarding is also a
  labelled reconstruction; the original surface was
  captured keyless.)

### Forwarding mechanics

On the first tool call the client opens a streamable
HTTP session with the upstream: a JSON-RPC `initialize`
request (protocolVersion `2025-03-26`, clientInfo name
`officelens`), then a `notifications/initialized`
notification, then the `tools/call` request carrying
the caller's arguments unchanged. When the upstream
answers `initialize` with an `Mcp-Session-Id` header,
that value rides on every later request of the session,
which is reused for the life of the process. Replies
may arrive as plain JSON or as server-sent events;
both are read.

Successful upstream results pass through verbatim,
including any `isError` flag the upstream sets.
Failures — a JSON-RPC error, a non-2xx status, an
unreadable response, or a request that cannot be
completed — come back as an `isError` result whose
text starts with `officelens error:` (this rendering
is this rebuild's own labelled reconstruction).

## CLI

Each tool is also a subcommand taking one JSON argument
string (omit it for tools that take none):

```bash
npx @reneturcios/officelens search_registry '{"country":"CH","canton":"ZH","type":"MFO"}'
npx @reneturcios/officelens get_record '{"id":"CHE-116.281.419"}'
npx @reneturcios/officelens --version
```

Exit codes: `0` on success, `1` on an `isError`
result, `2` on a usage error.

## MCP server

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

MCP client config:

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

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/officelens
docker run --rm ghcr.io/cloudcorprecords/officelens --version
```

The container's default command is `mcp`, so the first
form is a stdio MCP server; any other arguments reach
the CLI normally.

## Development

```bash
npm install
npm run build
npm test
npm run dev
```

The test suite runs entirely against a stubbed
JSON-RPC upstream — no live network calls.

## License

MIT — see `LICENSE`.