Followin-MCP

プロジェクト概要

このプロジェクトは、暗号資産（crypto）ニュースシーン向けのイベントレベルのレコメンデーションプロトタイプと理解できます：

• 上流で Followin API + adapters.py を通じてオリジナルコンテンツを取得

• normalizer.py でオリジナルコンテンツを構造化された ContentItem に正規化

• service.py の get_personal_feed 内で、まず明示的なマルチパスリコールを行い、次にセマンティック補完（semantic supplement）を実行

• clustering.py で複数のコンテンツを同一イベントの EventCluster に統合

• ranking.py でマルチシグナルヒューリスティックランカー + MMRリランキングを使用してパーソナライズされたフィードを生成

一言でまとめると：

暗号資産ニュースシーン向けのFollowin MCPプロトタイプ：オリジナルコンテンツを構造化されたアイテムに正規化し、マルチパスリコール、セマンティック補完、イベントクラスタリング、パーソナライズされたランキングを通じて、ユーザー向けのイベントレベルのフィードを出力します。

Related MCP server: Daily News MCP Server

ディレクトリ構造

• followin_mcp/ Pythonパッケージの入り口

• followin_mcp/core/ コアビジネスロジック：アダプター、モデル、正規化、ランキング、サービス

• followin_mcp/mcp/ MCPサーバーの入り口

• followin_mcp/demo/ テストエージェントおよびWebデモ

• scripts/start_dev.sh ローカル一括起動スクリプト

• web/ フロントエンドの静的リソース

コアモジュール

• followin_mcp/core/adapters.py Followin APIアダプター層

• followin_mcp/core/models.py データモデル

• followin_mcp/core/taxonomy_rules.py タクソノミー / ルール設定

• followin_mcp/core/normalizer.py オリジナルコンテンツの正規化、エンティティ抽出、イベントタイプ識別

• followin_mcp/core/clustering.py イベントクラスタリング

• followin_mcp/core/ranking.py ユーザーレコメンデーションのランキングと解説

• followin_mcp/core/semantic_recall.py 埋め込み（embedding）インデックス作成、セマンティックリコール、アイテム類似度

• followin_mcp/core/service.py MCP / アプリケーション層向けのサービス入り口

リクエスト処理シーケンス

sequenceDiagram
    participant U as MCP client / agent
    participant M as mcp/server.py
    participant S as service.py
    participant A as adapters.py
    participant F as Followin API
    participant N as normalizer.py
    participant SR as semantic_recall.py
    participant C as clustering.py
    participant R as ranking.py

    U->>M: call tool
    M->>S: get_latest / search / get_personal_feed ...

    S->>A: fetch raw content
    A->>F: HTTP request
    F-->>A: raw payload
    A-->>S: raw items

    loop per raw item
        S->>N: normalize(raw)
        N-->>S: ContentItem\nentities / event_type / scores
    end

    S->>SR: enqueue normalized items
    SR-->>S: background indexing

    opt personal feed / semantic supplement
        S->>SR: recall(query, candidate pool)
        SR-->>S: semantic candidates / similarity
    end

    opt personal feed
        S->>C: cluster_same_event(items)
        Note over C: uses item embedding similarity
        C-->>S: EventCluster list
        S->>R: rank_for_user(user, clusters)
        Note over R: uses semantic_match_score
        R-->>S: ranked clusters
    end

    S-->>M: tool payload
    M-->>U: MCP response

処理リンク

1. MCP入り口

• mcp/server.py

  • 7つのMCPツールを公開

  • MCPの入力パラメータを service.py の呼び出しに変換

  • ContentItem / EventCluster をMCPの戻り値構造にシリアライズする役割

2. オリジナルコンテンツの取得

• service.py -> adapters.py

  • get_latest_headlines / get_project_feed / get_project_opinions / get_trending_topics 上流のページネーション機能をそのまま透過

  • get_trending_feeds / search_content 現在のスナップショット結果を直接返却

  • get_personal_feed まず明示的なマルチパスリコールとセマンティック補完を行い、その後イベントクラスタリングとパーソナライズされたランキングを実行

3. コンテンツの正規化

• normalizer.py

  • normalize(raw) で単一のオリジナルコンテンツを ContentItem に変換

  • エンティティ抽出のソース：

    • tag

    • chain keyword

    • project alias

    • token alias

    • topic alias

    • dynamic alias（軽量なエンティティ発見 / バイパスNER）

  • 出力：

    • projects / tokens / chains / topics

    • entity_sources

    • entity_confidence(ヒット方式の強度)

    • event_type

    • credibility_score(ソースの信頼度)

    • importance_score(規定ルールによる計算)

4. リコール

• ここでの「リコール」とは：

  • より大きなコンテンツプールから候補となる ContentItem を取得すること

  • その後のクラスタリング、ランキング、ページネーションに使用

• service.py のパーソナルフィードでは、まず明示的なマルチパスリコールを実行：

  • latest

  • trending

  • project

  • search

• マルチパスリコールの結果は item.id で重複排除される

  • 同じアイテムが複数パスでヒットした場合、セマンティックマッチがより強く、重要度が高く、更新時間が新しいバージョンが優先される

5. イベントクラスタリング

• clustering.py

  • 入力は ContentItem のリスト

  • 出力は EventCluster のリスト

  • クラスタリングの目的は「同一プロジェクト」や「同一トピック」ではなく「同一イベント」

  • 主なシグナル：

    • イベントタイプの互換性

    • 時間枠

    • 信頼度重み付きのエンティティ重複

    • タイトルの類似度

    • オプションのセマンティック類似度

6. パーソナライズされたランキング

• ranking.py

  • 入力は EventCluster

  • 出力はユーザーごとにランキングされたクラスターフィード

  • 主なシグナル：

    • importance_score

    • freshness_score

    • follow_affinity_score

    • interest_match_score

    • semantic_match_score

    • source_quality_score

    • risk_boost_score

  • mute_penalty

  • 最後にMMRスタイルの多様化リランキングを実行

7. Embedding

• semantic_recall.py

  • 正規化されたアイテムはまず非同期のembeddingワーカーに enqueue される

  • アイテムのembeddingはローカルのSQLite semantic_index.db に保存される

• embeddingは現在主に3つの役割を果たす：

  • service.py のパーソナルフィードにおいて、現在のクエリと候補プールに基づいたクエリ認識型セマンティックリコール / セマンティック補完

  • clustering.py において、アイテムのembedding類似度をクラスタリングシグナルの一つとして使用

  • ranking.py において、semantic_match_score を通じてセマンティックマッチシグナルを最終ランキングに反映

Personal Feed

• get_personal_feed は現在唯一のセッション化されたフィードツール

• 主なフロー：

  • 明示的なマルチパスリコール

  • セマンティック補完

  • イベントクラスタリング

  • パーソナライズされたランキング

• service.py は内部で FeedSessionState を保持し、主に以下を保存：

  • pending_clusters

  • delivered_event_ids

  • delivered_item_ids

  • source_cursors

• 戻り値には以下が含まれる：

  • ranked_clusters

  • 展開されたサポート items

  • next_cursor

  • has_more

• ページネーションのセマンティクス：

  • 初回リクエストでフィードセッションを作成し、ランキング済みのクラスターを可能な限り pending_clusters に格納

  • 現在のページは pending_clusters の先頭から最大 max_items 個のクラスターを取得

  • 返却済みのクラスター / アイテムはdeliveredセットに記録され、重複を防ぐ

  • 後続の「もっと見る」は、残りの pending_clusters を優先的に消費

  • バッファがリフィル閾値を下回った場合、次のリコール、セマンティック補完、クラスタリング、ランキングを実行してバッファを補充

ツールのセマンティクスとコンテキストの境界

現在のMCPツールセットは2つのカテゴリに分類できる：

• コンテンツクエリツール

  • get_latest_headlines

  • get_trending_feeds

  • get_project_feed

  • get_project_opinions

  • get_trending_topics

  • search_content

• レコメンデーションツール

  • get_personal_feed

コンテンツクエリツールはデフォルトでステートレス：

• get_latest_headlines / get_project_feed / get_project_opinions / get_trending_topics

  • 上流のページネーション機能を透過

  • 現在のリクエストに対応する1ページの結果を返却

• get_trending_feeds / search_content

  • 現在のスナップショット結果を直接返却

  • 追加のサービス層ページネーション状態を保持しない

get_personal_feed は現在唯一のステートフルなツール：

• service.py は短命な FeedSessionState を保持

• 外部には feed session cursor のみを公開

• サーバー内部で以下を保持：

  • pending_clusters

  • delivered_event_ids

  • delivered_item_ids

  • source_cursors

• 後続の「もっと見る」は、セッション内の pending_clusters を優先的に消費

責任の境界は概ね以下の通り：

• ツール / サービス層

  • コンテンツ取得、候補リコール、クラスタリング、ランキング、フィードセッション管理を提供

• エージェント層

  • マルチターン対話におけるツール選択とコンテキストの継承を担当

  • 例：前回の続き、前回の詳細展開、前回の結果に基づく追問

現在のページネーションのセマンティクス：

• get_latest_headlines / get_project_feed / get_project_opinions / get_trending_topics

  • 上流のネイティブカーソルメタデータを返却

• get_personal_feed

  • next_cursor と has_more を返却

  • cursor のセマンティクスはフィードセッションの継続であり、通常のリストページネーションではない

現在使用されている技術 / アルゴリズム

• Python + MCP (FastMCP)

• Followin APIアダプター

• ルールベースのエンティティ抽出

  • alias matching

  • source tag matching

  • keyword rules

• イベント分類

  • ルールベースのマルチシグナルスコアリング

• エンティティ信頼度

  • strong / medium / weak

• セマンティックリコール

  • OpenAI embedding

  • cosine similarity

  • SQLite ベクトル永続化

• クラスタリング

  • greedy incremental clustering

  • confidence-weighted Jaccard overlap

  • title Jaccard similarity

  • item embedding similarity

• ランキング

  • heuristic linear ranker

  • MMR-style diversification rerank

業界のプロダクション実装と比較して不足しているもの

リコール / レコメンデーションシステムの能力

• レコメンデーション層には、真の長期 / セッションユーザー表現の階層化がまだない

• 行動ログ駆動の非同期ユーザープロファイル更新リンクがまだない

コンテンツ理解

• 軽量なエンティティ発見 / 弱NER（tag、alias、rule、LLM支援抽出）はあるが、スパンオフセット付きの汎用オンラインNER / エンティティリンキングのメインリンクがまだない

• イベントタクソノミーは依然としてコールドスタートルールシステムに偏っており、アノテーションデータ駆動のキャリブレーションが不足している

• 現在の credibility_score は主に上流が提供するソースタイプ / メタデータに依存しており、データ境界の制約により、より詳細なソースレベルの信頼性やマルチソース検証が不足している

クラスタリング

• 現在はembedding類似度をクラスタリングシグナルの一つとしているが、全体としては依然としてヒューリスティックなマルチシグナルクラスタリングであり、学習ベースのペアワイズ分類器 / マージモデルではない

• 永続的なクラスターストアに基づくオンラインクラスタリング体系へさらに進化させるには、クラスター割り当て、および日をまたいだ進化、クラスターの分割・統合などのクラスターライフサイクル能力を補完する必要がある

ランキング

• 現在のランキングはembedding駆動の semantic_match_score を使用しているが、主体は依然として人手による特徴量重み付けのヒューリスティック線形ランカーであり、学習ベースのランキング（LTR）ではない

• レコメンデーション層には、クリック、滞在時間、共有などの行動特徴量がまだ組み込まれていない

• レコメンデーション層は現在軽量なMMR多様化のみを行っており、より体系的なクォータ制御やビジネス制約が不足している

現在公開されているMCPツール

• get_latest_headlines

• get_trending_feeds

• get_project_feed

• get_project_opinions

• get_trending_topics

• search_content

• get_personal_feed

Webデモ

「ランダムなユーザープロファイル + マルチターン対話」をより直感的にテストしたい場合は、Webデモを起動できます：

python3 -m followin_mcp.demo.webapp

またはインストール後：

followin-mcp-web

その後、以下を開きます：

http://127.0.0.1:8000

このデモは以下をサポートします：

• ランダムなユーザープロファイルの生成

• 現在のプロファイルに対するLangChainエージェントセッションの作成

• 同一セッション内でのマルチターンチャットコンテキストの保持

• ページネーションをサポートするツールに対する最新の next_cursor コンテキストの保持

• 各ターンで実際に発生した1つまたは複数のツール呼び出しの表示

• ツールパラメータと戻り値カードの表示

実行前に .env が設定されていることを確認してください：

FOLLOWIN_API_KEY=your_api_key
OPENAI_API_KEY=your_openai_api_key

MCP Server

現在、以下の機能をMCPツールとして公開しています：

• get_latest_headlines

• get_trending_feeds

• get_project_feed

• get_project_opinions

• get_trending_topics

• search_content

• get_personal_feed

起動方法：

python3 -m followin_mcp.mcp.server

またはインストール後に使用：

followin-mcp-server

ACP Agent

現在の対話エージェントをACPをサポートするクライアントにACP stdioエージェントとして公開したい場合は、以下を起動します：

python3 -m followin_mcp.acp.server

またはインストール後に使用：

followin-acp-agent

現在のACPラッパーは FollowinChatAgent を直接再利用します：

• ACPセッションは1つの FollowinChatAgent セッションに対応

• prompt() 内部で既存の chat_stream() を呼び出し

• アシスタントのテキストはストリーミングチャンクとしてACPクライアントに返送される

• ユーザープロファイルはデフォルトで FOLLOWIN_ACP_PROFILE_JSON を読み込み、設定がない場合は組み込みのデフォルトプロファイルを使用

ローカルの acpx / OpenClawに接続する場合、~/.acpx/config.json は最小構成で開始できます：

{
  "agents": {
    "followin": {
      "command": "/path/to/python",
      "args": ["-m", "followin_mcp.acp.server"],
      "cwd": "/path/to/followin-mcp"
    }
  }
}

ここでは追加の env を記述する必要はありません：

• followin_mcp.acp.server 起動時に load_dotenv() が実行される

• cwd がプロジェクトルートを指していれば、リポジトリ内の .env が読み込まれる