Fullmention - Track how AI recommends your brand

@fullmention/mcp-server

FullMention MCP サーバーは、LLM や AI エージェント（Claude Desktop、Cursor、カスタムエージェントネットワークなど）が FullMention Public API と直接やり取りできる、安全で高性能なゲートウェイを提供します。

FullMention のステートレスなシミュレーション実行をネイティブな MCP ツールおよび構造化されたリソースとして公開することで、AI モデルは一括分析の実行、進捗の追跡、結果の取得、可視性指標の分析をシームレスに行えます。

---

メモ

📊 明示的なランキングシステム

FullMention の AI 推薦結果では、フラットなランキングリスト（brandRankings、websiteRankings、productRankings）を使用します。

• 順位: これらのリストの各項目には、1 から始まる position プロパティが含まれています。1 位は LLM のコンテキスト内で最上位のおすすめ／最も目立つ候補を表し、その後に順位の低い項目が続きます。
• ルール: これらのリストの要素は、関連性と可視性の高さに基づいて厳密に並べられています。貴重な可視性情報が失われるため、これらの配列をアルファベット順に並べ替えないでください。

---

クイックスタート：AI クライアントを接続する（ローカルデスクトップ）

FullMention MCP サーバーをローカルのエディターまたはチャットクライアントに接続するには、以下の設定を使用してクライアントを構成します。

1. Claude Desktop のセットアップ

以下の設定を claude_desktop_config.json に追加します（通常、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json にあります）。

{
  "mcpServers": {
    "fullmention": {
      "command": "npx",
      "args": ["-y", "@fullmention/mcp-server"],
      "env": {
        "FULLMENTION_API_KEY": "your_fm_live_key_here"
      }
    }
  }
}

ヒント

バージョンの固定： 本番環境のワークフローに破壊的変更が影響しないように、npx で起動する際は特定の SemVer バージョンを固定することを検討してください。 "args": ["-y", "@fullmention/[email protected]"]

2. Cursor のセットアップ

1. Cursor の設定を開き、Features -> MCP に移動します。
2. + Add New MCP Server をクリックします。
3. 設定を入力します。
   • 名前： FullMention
   • タイプ： stdio
   • コマンド： npx -y @fullmention/mcp-server
4. 環境変数 FULLMENTION_API_KEY に API キーを設定します。
5. Save をクリックします。

---

コアアーキテクチャとスマートシールド

FullMention MCP サーバーは、API の利用枠とクレジットの予算を自動的に保護する、AI に安全で リソース効率に優れた設計を一から採用しています。

• 🛡️ メモリ内クエリシールド： クエリ応答をキャッシュ（TTL は 60 秒）し、エージェントのループによる不要なリクエストから外部 API のレート制限を保護します。
• 🚦 ステータスポーリングのガードレール： 実行中の一括処理ステータスに対する短時間での連続ポーリングを検出します。AI エージェントが 8 秒以内にサーバーをポーリングすると、サーバーはネットワーク呼び出しをインターセプトし、[POLLED_TOO_FAST_CACHED_WARNING] とともにキャッシュ済みの状態を返します。これにより、ネットワークのオーバーヘッドと API への負荷を軽減します。
• 📊 サーバー側のシェア・オブ・ボイス： get_share_of_voice によりブランド可視性の計算をサーバー側で自動化し、LLM による数学的な幻覚を完全に防ぎます。
• 🚀 サーバー側のトークン最適化： format: "markdown" パラメーターに対応しています。冗長な JSON をそのまま LLM に送る代わりに、MCP サーバーがデータを高密度で圧縮した Markdown テーブルに自動的にまとめ、トークンのオーバーヘッドを大幅に削減して LLM の入力コストを大きく抑えます。

---

クラウドデプロイで機能を拡張する（SSE モード）

SaaS やクラウドのアーキテクチャ向けに、FullMention MCP サーバーは SSE（Server-Sent Events）HTTP トランスポートに標準で動的に対応しています。

SSE モードでの起動：

ポート 3000（または設定済みの PORT / FULLMENTION_MCP_PORT）で HTTP ゲートウェイを起動するには、次のコマンドを実行します。

npx -y @fullmention/mcp-server --sse

100% セキュアなメトリクスエンドポイント

SSE モードでホストしている場合、以下から診断情報とリアルタイムのキャッシュ性能指標を確認できます。

curl http://localhost:3000/diagnostics

---

ツールとパラメーターの詳細リファレンス

FullMention MCP サーバーは、7 つの専用ツールを公開しています。以下に、各ツールの完全なパラメータースキーマとレスポンス形式を示します。

📊 システムとクォータのツール

1. get_status

FullMention プラットフォームの動的なシステムとエンジンのステータスを取得します。

• パラメーター： なし。
• レスポンス（JSON）：

  {
    "status": "operational",
    "engines": {
      "openai": "operational",
      "openaiMini": "operational",
      "gemini": "operational"
    }
  }
  

