ezstat-mcp-server

EzStat MCP サーバー

EzStat 用のスタンドアロンな Model Context Protocol サーバーです。 Claude／Cursor／MCP 互換のエージェントなら、メトリクスをネイティブに送信・読み取りできます。コピー＆ペーストも、ダッシュボードへの切り替えも不要です。「エージェント自身が書き込み、読み取るメトリクス」という位置づけを支える製品です。コードに触れるすべてのエージェントが、オブザーバビリティにもアクセスできます。

このサーバーは stdio（ローカルのエージェントランナーで標準的なトランスポート）と、https://mcp.ezstat.dev のホステッドエンドポイントとして streamable HTTP に対応し、同じ7つの特化型ツールを公開します。各ツールの説明はエージェント向けに記述されているため、モデルはいつ呼び出すべきかを把握できます。

ホステッドエンドポイント — インストール不要

EzStat API キーだけでホステッド streamable-HTTP エンドポイントに接続できます。npm のインストールも、ローカルプロセスも不要です。

{
  "mcpServers": {
    "ezstat": {
      "type": "http",
      "url": "https://mcp.ezstat.dev",
      "headers": {
        "Authorization": "Bearer ezkey_your_api_key_here"
      }
    }
  }
}

• マルチテナント：すべてのリクエストに あなたの キーを Authorization: Bearer <ezkey> として含めます。サーバーは独自のキーを保持せず、各接続から参照できるのはそのアカウントのみです。
• ディスカバリーは無料：initialize と tools/list はキーなしで動作するため、クライアントやレジストリの検査ツールは設定前にツールの一覧を確認できます。
• ツールの呼び出しにはキーが必要です：キーなし（または無効なキー）で呼び出すと、エージェントに送信すべき内容を伝える明確なインバンドの MCP ツールエラーが返されます。ハングやクラッシュは発生しません。
• ステートレス：セッションは発行も要求もされません。各 POST はそれだけで完結します。

このホステッドエンドポイントは、MCP レジストリのホステッド／リモート掲載要件（Smithery のホステッドサーバーパスなど）も満たしています。server.json の remotes エントリーを参照してください。

以下の stdio トランスポートも引き続き完全にサポートされており、独自のランナーでサーバーをローカル実行する場合に適しています。

ツール

ツール	機能
track_metric	アプリが「生成した」メトリクスのポイントを記録します。カウンター（+N、デフォルトは+1）またはゲージ（例：42.5 ms）に対応します。
ask_ezstat	メトリクスについて自然言語で質問します（エージェントが読み取るための経路です）。
read_stat	統計情報を構造化して読み取ります。指定期間の最新値、系列、概要（件数／最小値／最大値／平均値／合計）を取得します。
list_stats	アカウントのメトリクス（名前、種類、説明）を一覧表示します。
create_alert	統計情報に対する Webhook アラートを作成します（しきい値／変化率／ハートビート／継続時間）。
list_alerts	アカウントのアラート（ID、統計情報、条件、チャネル、有効状態、最終発火）を一覧表示します。
delete_alert	ID を指定してアラートを削除します。

ツールの説明はエージェントの推論に合わせて調整されています。src/server.ts を参照してください。

インストール（Claude Desktop / Claude Code / Cursor）

1行でインストール（npm/pnpm）

# pnpm
pnpm add -g ezstat-mcp-server

# npm
npm install -g ezstat-mcp-server

MCP クライアントの設定

Claude Desktop（macOS/Linux の場合は ~/.config/Claude/claude_desktop_config.json、 Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "ezstat": {
      "command": "ezstat-mcp-server",
      "env": {
        "EZSTAT_API_KEY": "ezkey_your_api_key_here"
      }
    }
  }
}

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "ezstat": {
      "command": "ezstat-mcp-server",
      "env": {
        "EZSTAT_API_KEY": "ezkey_your_api_key_here"
      }
    }
  }
}

API キー（「ezkey」）は https://ezstat.dev で取得してください。

Smithery

npx -y @smithery/cli install ezstat-mcp-server --client claude

または https://smithery.ai/server/ezstat-mcp-server にアクセスして、インストールをクリックしてください。

