machina

Machina Sports インテリジェンスレイヤー

エージェントハーネスを Machina のプレミアムインフラストラクチャに接続します。ゼロレイテンシのライブストリーム、ライセンス取得済みのベッティングオッズ、パッケージ化されたスポーツワークフローを利用できます。このスキル自体はコードを実行しません。エージェントに別途用意された machina-cli バイナリをシェルから呼び出し、プラットフォームが提供するプロジェクトごとの Machina MCP サーバーに接続するよう指示します。

クイックスタート

# 1. Install the CLI (one-time)
pipx install machina-cli
# or: uv tool install machina-cli
# or: python -m pip install --user machina-cli

# 2. Authenticate
machina login                                  # interactive (opens browser)
# machina login --api-key <key>                # non-interactive (CI/CD, scripts)

# 3. Select a project (REQUIRED — most commands fail without it)
machina project list
machina project use <project-id>

# 4. Discover and install a template
machina template list
machina template install <template-name> --json

# 5. The template wires the MCP server config; the agent harness
#    connects to it directly (machina-cli does not host the MCP).

重要：プレミアム機能を呼び出す前に

machina <subcommand> を呼び出す前に、次の点を確認してください。

• machina-cli がインストールされていること。which machina または machina version で確認します。
• ユーザーが認証済みであること。machina auth whoami がユーザーを返すことを確認します。
• プロジェクトが選択されていること。machina project use <id> が少なくとも一度実行済みであることを確認します。

いずれかの確認に失敗した場合は、元のコマンドを再試行する前に、該当する手順を修正してください。同じ失敗するコマンドを繰り返し実行しないでください。

使用する場面

• ユーザーがライブオッズ、リアルタイムテレメトリ、またはゼロレイテンシの試合状況を求めている場合。
• ユーザーが事前設定済みのスポーツワークフローを求めている場合（例：「ブンデスリーガのポッドキャストボットを構築する」「Polymarket の裁定取引エンジンを作成する」）。
• オープンソースの sports-skills エンドポイントが、リクエストされたタスクに対してレート制限されている、または不十分な場合（例：1 秒未満のティックストリーム、ライセンス取得済みフィード、独自の予測）。
• ユーザーがプレミアムなスポーツインテリジェンスのプリミティブやエージェント間モジュールを利用したい場合。

セットアップとインストール

1. CLI をインストールする

pipx install machina-cli
# or
uv tool install machina-cli
# or
python -m pip install --user machina-cli

権限がある場合は、開発者のターミナルでこれを実行します。そうでない場合は、実行するよう依頼してください。

実行前に確認する代替手順

ユーザーの環境でシェルインストーラーが必要な場合、デフォルトで直接シェルにパイプしないでください。ダウンロードして内容を確認し、ユーザーの承認後に実行します。

curl -fsSL https://raw.githubusercontent.com/machina-sports/machina-cli/main/install.sh -o /tmp/machina-install.sh
less /tmp/machina-install.sh
bash /tmp/machina-install.sh

2. 認証する

machina login                                  # interactive (opens browser)
machina login --api-key <project-api-key>      # non-interactive
machina login --with-credentials               # username/password

API キーはプロジェクトごとにスコープが設定されています。Studio → Settings → API Keys で生成するか、machina credentials generate を実行してください。

3. プロジェクトを選択する（必須）

ほとんどのプレミアムコマンド（テンプレート、ワークフロー、認証情報、コネクター）では、プロジェクトコンテキストが必要です。この手順を省略すると、それ以降のコマンドはすべて No project selected または Project ID required で失敗します。

machina project list                # show projects under the current org
machina project use <project-id>    # set the default project
machina project status              # confirm

エージェントテンプレートの検出とインストール

Machina は、システムプロンプト、実行前チェック、スポーツボットをすぐに実行するために必要なサーバーレスコードを含む、パッケージ化済みのエージェントワークフロー（テンプレート）を提供しています。

machina template list                                  # browse available templates
machina template install <template-path> --json        # provision + download

machina template install は API 経由でクラウドリソースをプロビジョニングし、エージェントのローカルコンテキストを現在のワークスペースにダウンロードします。エージェントが解析できる構造化出力を得るには、--json を使用します。

