Matomo JS

Matomo JS

Matomo Analytics 向けのモダンな JavaScript／TypeScript クライアントライブラリです。

プロジェクトの状況

⚠️ このプロジェクトはまだ開発中です。 ライブラリの開発と改良を続ける中で、API が今後変更される可能性があります。本番環境での使用にはご注意ください。

概要

このモノレポには、Matomo Analytics と連携するための JavaScript／TypeScript ライブラリが含まれています。TypeScript で構築され、最適な開発体験を実現するために Nx モノレポとして構成されています。

パッケージ

レポートクライアント（@mj-kiwi/matomo-client）

型安全なインターフェースを備えた、Matomo Reporting API 用の TypeScript クライアントです。このパッケージを使うと、Matomo の Reporting API エンドポイントを簡単に利用できます。

特長

• モダンな Promise ベースの API
• 完全な型定義による TypeScript サポート
• 柔軟に利用できるモジュール設計
• ツリーシェイキング対応（必要なものだけをインポート）

利用可能なモジュール

レポートクライアントには、以下を含む、Matomo API の主要なすべてのエンドポイント向けモジュールが用意されています。

• Core - コアレポート機能（core）
• API - 一般的な API 操作（api）
• SitesManager - サイト管理用メソッド（sitesManager）
• AbTesting - A/B テスト機能用メソッド（abTesting）
• Actions - ページビュー、コンテンツのトラッキング（actions）
• ActivityLog - ユーザーアクティビティログ（activityLog）
• AdvertisingConversionExport - 広告コンバージョンのエクスポート（advertisingConversionExport）
• Annotations - アノテーションの管理（annotations）
• ConnectAccounts - 他のプラットフォームとの連携（connectAccounts）
• Contents - コンテンツのインタラクションデータ（contents）
• CoreAdminHome - 管理タスク（coreAdminHome）
• CrashAnalytics - JavaScript エラーのトラッキング（crashAnalytics）
• CustomAlerts - カスタムアラートの定義（customAlerts）
• CustomDimensions - カスタムディメンションのトラッキング（customDimensions）
• CustomJsTracker - カスタム JS トラッカー機能（customJsTracker）
• CustomReports - カスタムレポートの管理（customReports）
• CustomVariables - カスタム変数データ（customVariables）
• Dashboard - ダッシュボードの管理（dashboard）
• DevicePlugins - ブラウザープラグインの統計（devicePlugins）
• DevicesDetection - 訪問者のデバイスレポート（devicesDetection）
• Events - イベントのトラッキングと分析（events）
• Feedback - ユーザーフィードバックの送信（feedback）
• FormAnalytics - フォームのインタラクションデータ（formAnalytics）
• Funnels - コンバージョンファネルの分析（funnels）
• Goals - コンバージョン目標と EC（goals）
• HeatmapSessionRecording - ヒートマップとセッション録画（heatmapSessionRecording）
• ImageGraph - 静的 PNG グラフの生成（imageGraph）
• Insights - 分析インサイトの生成（insights）
• LanguagesManager - 翻訳と言語設定（languagesManager）
• Live - リアルタイムの訪問者データ（live）
• Login - 認証メソッド（login）
• MarketingCampaignsReporting - マーケティングキャンペーンデータ（marketingCampaignsReporting）
• MediaAnalytics - メディアエンゲージメント統計（mediaAnalytics）
• MobileMessaging - モバイルメッセージング連携（mobileMessaging）
• MultiChannelConversionAttribution - マルチチャネルアトリビューション（multiChannelConversionAttribution）
• MultiSites - 複数サイトの概要データ（multiSites）
• Overlay - ページオーバーレイレポート（overlay）
• PagePerformance - ページ読み込み指標（pagePerformance）
• PrivacyManager - データプライバシーの管理（privacyManager）
• Referrers - トラフィックソース（referrers）
• Resolution - 画面解像度レポート（resolution）
• RollUpReporting - ロールアップレポート機能（rollUpReporting）
• ScheduledReports - スケジュール済みレポートの管理（scheduledReports）
• SearchEngineKeywordsPerformance - SEO キーワード（searchEngineKeywordsPerformance）
• SegmentEditor - セグメントの管理（segmentEditor）
• Seo - SEO ランキングレポート（seo）
• TagManager - タグマネージャー機能（tagManager）
• Tour - ガイド付きツアー機能（tour）
• Transitions - 訪問者のナビゲーション経路（transitions）
• TwoFactorAuth - 二要素認証の管理（twoFactorAuth）
• UserCountry - 地理データ（userCountry）
• UserId - ユーザー ID のトラッキング（userId）
• UserLanguage - 訪問者の言語レポート（userLanguage）
• UsersFlow - ユーザーフローの可視化（usersFlow）
• UsersManager - ユーザー管理（usersManager）
• VisitFrequency - 訪問者頻度の指標（visitFrequency）
• VisitTime - 訪問時間レポート（visitTime）
• VisitorInterest - エンゲージメント指標（visitorInterest）
• VisitsSummary - 訪問指標と統計（visitsSummary）

Matomo API を幅広くカバーする、さらに多くのモジュールが用意されています。

MCP サーバー（@mj-kiwi/matomo-mcp-server）

AI エージェント（大規模言語モデルなど）と Matomo アナリティクスをつなぐブリッジとして機能する、Model Context Protocol（MCP）サーバーです。このパッケージは、Matomo Reporting API の機能を MCP ツールとして公開します。

特徴

• Model Context Protocol の仕様を実装しています
• AI エージェントに Matomo データへの直接アクセスを提供します
• 環境変数を使って簡単に設定できます
• Matomo API の構造を反映したモジュール式の設計です

実装状況

現在、MCP サーバーでは Matomo API の47モジュール中4モジュール（8.5%）が実装されています。

• SitesManager
• TagManager
• Tour
• UserId

現在、さらに多くのモジュールを積極的に実装しています。

はじめに

前提条件

• Node.js（v18以降を推奨）
• npm、yarn、または pnpm

インストール

# Install the reporting client
npm install @mj-kiwi/matomo-client

# Or with yarn
yarn add @mj-kiwi/matomo-client

# Or with pnpm
pnpm add @mj-kiwi/matomo-client

基本的な使い方

import { ReportingClient } from '@mj-kiwi/matomo-client';

// Create a reporting client instance
const client = new ReportingClient({
  baseUrl: 'https://your-matomo-instance.com',
  apiKey: 'your-api-key', // if using token-auth
});

// Fetch site analytics data
const siteData = await client.core.getVisits({
  idSite: 1,
  period: 'day',
  date: 'yesterday',
});

ライセンス

MIT