EzStat について

EzStat は、シンプルなホスト型メトリクスサービスです。HTTP POST を 1 回送るだけで、リアルタイムのグラフが表示されます。SDK も、コレクターデーモンも、YAML も、ダッシュボードビルダーも不要です。カウンターと値／ゲージ統計は、最初の POST で自動的に作成されます。グラフ、共有／埋め込み、CSV／JSON エクスポートが標準搭載されており、Ask-Your-Data（ライブ）は、ご自身のメトリクスについての平易な英語の質問に回答します。回答をお届けする前に、すべての数値を取得したデータと照合して検証します。

追跡する統計の数に応じた月額固定料金は $19 / $49 / $149 です。また、カード登録が必要な無料プランもあります（料金はかかりません。お支払い前にデータをライブで確認できます）。データはご自身のものです。いつでもエクスポートでき、いつでもキャンセルできます。異常検出とメトリクスの相関分析は利用可能です。まだ提供開始していない機能（アラート、週次ダイジェスト）は販売せず、サイト上で 近日公開 と表示しています。ライブで確認できるものは、すでに動作する機能です。

StatHat からの移行

api.stathat.com への呼び出しが止まり、ダッシュボードが表示されなくなった場合：EzStat は StatHat のワイヤーフォーマットに対応しています。同じ /ez、/c、/v エンドポイント、同じパラメーター、同じレスポンスです。通常、移行は 1 行変更するだけです。

# before
curl -X POST https://api.stathat.com/ez -d "stat=messages sent" -d "ezkey=KEY" -d "count=1"
# after — change the host, use your EzStat key; stats auto-create
curl -X POST https://api.ezstat.dev/ez -d "stat=messages sent" -d "ezkey=EZSTAT_KEY" -d "count=1"

注意点が 1 つあります。重要なのは、ステータスコードではなくレスポンス本文を確認することです。 ワイヤーフォーマットが StatHat のものと同じため、書き込みが拒否された場合（古いキー、誤ったキー、クォータ超過）でも HTTP 200 が返され、判定結果は本文に含まれます。{"status":200,"msg":"ok"} は記録済み、{"status":"error","msg":"..."} は未記録を意味します。変更していない StatHat クライアントはこれらを成功として報告するため、グラフには古いデータが表示され続け、問題が起きているように見えません。新しいコードでは /ez に X-EzStat-Strict: 1 を指定し、実際の HTTP ステータスコードを取得してください。（このサーバーはすでに適切に処理しており、HTTP コードにかかわらず、本文が error の場合は失敗として扱います。）切り替え後、ezstat.dev/tools/ezstat-verify.py でポイントが到着していることを確認してください。手順は ezstat.dev/docs#verify に記載されています。

ほとんどの StatHat クライアントライブラリでは、ベース URL を 1 行で変更できます。StatHat の CSV／JSON エクスポートを保存してありますか？インポーターで統計を再作成し、履歴データを補完できます（ファイルごとに 8 MB／500k ポイント）。詳しいガイド：docs/stathat-migration.md · ezstat.dev/migrate/stathat。移行特典として、ライブで確認できる無料プラン、12 か月間の価格固定、最初の 25 件の移行に対する手厚いインポートサポートもあります。

エージェントネイティブなメトリクスを実現する理由

コーディングエージェントはデプロイ、テスト、リリースを行います。数値の追跡と読み取りも、エージェント自身が行うべきです。それを実現するのがこのサーバーです。メトリクスをエージェント自身が記録し、読み取ります。理由：docs/agent-native-metrics.md · StatHat／StatFlow／Datadog との比較：ezstat.dev/vs。

環境変数

変数	必須	デフォルト	備考
EZSTAT_API_KEY	yes	—	EzStat API キー（「ezkey」）。ハードコードしないでください。ログに記録しないでください。
EZSTAT_BASE_URL	no	https://api.ezstat.dev	ステージング／セルフホスト向けの上書き。
EZSTAT_TIMEOUT_MS	no	10000	リクエストごとのタイムアウト（ミリ秒）。
EZSTAT_INGEST_PATH	no	/api/ez	EZ エンドポイントをプロキシする場合の上書き。
EZSTAT_QUERY_PATH	no	/api/v1/query	Ask-Your-Data のパス。
EZSTAT_STATS_LIST_PATH	no	/api/v1/stats	統計一覧のパス。

