earnings-watch

Earnings Watch

CLI、Python API、MCP サーバーを通じて、検証済みの発行体の決算カレンダーと決算関連文書を提供します。モデルは日付を提案し、決定論的なチェックによって、引用された根拠と発行体、期間、タイミングの整合性を確認します。決算説明会の開始時刻が、通知なしに公開時刻として扱われることはありません。

カレンダーの更新は任意です。Earnings Watch は操作計画を作成し、お使いの MCP クライアントが外部の Outlook アプリを使って適用し、確認済みの書き込みを記録します。このパッケージでは、Microsoft の認証情報やカレンダー SDK は不要です。

メンテナンスされているソースとコントリビューション：benjamin-di/earnings-watch。ソースとリリースを参照してください。

Python 3.12 以降が必要です。公開済みパッケージは uv tool install earnings-watch でインストールするか、ソースチェックアウトから開発してください。

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

この例では予約済みドメインと架空のデータを使用しています。取得する前に、ソース URL と発行体のメタデータを置き換えてください。発行体の一覧やマーケットデータのサブスクリプションは同梱されていません。

メンテナンスとモデル

サービスは SQLite を読み取り、個人のフォロー情報や台帳を更新します。発行体のページを取得したり、モデルを呼び出したりすることはありません。メンテナンスは別途実行してください。

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

デフォルトのバックエンドは none です。既存の日付を保持しながら、公式の決算発表プロバイダーのポーリングを続けます。新しい日付を抽出するには、Claude Code または Codex CLI をインストールしてサインインし、earnings-watch.toml で設定してください。

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

サポート対象の最小バージョンは Claude Code 2.1.312 と Codex 0.164.0 です。earnings-watch doctor --live を実行すると、機能と任意のモデルカナリアを確認できます。このパッケージにはログインフローがありません。モデルの使用量には、CLI アカウントの制限と利用規約が適用されます。明示的なサインイン拒否またはアカウント制限による拒否が発生した場合、あるいは設定済みの Codex エンドポイントが、出力を生成する前に到達不能または失敗した場合に限り、次のバックエンドを試します。タイムアウトした実行は、同じティック内では再試行されません。

Codex は --ignore-user-config を付けて実行されます。OpenAI Responses 互換のエンドポイントを経由させるには、[llm] の下で codex_base_url と codex_key_env（キーを保持する環境変数の名前）の両方を設定してください。キー自体をファイルに記載することはありません。ローカルホスト以外のエンドポイントには https:// を使用してください。Claude Code は環境から ANTHROPIC_BASE_URL と CLAUDE_CODE_MAX_RETRIES を受け取ります。そのため、再試行回数に上限を設定すると、タスクのタイムアウト前に利用できないエンドポイントを失敗させることができます。

MCP

初期化後のローカルクライアント設定：

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

ツール	用途
earnings_upcoming	タイミングの不確実性を含む、範囲を限定した今後の日付
earnings_get_events	根拠、改訂履歴、最近の履歴
earnings_documents	公式の決算関連文書へのリンクと検証状況
earnings_changes	カーソルベースの公開変更フィード
earnings_watchlist	フォロー情報と登録状況
earnings_watch	発行体をフォローし、登録をキューに追加するか、曖昧さを解消
earnings_unwatch	手動で追加したフォローを削除
earnings_calendar_plan	任意の外部カレンダー操作を計画
earnings_calendar_ack	署名済みの計画に基づき、確認済みの操作を記録
earnings_status	カタログとメンテナンスの状況

プロンプト：earnings_briefing、results_brief、sync_to_my_outlook。リソース：earnings://upcoming.ics。正確な時刻を設定するには、時刻とタイムゾーンの根拠を検証する必要があります。そうでない場合、カレンダーの予定はすべて終日として登録されます。Outlook の操作に出席者が含まれることはありません。

スタンドアロン HTTP モードでは、/users/<id>/mcp でユーザーごとに個別のベアラートークンを使用します。ゲートウェイモードでは、/mcp で、設定済みのバックエンド用ベアラーと、認証ゲートウェイから渡される不変のサブジェクトヘッダーを受け付けます。これらのモードは信頼境界が別々です。権限を参照してください。

接続ページと通知

オプションの接続ページでは、「近日予定」「企業一覧」「通知」「カレンダー」をまとめて利用できます。サインインして企業を追加するか、保有銘柄のインポートをプレビューしてから、非公開のカレンダーフィードを購読します。事実情報は共有されますが、保有銘柄、ウォッチリスト、ミュート設定、環境設定、受領記録は個人用です。

新規ユーザーには、結果公開時の通知が有効になっています。デイリーブリーフと緊急変更の通知はオプションです。メールの送信には、別途設定したトランスポートが必要です。サーバーと取得ワーカーがメッセージを直接送信することはありません。

Docker Compose

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

返されたトークンは安全な場所に保存し、その人の HTTP パスでのみ使用してください。サーバーはデフォルトでループバックにバインドされます。両方のイメージは uid 1000 で実行されます。Compose は機能を削除し、特権の昇格を防止し、ルートファイルシステムを読み取り専用でマウントします。ワーカーのイメージには固定バージョンのモデル CLI が含まれています。backends=["none"] の場合、認証ボリュームはオプションです。モデルのメンテナンスを有効にする前に、読み取り専用ワーカーの外部で CLI にサインインするよう設定してください。認証ファイルとデータボリュームを他のユーザーから保護してください。

CLI では --config PATH、--person ID、--json を使用します。設定は TOML と EARNINGS_WATCH_* 環境変数から読み込まれます。運用ガイド、アーキテクチャ、プロバイダー、設計上の決定事項を参照してください。

開発

make check は、ロックファイルのずれ、lint、フォーマット、型、依存関係の境界、オフラインテスト、wheel／ソースのビルドを検証します。テストでは、合成発行者と、ネットワーク／モデル／アカウントの境界を模した偽物を使用します。実際のモデルやページを使ったチェックは、別途運用担当者が実施するゲートです。CONTRIBUTING.md と SECURITY.md をお読みください。

完了した機能、リリースゲート、切り替え前に必要な本番アダプターの作業については、実装状況を参照してください。