2. get_quota

アカウントのクォータ上限と現在の使用状況を取得します。

• パラメーター：
  • bypassCache (boolean, optional)：true に設定すると、キャッシュをバイパスします。
• レスポンス（JSON）：

  {
    "limit": 10000,
    "used": 2350,
    "extra": 0,
    "remaining": 7650
  }
  

3. get_usage_stats

予算に関する警告とともに、クォータとクレジットの詳細な統計を取得します。

• パラメーター：
  • bypassCache (boolean, optional)：true に設定すると、キャッシュをバイパスします。
• レスポンス： 残りのクレジット、月間上限、現在のクレジット料金表をまとめた Markdown。

---

🚦 シミュレーションと実行

4. trigger_run

非同期のステートレスなシミュレーション実行を開始します。

• パラメーター：
  • keywords (array of strings, required)：シミュレーションするキーワードのリスト（最大 500 件）。
  • engines (array of strings, required)：対象とする AI 検索エンジン（例：["openai", "openai-mini", "gemini"]）。
  • country (string, required)：国のコンテキスト（例："Denmark" または "United States"）。
  • language (string, required)：言語のコンテキスト（例："Danish" または "English"）。
  • location (string, optional, nullable)：任意の特定都市のコンテキスト（例："Copenhagen"）。
  • fanout (boolean, optional)：ウェブ検索のファンアウトを有効にします（キーワードごとにクレジットコストが 1 加算されます）。
  • webhookUrl (string, optional, nullable)：実行完了時にコールバックする、任意の完全修飾 HTTP/S URL。
  • idempotencyKey (string, optional)：実行の重複を防ぐ一意の文字列。
• レスポンス（JSON）：

  {
    "id": "run_987abc",
    "status": "queued",
    "progress": {
      "status": "queued",
      "totalRequests": 10,
      "completedRequests": 0,
      "failedRequests": 0,
      "percentage": 0
    },
    "estimatedCredits": 10,
    "createdAt": "2026-06-10T22:00:00.000Z",
    "completedAt": null,
    "expiresAt": "2026-06-11T22:00:00.000Z",
    "statusUrl": "https://api.fullmention.com/v1/runs/run_987abc"
  }
  

5. get_run_status

runId を使用して、実行の詳細、進行状況、結果を取得します。

• パラメーター：
  • runId (string, required)：実行の ID。
  • format ("compact" | "raw" | "markdown", optional, default: "compact")：レスポンス形式。
  • bypassCache (boolean, optional)：true の場合、キャッシュをバイパスします。
• レスポンス： （format: "markdown" の場合）詳細をまとめた Markdown テーブル、または実行と結果を簡潔にまとめた JSON 表現。

6. get_fanout_sources

特定の推奨結果について、ページネーションに対応したウェブソースと検索クエリの全件を取得します。

• パラメーター：
  • runId (string, required)：バッチ実行の ID。
  • resultId (string, required)：結果スナップショットの ID。
  • limit (number, optional)。
  • cursor (string, optional)。
• レスポンス（JSON）：

  {
    "data": [
      {
        "domain": "ahrefs.com",
        "url": "https://ahrefs.com/blog/best-seo-tools/",
        "title": "Best SEO Tools for 2026",
        "snippet": "Read our comprehensive review of top SEO suites...",
        "crawledAt": "2026-06-10T22:05:00.000Z"
      }
    ],
    "meta": {
      "nextCursor": "eyJza2lwIjoxfQ=="
    }
  }
  

7. get_share_of_voice

完了した実行について、シェア・オブ・ボイス（%）と平均順位をサーバー側で計算します。

• パラメーター：
  • runId (string, required)：分析対象の完了済み実行 ID。
  • brands (array of strings, optional)：比較対象とするブランドを指定します。
  • format ("json" | "markdown", optional, default: "markdown")。
  • bypassCache (boolean, optional)。
• レスポンス： Markdown の表形式レポート、または可視性の割合を含む集計済み JSON。

---

公開されているネイティブリソース

AI モデルは、以下の構造化されたネイティブリソースを直接クエリできます。

• fullmention://schema/openapi — 機械可読な API コントラクト。
• fullmention://runs/{runId} — 特定の完了済み実行の要約 Markdown レポート。

---

AI ガイド付きプロンプト

MCP サーバーに含まれる、事前定義済みのエージェントテンプレート：

• brand-analysis：完了済み実行の結果における競合他社の出現状況を分析します。
• credit-optimization：キーワード数とエンジン数に基づいて、計画中の実行に必要なクレジットコストを助言します。
• gap-analysis：実行結果で競合他社が表示されている一方、自社ブランドが表示されていないキーワードのギャップを分析します。
• citation-coverage：実行におけるドメインとウェブソースを対応付けます。
• category-dominance：実行における AI の推奨に基づいて、カテゴリー内での優位性を示します。
• executive-digest：実行データから週次の経営 KPI サマリーを生成します。