Skip to main content
Glama
io.github.benjamin-di/earnings-watch

io.github.benjamin-di/earnings-watch

by benjamin-di
README.md
# Earnings Watch

<!-- mcp-name: io.github.benjamin-di/earnings-watch -->

Verified issuer earnings calendars and results documents through a CLI, Python API and MCP server. Models propose dates; deterministic checks require quoted evidence and consistent issuer, period and timing. A call time never silently becomes a publication time.

Calendar updates are optional. Earnings Watch produces an operation plan; your MCP client uses its external Outlook app to apply it and acknowledges confirmed writes. No Microsoft credentials or calendar SDK are required by this package.

Maintained source and contributions: [benjamin-di/earnings-watch](https://github.com/benjamin-di/earnings-watch). See [Source and releases](docs/SOURCE.md).

Requires Python 3.12+. Install the published package with `uv tool install earnings-watch`, or develop from a source checkout:

```sh
make bootstrap
uv run earnings-watch init
uv run earnings-watch doctor
uv run earnings-watch sources import examples/sources.yaml
uv run earnings-watch watch EXAMPLE
uv run earnings-watch upcoming --format json
```

The example uses reserved domains and fictional data; replace its source URLs and issuer metadata before fetching. There is no bundled issuer universe or market-data subscription.

## Maintenance and models

Serving reads SQLite and updates personal follows/ledgers; it never fetches issuer pages or calls a model. Run maintenance separately:

```sh
uv run earnings-watch sweep --dry-run
uv run earnings-watch sweep
uv run earnings-watch sweep --docs-only
uv run earnings-watch worker
```

The default backend is `none`: it preserves existing dates and still polls official release providers. To extract new dates, install and sign into your own Claude Code or Codex CLI, then configure it in `earnings-watch.toml`:

```toml
[llm]
backends = ["claude-code", "codex", "none"]
max_calls_per_run = 20
```

Supported minimum versions are Claude Code 2.1.312 and Codex 0.164.0. Run `earnings-watch doctor --live` to check capabilities and an optional model canary. The package has no login flow. Model usage follows your CLI account's limits and terms. Only an explicit sign-in or account-limit refusal, or a configured Codex endpoint that is unreachable or failing before any output, tries the next backend; a timed-out run is not repeated in the same tick.

Codex runs with `--ignore-user-config`. To send it through an OpenAI Responses-compatible endpoint, set both `codex_base_url` and `codex_key_env` (the name of the environment variable holding its key) under `[llm]`; the key itself never goes in the file. Use `https://` for any endpoint that is not on the local host. Claude Code receives `ANTHROPIC_BASE_URL` and `CLAUDE_CODE_MAX_RETRIES` from the environment, so a bounded retry count lets an unavailable endpoint fail before the task timeout.

## MCP

A local client configuration, after initialization:

```json
{"mcpServers":{"earnings":{"command":"earnings-watch","args":["serve","--stdio"]}}}
```

| Tool | Purpose |
| --- | --- |
| `earnings_upcoming` | Bounded upcoming dates with timing uncertainty |
| `earnings_get_events` | Evidence, revisions and recent history |
| `earnings_documents` | Official result-document links and verification status |
| `earnings_changes` | Cursor-based public change feed |
| `earnings_watchlist` | Your follows and registration states |
| `earnings_watch` | Follow an issuer; queue registration or resolve ambiguity |
| `earnings_unwatch` | Remove a manual follow |
| `earnings_calendar_plan` | Plan optional external calendar operations |
| `earnings_calendar_ack` | Record confirmed operations from a signed plan |
| `earnings_status` | Catalogue and maintenance status |

Prompts: `earnings_briefing`, `results_brief`, `sync_to_my_outlook`. Resource: `earnings://upcoming.ics`. Exact times require verified clock and timezone evidence; otherwise calendar entries are all-day. Outlook operations never include attendees.

HTTP standalone mode uses a separate bearer token per person at `/users/<id>/mcp`. Gateway mode accepts a configured backend bearer and an immutable subject header from the admission gateway at `/mcp`. These modes are separate trust boundaries; see [permissions](docs/PERMISSIONS.md).

## Connections page and notifications

The optional [Connections page](docs/CONNECTIONS.md) provides Upcoming, Your
companies, Notifications and Calendar in one place. Sign in, add companies or
preview a holdings import, then subscribe to your private calendar feed. Facts
are shared; holdings, watchlists, mutes, preferences and receipts are personal.

Results-out notifications are enabled for new people. Daily briefs and urgent
changes are optional. Mail submission requires a separately configured transport;
the server and acquisition worker never send messages themselves.

## Docker Compose

```sh
cp earnings-watch.example.toml earnings-watch.toml
docker compose build
docker compose run --rm server init
docker compose run --rm server users add example
docker compose up -d
```

Save the returned token privately and use it only on that person's HTTP path. The server binds to loopback by default. Both images run as uid 1000; Compose drops capabilities, prevents privilege escalation and mounts the root filesystem read-only. The worker image includes pinned model CLIs; their auth volume is optional with `backends=["none"]`. Configure CLI sign-in outside the read-only worker before enabling model maintenance. Protect auth files and the data volume from other users.

Use `--config PATH`, `--person ID`, and `--json` with the CLI. Settings come from TOML and `EARNINGS_WATCH_*` environment variables. See [operations](docs/OPERATIONS.md), [architecture](docs/ARCHITECTURE.md), [providers](docs/PROVIDERS.md) and [design decisions](docs/DESIGN.md).

## Development

`make check` verifies lock drift, lint, formatting, types, dependency boundaries, offline tests and wheel/source builds. Tests use synthetic issuers and fake network/model/account boundaries. Real-model and real-page checks are separate operator gates. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).

See [implementation status](docs/IMPLEMENTATION.md) for completed capabilities,
release gates and the production adapter work still required before cutover.

TDQS

B3/5.0

Scored across 10 tools

Disambiguation5/5

Each tool has a distinct role: events, upcoming dates, documents, change feed, watchlist, follow/unfollow, calendar planning/acknowledgment, and status. The read-only public-data tools are clearly separated by resource, and the write tools are clearly separated by action. No two tools appear to do the same thing.

Naming Consistency3/5

All tools use the same earnings_ prefix and snake_case, which keeps them readable. However, the suffix conventions are mixed: get_events is verb_noun, upcoming/documents/changes/watchlist/status are noun-oriented, and watch/unwatch/calendar_plan/calendar_ack mix action and object styles. The pattern is understandable but not consistently verb_noun.

Tool Count5/5

Ten tools is a well-scoped set for an earnings-watch service. It covers reads, follows, change tracking, calendar coordination, and status without obvious redundancy. Each tool appears to earn its place.

Completeness4/5

The surface covers the core lifecycle: upcoming dates, events, documents, change feed, watchlist, follow/unfollow, calendar plan/ack, and status. Minor gaps may exist around explicit event search/filtering or calendar cancellation, but agents can likely work around them. Overall coverage is strong for the stated domain.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues