Followin-MCP

프로젝트 개요

이 프로젝트는 암호화폐 뉴스 시나리오를 위한 이벤트 기반 추천 프로토타입으로 이해할 수 있습니다:

• 업스트림: Followin API + adapters.py를 통해 원본 콘텐츠를 가져옵니다.

• normalizer.py: 원본 콘텐츠를 구조화된 ContentItem으로 정규화합니다.

• service.py: get_personal_feed에서 명시적 다중 경로 리콜(multi-path recall)을 수행한 후 의미론적 보완(semantic supplement)을 진행합니다.

• clustering.py: 여러 콘텐츠를 동일한 이벤트인 EventCluster로 병합합니다.

• ranking.py: 다중 신호 휴리스틱 랭커(heuristic ranker) + MMR 리랭킹을 사용하여 개인화된 피드를 생성합니다.

한 줄 요약:

암호화폐 뉴스 시나리오를 위한 Followin MCP 프로토타입: 원본 콘텐츠를 구조화된 항목으로 정규화하고, 다중 경로 리콜, 의미론적 보완, 이벤트 클러스터링 및 개인화된 정렬을 통해 사용자에게 이벤트 기반 피드를 제공합니다.

Related MCP server: Daily News MCP Server

디렉토리 구조

• followin_mcp/ Python 패키지 진입점

• followin_mcp/core/ 핵심 비즈니스 로직: 어댑터, 모델, 정규화기, 랭킹, 서비스

• followin_mcp/mcp/ MCP 서버 진입점

• followin_mcp/demo/ 테스트 에이전트 및 웹 데모

• 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 임베딩 인덱싱, 의미론적 리콜, 항목 유사도

• 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으로 변환

  • 엔티티 추출 소스:

    • 태그

    • 체인 키워드

    • 프로젝트 별칭

    • 토큰 별칭

    • 토픽 별칭

    • 동적 별칭(경량 엔티티 발견 / 우회 NER)

  • 산출물:

    • projects / tokens / chains / topics

    • entity_sources

    • entity_confidence(적중 방식 강도)

    • event_type

    • credibility_score(출처 신뢰도)

    • importance_score(사전 규칙 계산)

4. 리콜(Recall)

• 여기서 '리콜'이란:

  • 더 큰 콘텐츠 풀에서 후보 ContentItem을 가져오는 것

  • 이후 클러스터링, 정렬 및 페이징에 사용

• service.py는 개인 피드에서 명시적 다중 경로 리콜을 먼저 수행:

  • latest

  • trending

  • project

  • search

• 다중 경로 리콜 결과는 item.id를 기준으로 중복 제거

  • 동일한 항목이 여러 경로에서 적중될 경우, 의미론적 일치도가 높고 중요도가 높으며 최신인 버전을 우선 유지

5. 이벤트 클러스터링

• clustering.py

  • 입력: ContentItem 목록

  • 출력: EventCluster 목록

  • 클러스터링 목표는 '동일한 프로젝트'나 '동일한 토픽'이 아닌 '동일한 이벤트'

  • 주요 신호:

    • 이벤트 유형 호환성

    • 시간 창(Time window)

    • 신뢰도 가중치가 적용된 엔티티 중첩

    • 제목 유사도

    • 선택적 의미론적 유사도

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. 임베딩

• semantic_recall.py

  • 정규화된 항목은 비동기 임베딩 워커에 enqueue됨

  • 항목 임베딩은 로컬 SQLite semantic_index.db에 저장

• 임베딩은 현재 세 가지 작업에 참여:

  • service.py의 개인 피드에서 현재 쿼리와 후보 풀을 기반으로 쿼리 인식 의미론적 리콜 / 의미론적 보완 수행

  • clustering.py에서 항목 임베딩 유사도를 클러스터링 신호 중 하나로 사용

  • 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

  • 펼쳐진 supporting items

  • next_cursor

  • has_more

