Followin-MCP

Resumen del proyecto

Este proyecto puede entenderse como un prototipo de recomendación a nivel de eventos orientado al escenario de noticias cripto:

• El flujo ascendente obtiene el contenido original a través de Followin API + adapters.py

• normalizer.py estandariza el contenido original en un ContentItem estructurado

• service.py, en get_personal_feed, realiza primero una recuperación múltiple explícita y luego un suplemento semántico

• clustering.py agrupa múltiples contenidos en un EventCluster del mismo evento

• ranking.py utiliza un ranker heurístico de múltiples señales + re-ranking MMR para generar un feed personalizado

Resumen en una frase:

Un prototipo de MCP de Followin para el escenario de noticias cripto: estandariza el contenido original en ítems estructurados y, mediante recuperación múltiple, suplemento semántico, agrupación de eventos y clasificación personalizada, genera un feed a nivel de evento para el usuario.

Related MCP server: Daily News MCP Server

Estructura del directorio

• followin_mcp/ Entrada del paquete Python

• followin_mcp/core/ Lógica de negocio central: adaptador, modelo, normalizador, ranking, servicio

• followin_mcp/mcp/ Entrada del servidor MCP

• followin_mcp/demo/ Agente de prueba y demo web

• scripts/start_dev.sh Script de inicio local con un solo clic

• web/ Recursos estáticos del frontend

Módulos principales

• followin_mcp/core/adapters.py Capa de adaptación de la API de Followin

• followin_mcp/core/models.py Modelos de datos

• followin_mcp/core/taxonomy_rules.py Configuración de taxonomía / reglas

• followin_mcp/core/normalizer.py Estandarización de contenido original, extracción de entidades, identificación de tipos de eventos

• followin_mcp/core/clustering.py Agrupación de eventos

• followin_mcp/core/ranking.py Clasificación y explicación de recomendaciones de usuario

• followin_mcp/core/semantic_recall.py Indexación de embeddings, recuperación semántica, similitud de ítems

• followin_mcp/core/service.py Entrada de servicio orientada a MCP / capa de aplicación

Secuencia de procesamiento de solicitudes

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

Cadena de procesamiento

1. Entrada MCP

• mcp/server.py

  • Expone 7 herramientas MCP

  • Convierte los parámetros de entrada de MCP en llamadas a service.py

  • Responsable de serializar ContentItem / EventCluster en la estructura de retorno de MCP

2. Obtención de contenido original

• service.py -> adapters.py

  • get_latest_headlines / get_project_feed / get_project_opinions / get_trending_topics Transmite directamente la capacidad de paginación ascendente

  • get_trending_feeds / search_content Devuelve directamente el resultado de la instantánea actual

  • get_personal_feed Realiza primero la recuperación múltiple explícita y el suplemento semántico, luego pasa por la agrupación de eventos y la clasificación personalizada

3. Estandarización de contenido

• normalizer.py

  • normalize(raw) convierte un ítem de contenido original en un ContentItem

  • Fuentes de extracción de entidades:

    • etiqueta (tag)

    • palabra clave de cadena (chain keyword)

    • alias de proyecto

    • alias de token

    • alias de tema

    • alias dinámico (descubrimiento de entidades ligero / NER de derivación)

  • Resultados:

    • projects / tokens / chains / topics

    • entity_sources

    • entity_confidence (fuerza del método de acierto)

    • event_type

    • credibility_score (nivel de credibilidad de la fuente)

    • importance_score (calculado mediante reglas predefinidas)

4. Recuperación (Recall)

• La "recuperación" aquí se refiere a:

  • Tomar primero un lote de ContentItem candidatos de un grupo de contenido más grande

  • Para su uso en la agrupación, clasificación y paginación posteriores

• service.py en el feed personal realiza primero una recuperación múltiple explícita:

  • latest

  • trending

  • project

  • search

• Los resultados de la recuperación múltiple se desduplican primero por item.id

  • Si el mismo ítem es alcanzado por múltiples vías, se prioriza la versión con una coincidencia semántica más fuerte, mayor importancia y fecha de actualización más reciente

5. Agrupación de eventos

• clustering.py

  • La entrada es una lista de ContentItem

  • La salida es una lista de EventCluster

  • El objetivo de la agrupación es el "mismo evento", no el mismo proyecto o el mismo tema

  • Señales principales:

    • Compatibilidad de tipo de evento

    • Ventana de tiempo

    • Superposición de entidades con pesos de confianza

    • Similitud de títulos

    • Similitud semántica opcional

6. Clasificación personalizada

• ranking.py

  • La entrada es EventCluster

  • La salida es el feed de clústeres clasificado según el usuario

  • Señales principales:

    • importance_score

    • freshness_score

    • follow_affinity_score

    • interest_match_score

    • semantic_match_score

    • source_quality_score

    • risk_boost_score

  • mute_penalty

  • Finalmente, se realiza una capa de re-ranking de diversificación estilo MMR

7. Embedding

• semantic_recall.py

  • El ítem normalizado se encola (enqueue) primero en un trabajador de embedding asíncrono

  • El embedding del ítem se almacena en la base de datos SQLite local semantic_index.db

• El embedding participa actualmente en tres cosas principales:

  • service.py realiza una recuperación semántica / suplemento semántico consciente de la consulta en el feed personal basado en la consulta actual y el grupo de candidatos

  • clustering.py utiliza la similitud de embedding del ítem como una de las señales de agrupación

  • ranking.py introduce la señal de coincidencia semántica en la clasificación final a través de semantic_match_score

Feed Personal

• get_personal_feed es actualmente la única herramienta de feed con sesión

• El flujo principal es:

  • Recuperación múltiple explícita

  • Suplemento semántico

  • Agrupación de eventos

  • Clasificación personalizada

• service.py mantiene internamente FeedSessionState, que guarda principalmente:

  • pending_clusters

  • delivered_event_ids

  • delivered_item_ids

  • source_cursors

• Los resultados devueltos incluyen:

  • ranked_clusters

  • items de soporte desplegados

  • next_cursor

  • has_more

• La semántica de paginación es:

  • La primera solicitud crea una sesión de feed e intenta llenar los clústeres ya clasificados en pending_clusters

  • La página actual toma los primeros max_items clústeres del encabezado de pending_clusters

  • Los clústeres / ítems devueltos se registran en el conjunto de entregados para evitar repeticiones posteriores

  • El "más" posterior prioriza continuar consumiendo los pending_clusters restantes

  • Cuando el búfer cae por debajo del umbral de recarga, se activa la siguiente ronda de recuperación, suplemento semántico, agrupación y clasificación para rellenar el búfer

Semántica de herramientas y límites de contexto

Este conjunto actual de herramientas MCP se puede dividir en dos categorías:

• Herramientas de consulta de contenido

  • get_latest_headlines

  • get_trending_feeds

  • get_project_feed

  • get_project_opinions

  • get_trending_topics

  • search_content

• Herramientas de recomendación

  • get_personal_feed

Las herramientas de consulta de contenido son por defecto sin estado:

• get_latest_headlines / get_project_feed / get_project_opinions / get_trending_topics

  • Transmiten la capacidad de paginación ascendente

  • Devuelven una página de resultados correspondiente a la solicitud actual

• get_trending_feeds / search_content

  • Devuelven directamente el resultado de la instantánea actual

  • No mantienen un estado de paginación adicional en la capa de servicio

get_personal_feed es actualmente la única herramienta con estado:

• service.py mantendrá un FeedSessionState de ciclo de vida corto

• Solo expone externamente el feed session cursor

• El servidor mantiene internamente:

  • pending_clusters

  • delivered_event_ids

  • delivered_item_ids

  • source_cursors

• El "más" posterior priorizará continuar consumiendo los pending_clusters en la sesión

Los límites de responsabilidad son aproximadamente:

• Capa de herramienta / servicio

  • Proporciona obtención de contenido, recuperación de candidatos, agrupación, clasificación y gestión de sesión de feed

• Capa de agente

  • Responsable de la selección de herramientas y la continuación del contexto en diálogos de múltiples rondas

  • Por ejemplo, continuar con el lote anterior, desplegar el anterior, preguntar basándose en los resultados de la ronda anterior

Semántica de paginación actual:

• get_latest_headlines / get_project_feed / get_project_opinions / get_trending_topics

  • Devuelven metadatos de cursor nativos del flujo ascendente

• get_personal_feed

  • Devuelve next_cursor y has_more

  • La semántica de cursor es la continuación de la sesión de feed, no una paginación de lista ordinaria

Tecnologías / algoritmos utilizados actualmente

• Python + MCP (FastMCP)

• Adaptador de API de Followin

• Extracción de entidades basada en reglas

  • coincidencia de alias

  • coincidencia de etiquetas de fuente

  • reglas de palabras clave

• Clasificación de eventos

  • puntuación de múltiples señales basada en reglas

• Confianza de entidad

  • strong / medium / weak

• Recuperación semántica

  • Embedding de OpenAI

  • similitud de coseno

  • persistencia de vectores en SQLite

• Agrupación

  • agrupación incremental codiciosa

  • superposición de Jaccard ponderada por confianza

  • similitud de Jaccard de títulos

  • similitud de embedding de ítems