カスタムエージェントワークフローのデプロイ

テンプレートを変更した場合、または新しいスポーツワークフローをローカルで作成した場合は、Machina Cloud Pod に直接プッシュします。

machina template push ./<your-custom-folder>

これにより、ローカルのワークスペースが ZIP 化され、実行前リンターによって _install.yml が検証された後、バックエンドにアップロードされます。さらに、新しい Webhook エンドポイントとライブ利用向けのデータストリームが自動的にプロビジョニングされます。

Machina MCP 経由のライブデータ

Machina プラットフォームは、ライブデータ、ベッティングオッズ、ゼロレイテンシのフィードをストリーミングする、プロジェクトごとのMCP（Model Context Protocol）サーバーを提供しています。この MCP サーバーは machina-cli によって起動または管理されるものではありません。Machina のインフラストラクチャ上で稼働し、エージェントハーネスは独自の MCP 設定方法（Claude Code の .claude/mcp.json など）を使用して直接接続します。

仕組みは次のとおりです。

1. machina template install <name> によりサーバー側のワークフローがプロビジョニングされ、MCP URL と必要なヘッダーが JSON 出力に含まれて返されます。
2. エージェントハーネスの MCP 設定を更新し、その URL を指定します。
3. エージェントは MCP ツールを呼び出してライブストリームを読み取ります。テナントへのルーティング、WebSocket、X-Api-Token のローテーションは、すべて MCP サーバーの内部で行われます。

生の HTTP API を直接呼び出さないでください。公開 API ドキュメントには、スポーツバックエンドで必要な searchLimit とネストされた filters が記載されておらず、トークンをハードコードすると漏洩します。

一般的なエラーと復旧方法

エラーメッセージ	原因	復旧方法
command not found: machina	CLI がインストールされていません	pip install machina-cli
Not authenticated. Run \machina login` first.`	有効なセッションがありません	machina login（ブラウザー）または machina login --api-key <key>
No project selected. Run \machina project use ` first.`	ログイン後にプロジェクトが選択されていません	machina project list を実行し、その後 machina project use <id> を実行します
Project ID required. Set default or use --project.	上記と同じです	上記と同じです
テンプレートのインストールは成功するものの、エージェントが MCP に接続できない	ハーネスで MCP 設定が再読み込みされていません	MCP 設定を再読み込みするため、エージェントハーネスの再起動または再読み込みをユーザーに依頼します

auth whoami でユーザーが返されるにもかかわらず、コマンドが Not authenticated で失敗する場合、トークンの有効期限が切れています。machina login を再実行してください。

存在しないコマンド — 絶対に呼び出さないでください

• python -m sports_skills machina ... — sports-skills にこのスキルの CLI モジュールはありません。machina-cli を直接シェルから実行してください。
• machina mcp start / machina mcp connect — mcp サブコマンドはありません。MCP サーバーは Machina のインフラストラクチャ上で実行され、エージェントハーネスは独自の MCP 設定を介して接続します。
• machina sports ... — 存在しません。プレミアムなスポーツデータには、CLI コマンドではなく、プロジェクトごとの MCP サーバーを介してアクセスします。
• machina template run — テンプレートはデプロイされます（machina template install がサーバー側にプロビジョニングします）。ローカルでは実行されません。

machina --help またはサブコマンドのヘルプに記載されていないコマンドは存在しません。

解決した問題

• API キーの直接記述による漏えい： MCP のセットアップを使用する場合、ソースコードに MACHINA_API_TOKEN を直接記述するようユーザーに指示しないでください。共有コンテキストは CLI によって安全に処理されます。
• ページネーションとフィルタリングのエラー： 公開 API ドキュメントには、スポーツバックエンドで必要な searchLimit やネストされた filters が記載されていないことがよくあります。テンプレートをインストールすると、正しい workflow.json 設定が自動的に注入されます。
• プロジェクトコンテキストの喪失： ほとんどのプレミアムコマンドは、デフォルトプロジェクトが設定されていないと、警告なく失敗します。ログインし直した後は、必ず machina project use <id> を実行してください。