• 페이징 의미:

  • 첫 요청 시 피드 세션을 생성하고, 정렬된 클러스터를 pending_clusters에 최대한 채움

  • 현재 페이지는 pending_clusters의 앞부분에서 max_items만큼 가져옴

  • 반환된 클러스터 / 항목은 delivered 집합에 기록되어 중복 방지

  • 이후 '더 보기'는 남은 pending_clusters를 우선 소비

  • 버퍼가 리필 임계값보다 낮아지면, 다음 리콜, 의미론적 보완, 클러스터링 및 정렬을 트리거하여 버퍼를 보충

도구 의미론 및 컨텍스트 경계

현재 MCP 도구는 두 가지 범주로 나뉩니다:

• 콘텐츠 조회 도구

  • 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

  • 업스트림 페이징 기능 전달

  • 현재 요청에 해당하는 한 페이지 결과 반환

• 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 어댑터

• 규칙 기반 엔티티 추출

  • 별칭 매칭

  • 소스 태그 매칭

  • 키워드 규칙

• 이벤트 분류

  • 규칙 기반 다중 신호 점수 산정

• 엔티티 신뢰도

  • strong / medium / weak

• 의미론적 리콜

  • OpenAI 임베딩

  • 코사인 유사도

  • SQLite 벡터 영속화

• 클러스터링

  • 탐욕적 증분 클러스터링

  • 신뢰도 가중 Jaccard 중첩

  • 제목 Jaccard 유사도

  • 항목 임베딩 유사도

• 정렬

  • 휴리스틱 선형 랭커

  • MMR 스타일 다양화 리랭킹

업계 프로덕션 구현 대비 부족한 점

리콜 / 추천 시스템 능력

• 추천 계층에 실제 장기 / 세션 사용자 표현 계층화가 부족함

• 행동 로그 기반의 비동기 사용자 프로필 업데이트 링크가 아직 없음

콘텐츠 이해

• 경량 엔티티 발견 / 약한 NER(태그, 별칭, 규칙, LLM 보조 추출)은 있으나, span offset을 포함한 범용 온라인 NER / 엔티티 연결 주력 링크가 부족함

• 이벤트 분류 체계는 여전히 콜드 스타트 규칙 시스템에 치우쳐 있으며, 레이블링 데이터 기반의 보정이 부족함

• 현재 credibility_score는 주로 업스트림에서 제공하는 소스 유형 / 메타데이터에 의존하며, 데이터 경계로 인해 더 세밀한 소스 수준의 신뢰성 및 다중 소스 검증이 부족함

클러스터링

• 임베딩 유사도를 클러스터링 신호로 사용 중이나, 전체적으로는 휴리스틱 다중 신호 클러스터링이며, 학습 기반의 쌍별 분류기 / 병합 모델이 아님

• 영속적 클러스터 저장소 기반의 온라인 클러스터링 체계로 발전하려면 클러스터 할당, 일별 진화, 클러스터 분할 및 병합 등 클러스터 수명 주기 능력이 보완되어야 함

정렬

• 임베딩 기반 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

웹 데모

'랜덤 사용자 프로필 + 다중 턴 대화'를 더 직관적으로 테스트하려면 웹 데모를 시작하세요:

python3 -m followin_mcp.demo.webapp

또는 설치 후:

followin-mcp-web

그 다음 접속:

http://127.0.0.1:8000

이 데모는 다음을 지원합니다:

• 랜덤 사용자 프로필 생성

• 현재 프로필을 위한 LangChain 에이전트 세션 생성

• 동일 세션 내 다중 턴 대화 컨텍스트 유지

• 페이징 지원 도구를 위한 최근 사용 가능한 next_cursor 컨텍스트 유지

• 각 턴에서 실제로 발생한 하나 이상의 도구 호출 표시

• 도구 매개변수 및 결과 카드 표시

실행 전 .env에 다음이 설정되어 있는지 확인하세요:

FOLLOWIN_API_KEY=your_api_key
OPENAI_API_KEY=your_openai_api_key

MCP 서버

현재 다음 기능을 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 에이전트

현재 대화 에이전트를 ACP를 지원하는 클라이언트에 ACP stdio 에이전트로 노출하려면 다음을 시작하세요:

python3 -m followin_mcp.acp.server

또는 설치 후 사용:

followin-acp-agent

현재 ACP 래퍼는 FollowinChatAgent를 직접 재사용합니다:

• ACP 세션은 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를 읽음