スターター用の .env.example が同梱されています。

EzStat との通信方法

各ツールは、実際の EzStat API ルートに対応しています（すべて EzStat API キーで認証します）。

ツール	メソッド	パス	認証
track_metric	POST	/api/ez	JSON 本文内の ezkey
ask_ezstat	POST	/api/v1/query	Authorization: Bearer <ezkey>
read_stat	GET	/api/v1/stats/:name	Authorization: Bearer <ezkey>
list_stats	GET	/api/v1/stats	Authorization: Bearer <ezkey>
create_alert	POST	/api/v1/alerts	Authorization: Bearer <ezkey>
list_alerts	GET	/api/v1/alerts	Authorization: Bearer <ezkey>
delete_alert	DELETE	/api/v1/alerts/:id	Authorization: Bearer <ezkey>

• track_metric は StatHat 互換の EZ 取り込み API（{"ezkey","stat","count"?,"value"?,"t"?}）を呼び出します。 カウンターの動作：count と value の両方を省略すると、count=1（カウンター +1）が記録されます。
• ask_ezstat は Ask-Your-Data（{"query":"..."} → {answer, data, intent, ...}）を呼び出します。 これはエージェントの読み取りパスです。使用状況の追跡では、エージェントによる読み取りとしてカウントしてください。
• read_stat は、統計情報の最近の時系列データと概要を返します。ウィンドウを指定するには from／to（Unix 秒。HTTP 境界で ISO 8601 に変換）を渡します。バケット幅は要求された期間に応じて自動的に決まります（≤6h → 分、≤7d → 時、>7d → 日）。
• list_stats はアカウントの統計情報を返します。type を渡すと、counter または value で絞り込めます。

ローカルでのビルドと実行

pnpm install
pnpm build       # tsc → dist/
pnpm start       # node dist/index.js  (stdio MCP server)
pnpm test        # vitest run  — fully mocked network, no real HTTP
pnpm dev         # tsx watch src/index.ts

pnpm start を実行するには、EZSTAT_API_KEY を設定する必要があります。設定されていない場合、明確なエラーを表示してサーバーは終了します（キーがログに記録されることはありません）。

セキュリティ

• API キーを読み取るのは EZSTAT_API_KEY からのみです。ハードコードしたり、表示したりすることはありません。
• すべてのエラーメッセージから機密情報を除去します。API キーがツールの結果に含まれることはありません。
• HTTP エラーには、安定した機械可読な code（unauthorized、rate_limited、timeout、not_found、server_error、...）と、安全に伝えられる人間可読な message が含まれます。
• テストではネットワークをモックするため、テストプロセスから実際の HTTP リクエストが送信されることはありません。

レジストリのメタデータ

Smithery／mcp.so／Glama への掲載情報：

• 名前：ezstat-mcp-server
• 表示名：EzStat
• 説明：任意の AI エージェントから EzStat にメトリクスを送信して読み取れます。カウンターや値を追跡し、本番環境のテレメトリについて自然言語で質問できます。
• ホームページ：https://ezstat.dev
• バージョン：0.8.0
• トランスポート：stdio（ローカル）＋ streamable-http（https://mcp.ezstat.dev でホスト）
• ライセンス：MIT
• リポジトリ：このパッケージのソース

package.json の mcp ブロックにも同じメタデータが含まれているため、レジストリのクローラーが情報を取得できます。

掲載手順（提出内容と提出先）

1. Smithery：リポジトリを GitHub にプッシュしてから、 npx -y @smithery/cli publish を実行します（またはウェブ UI から提出します）。同梱の smithery.yaml がインストールスキーマを提供します。
2. mcp.so：上記のメタデータと GitHub URL を添えて、https://mcp.so/submit から提出します。
3. Glama：https://glama.ai/mcp/submit から提出します。

このパッケージは npm に自動公開されません。リリースのレビュー後に手動で公開してください。

ライセンス

MIT。