• Clasificación

  • ranker lineal heurístico

  • re-ranking de diversificación estilo MMR

¿Qué le falta al prototipo en comparación con la implementación de producción de la industria?

Capacidades del sistema de recuperación / recomendación

• La capa de recomendación aún no tiene una estratificación real de representación de usuario a largo plazo / sesión

• Aún no hay una cadena de actualización de perfil de usuario asíncrona impulsada por registros de comportamiento

Comprensión de contenido

• Actualmente ya existe un descubrimiento de entidades ligero / NER débil (etiquetas, alias, reglas, extracción asistida por LLM), pero aún no hay una cadena principal de NER / enlace de entidades en línea general con desplazamiento de span

• La taxonomía de eventos sigue siendo un sistema de reglas de arranque en frío, carente de calibración impulsada por datos etiquetados

• El credibility_score actual depende principalmente del tipo de fuente / metadatos proporcionados por el flujo ascendente; limitado por los límites de los datos, aún no hay una fiabilidad a nivel de fuente y verificación de múltiples fuentes más detallada

Agrupación

• Actualmente ya se utiliza la similitud de embedding como una de las señales de agrupación, pero en general sigue siendo una agrupación heurística de múltiples señales, aún no hay un clasificador de pares / modelo de fusión entrenado

• Si se evoluciona aún más hacia un sistema de agrupación en línea basado en un almacén de clústeres persistente, se necesitaría complementar la asignación de clústeres, así como capacidades de ciclo de vida del clúster como evolución entre días, división y fusión de clústeres

Clasificación

• La clasificación actual ya utiliza semantic_match_score impulsado por embedding, pero el cuerpo principal sigue siendo un ranker lineal heurístico ponderado por características humanas, no un aprendizaje para clasificar (learned-to-rank)

• La capa de recomendación aún no ha incorporado características de comportamiento como clics, tiempo de permanencia, compartidos, etc.

• La capa de recomendación solo ha realizado una diversificación MMR ligera, aún no hay un control de cuotas y restricciones de negocio más sistemáticos

Herramientas MCP expuestas actualmente

• get_latest_headlines

• get_trending_feeds

• get_project_feed

• get_project_opinions

• get_trending_topics

• search_content

• get_personal_feed

Demo Web

Si deseas probar de forma más intuitiva el "perfil de usuario aleatorio + diálogo de múltiples rondas", puedes iniciar una demo web:

python3 -m followin_mcp.demo.webapp

O después de la instalación:

followin-mcp-web

Luego abre:

http://127.0.0.1:8000

Esta demo admite:

• Generación aleatoria de perfiles de usuario

• Creación de una sesión de agente LangChain para el perfil actual

• Conservación del contexto de chat de múltiples rondas en la misma sesión

• Conservación del contexto next_cursor disponible más reciente para herramientas que admiten paginación

• Visualización de una o más llamadas a herramientas que ocurrieron realmente en cada ronda

• Visualización de tarjetas de parámetros de herramientas y resultados devueltos

Antes de ejecutar, asegúrate de que en .env se haya configurado:

FOLLOWIN_API_KEY=your_api_key
OPENAI_API_KEY=your_openai_api_key

Servidor MCP

Actualmente se han expuesto las siguientes capacidades como herramientas MCP:

• get_latest_headlines

• get_trending_feeds

• get_project_feed

• get_project_opinions

• get_trending_topics

• search_content

• get_personal_feed

Forma de inicio:

python3 -m followin_mcp.mcp.server

O después de la instalación, usa:

followin-mcp-server

Agente ACP

Si deseas exponer el agente de diálogo actual como un agente stdio de ACP a clientes que admiten ACP, puedes iniciar:

python3 -m followin_mcp.acp.server

O después de la instalación, usa:

followin-acp-agent

El contenedor ACP actual reutiliza directamente FollowinChatAgent:

• La sesión ACP corresponde a una sesión de FollowinChatAgent

• prompt() llama internamente al chat_stream() existente

• El texto del asistente se devuelve al cliente ACP en fragmentos de flujo

• El perfil de usuario lee por defecto FOLLOWIN_ACP_PROFILE_JSON, si no está configurado, utiliza un perfil predeterminado incorporado

Si vas a conectarte a un acpx / OpenClaw local, ~/.acpx/config.json puede usar primero la configuración mínima:

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

Aquí no es necesario escribir env adicional:

• followin_mcp.acp.server ya hará load_dotenv() al iniciarse

• Siempre que cwd apunte al directorio raíz del proyecto, leerá el .env en el repositorio