RSSidian

Conecta feeds RSS ao Obsidian para análise automatizada de conteúdo e sumarização com IA.

GitHub
36
Experimente este MCPPatrocinado

Documentação

RSSidian

O RSSidian é uma ferramenta poderosa que conecta suas assinaturas de feeds RSS ao Obsidian, criando um pipeline automatizado para análise de conteúdo de artigos e gestão de conhecimento.

Recursos

  • Integração OPML:
    • Importa automaticamente assinaturas RSS de arquivos OPML
    • Adição direta de feeds via linha de comando (sem necessidade de OPML)
    • Gestão inteligente de feeds com recursos de silenciar/reativar
    • Organização fácil de assinaturas e listagem de artigos
  • Processamento de Feeds RSS:
    • Recupera e analisa feeds RSS para descobrir novos artigos
    • Por padrão, processa apenas artigos recentes (últimos 7 dias)
    • Período de retrospectiva configurável para conteúdo mais antigo
  • Armazenamento Inteligente:
    • Banco de dados SQLite3 para metadados de artigos e conteúdo completo
    • Índice vetorial Annoy para busca semântica rápida
    • Embeddings vetoriais para descoberta eficiente de conteúdo
    • Rastreamento de estatísticas de feeds (contagem de artigos, classificações de qualidade)
    • Exportação configurável para Markdown no Obsidian
  • Análise com IA:
    • Usa OpenRouter para gerar resumos e insights personalizados
    • Avaliação inteligente de qualidade de conteúdo (sistema de níveis S/A/B/C/D)
    • Análise de valor com pontuação numérica (1-100)
    • Limites de qualidade configuráveis para filtragem de conteúdo
    • Rastreamento de custos para todas as chamadas de API de IA
  • Geração de Resumos:
    • Cria notas de resumo abrangentes no Obsidian
    • Agrupa histórias semelhantes/sobrepostas para apresentação concisa
    • Organiza o conteúdo por nível de qualidade e relevância
    • Inclui estatísticas de feeds e métricas de processamento
  • Busca em Linguagem Natural:
    • Busca semântica rápida alimentada pela biblioteca Annoy
    • Busca inteligente que entende o significado das suas consultas
    • Encontra conteúdo relevante mesmo quando as palavras exatas não correspondem
    • Limite de relevância configurável para ajustar os resultados
    • Resultados agrupados por feed com trechos relevantes
  • Integração com Obsidian:
    • Gera notas em Markdown com modelos personalizáveis
  • API de Serviço MCP:
    • Expõe um serviço Model Context Protocol para agentes de IA

Instalação

# Clone the repository
git clone https://github.com/pedramamini/rssidian.git
cd rssidian

# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install hatch
uv pip install -e .

# Or if you prefer using regular pip
python -m venv .venv
source .venv/bin/activate
pip install hatch
pip install -e .

Observação: Usamos hatch como nosso sistema de build. A flag -e instala o pacote em modo editável, o que é recomendado para desenvolvimento.

Problemas com XCode no OSX

Se você tiver problemas de build, tente:

sudo xcode-select --reset
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

sudo xcodebuild -license

export SDKROOT=$(xcrun --sdk macosx --show-sdk-path)
export CFLAGS="-isysroot $SDKROOT -I$SDKROOT/usr/include"
export CXXFLAGS="$CFLAGS"
export LDFLAGS="-L$SDKROOT/usr/lib"
export PATH="$SDKROOT/usr/bin:$PATH"

rm -rf ~/.cache/uv/builds-v0
uv pip install -e .

Configuração

Inicialize a configuração:

rssidian init

Isso cria um arquivo de configuração em ~/.config/rssidian/config.toml

Configure as definições:

[obsidian]
# Path to your Obsidian vault
vault_path = "~/Documents/Obsidian"

# Template for generated digest note
# Available variables: {date_range}, {summary_items}, {value_analysis}, {feed_stats}
template = """{date_range}

# Feed Digest

## Top Stories
{summary_items}

## Feed Statistics
{feed_stats}
"""

[search]
# Search configuration options
# Length of context to include in search excerpts (in characters)
excerpt_length = 300

[openrouter]
# OpenRouter API configuration
# API key can also be set via RSSIDIAN_OPENROUTER_API_KEY environment variable
api_key = ""

# Model to use for topic detection and article processing
processing_model = "openai/gpt-4o"

# Sample size in characters for topic detection
topic_sample_size = 4096

# Model to use for summarization
# See https://openrouter.ai/docs for available models
model = "openai/gpt-4o"

# Prompt template for processing articles
# Available variables: {content}
prompt = """Your custom prompt template here.
Available variable: {content}"""

# Enable value analysis in output
# When enabled, each article will include a Value assessment
value_prompt_enabled = true

# Minimum quality tier to include in digest (S, A, B, C, D)
# Articles with lower quality tiers will be discarded
minimum_quality_tier = "B"

[annoy]
# Path to vector index file
index_path = "~/.config/rssidian/annoy.idx"

# Number of trees (more = better accuracy but slower build)
n_trees = 10

# Distance metric (angular = cosine similarity)
metric = "angular"

Uso

# Initialize configuration
rssidian init

# Show configuration and system status
rssidian show-config    # Displays config, vector index status, and article stats

# Import and export feeds in OPML format
rssidian opml import path/to/subscriptions.opml           # Import feeds from OPML file
rssidian opml export path/to/export.opml                  # Export all feeds
rssidian opml export path/to/export.opml --exclude-muted  # Export only active feeds (exclude muted)

# Manage feed subscriptions
rssidian subscriptions add <feed_url>                      # Add a new RSS feed subscription
rssidian subscriptions add <feed_url> --title "My Feed"    # Add feed with custom title
rssidian subscriptions add <feed_url> --force              # Update existing feed metadata
rssidian subscriptions list                                # List all subscriptions (sorted alphabetically)
rssidian subscriptions list --sort=articles                # List all subscriptions (sorted by article count)
rssidian subscriptions list --sort=rating                  # List all subscriptions (sorted by quality rating)
rssidian subscriptions list --sort=updated                 # List all subscriptions (sorted by last update date)
rssidian subscriptions mute "Feed Title"                   # Mute a feed (skip during ingestion)
rssidian subscriptions unmute "Feed Title"                 # Unmute a feed

# Process new articles (last 7 days by default)
rssidian ingest

# Process articles from last 30 days with debug output
rssidian ingest --lookback 30 --debug

# Search through article content using natural language (default relevance)
rssidian search "impact of blockchain on cybersecurity"

# Search with custom relevance threshold
rssidian search "meditation techniques for beginners" --relevance 75

# Force refresh of search index before searching
rssidian search "blockchain" --refresh

# Start the MCP (Model Context Protocol) service
rssidian mcp --port 8080                # Start in HTTP mode on port 8080
rssidian mcp --stdio                   # Start in STDIO mode for Claude Desktop integration

Backup do Banco de Dados

O RSSidian inclui um sistema de backup robusto para ajudar você a proteger seu banco de dados de artigos:

  • Carimbo de data/hora automático: Os backups são nomeados automaticamente no formato AAAA-MM-DD
  • Múltiplos backups diários: O sistema lida automaticamente com múltiplos backups no mesmo dia adicionando um índice
  • Processo de restauração seguro: Cria backup temporário antes da restauração em caso de falhas

Comandos:

# Create a new backup
rssidian backup create

# List all backups with sizes and dates
rssidian backup list

# Restore from a specific date
rssidian backup restore 2025-02-24

Ao restaurar um backup, o RSSidian irá:

  • Mostrar a diferença de tamanho entre o banco de dados atual e o backup
  • Exibir a diferença de tempo entre o atual e o backup
  • Exigir confirmação explícita antes de prosseguir
  • Criar um backup temporário do seu banco de dados atual como medida de segurança

Status do Sistema

Use o comando show-config para visualizar o estado atual da sua instalação do RSSidian:

rssidian show-config

Isso exibirá:

  • Localização e tamanho do índice vetorial
  • Número total de artigos
  • Número de artigos com embeddings
  • Outras definições de configuração

Como Funciona

Gestão de Feeds:

  • Importa URLs de feeds de arquivo OPML
  • Exporta feeds para arquivo OPML (com opção de incluir/excluir feeds silenciados)
  • Armazena dados de assinatura no banco de dados SQLite
  • Permite silenciar/reativar feeds específicos

Processamento de Conteúdo:

  • Busca artigos de feeds RSS
  • Gera embeddings vetoriais
  • Atualiza o índice vetorial Annoy
  • Armazena no banco de dados SQLite

Processamento com IA:

  • Gera resumos via OpenRouter
  • Analisa o valor do conteúdo (níveis S/A/B/C/D)
  • Atribui pontuações de qualidade (1-100)
  • Filtra conteúdo de baixo valor (limite configurável)

Integração de Conhecimento:

  • Cria notas de resumo no Obsidian
  • Organiza o conteúdo por qualidade e relevância
  • Inclui estatísticas de feeds e métricas de processamento
  • Modelos de nomes de arquivo personalizáveis com variáveis de data ({from_date}, {to_date}, {date_range}, {date}, {datetime})
  • Permite busca semântica em todo o conteúdo

API de Serviço MCP (Model Context Protocol)

O RSSidian fornece um serviço Model Context Protocol (MCP) que permite que agentes de IA como o Claude interajam com seu conteúdo RSS. O serviço MCP expõe uma API RESTful que permite acesso abrangente ao seu conteúdo ingerido via RSS.

Iniciando o Serviço MCP

# Start the MCP service on the default port (8080)
rssidian mcp

# Start the MCP service on a custom port
rssidian mcp --port 9000

Endpoints da API

# Base URL
http://localhost:8080/api/v1

# Standard API Endpoints
GET  /search                       # Natural language search across articles
GET  /articles                     # List all processed articles
GET  /articles/:id                 # Get article details and content
GET  /subscriptions                # List all subscriptions with mute state
POST /subscriptions/:title/mute    # Mute a feed subscription
POST /subscriptions/:title/unmute  # Unmute a feed subscription

# MCP-specific Endpoints
GET  /mcp                          # Discovery endpoint with capabilities and endpoints
GET  /mcp/subscriptions            # List all feed subscriptions
GET  /mcp/articles                 # List articles with advanced filtering
GET  /mcp/articles/:id/content     # Get full article content
GET  /mcp/search                   # Semantic search with relevance control
GET  /mcp/digest                   # Get digest of high-value articles
GET  /mcp/feed-stats               # Get feed statistics
POST /mcp/query                    # Process natural language queries

Configurando o Claude Desktop para Usar o RSSidian MCP

O RSSidian MCP pode ser usado com o Claude Desktop de duas maneiras: modo HTTP ou modo STDIO.

Opção 1: Modo STDIO (Recomendado)

O modo STDIO permite que o Claude Desktop inicie e se comunique diretamente com o servidor MCP do RSSidian, sem exigir um servidor HTTP separado em execução.

  1. Edite o arquivo de configuração do Claude Desktop clicando no ícone do Claude na barra de menus, selecionando "Settings" e depois clicando em "Edit Configuration File"

  2. Adicione uma nova entrada à seção mcpServers da configuração JSON:

    {
  "globalShortcut": "Shift+Space",
  "mcpServers": {
    "rssidian": {
      "command": "/path/to/your/python",
      "args": [
        "-m",
        "rssidian",
        "mcp",
        "--stdio"
      ]
    }
    // other MCP servers...
  }
}

    Substitua /path/to/your/python pelo caminho real do seu executável Python onde o RSSidian está instalado. Você pode encontrar isso executando which python no terminal onde você normalmente executa o RSSidian.

  3. Salve o arquivo de configuração

Opção 2: Modo HTTP

No modo HTTP, você precisa iniciar o serviço MCP do RSSidian separadamente e configurar o Claude Desktop para se conectar a ele.

  1. Inicie o serviço MCP do RSSidian manualmente:

    rssidian mcp --port 8080

  2. Edite o arquivo de configuração do Claude Desktop clicando no ícone do Claude na barra de menus, selecionando "Settings" e depois clicando em "Edit Configuration File"

  3. Adicione uma nova entrada à seção mcpServers da configuração JSON:

    {
  "globalShortcut": "Shift+Space",
  "mcpServers": {
    "rssidian-http": {
      "command": "/path/to/your/python",
      "args": [
        "-m",
        "rssidian",
        "mcp",
        "--port",
        "8080"
      ]
    }
    // other MCP servers...
  }
}

  4. Salve o arquivo de configuração

  5. Ao conversar com o Claude, você agora pode fazer perguntas sobre seu conteúdo RSS, como:

    • "Quais são os artigos mais recentes sobre IA?"
    • "Encontre artigos sobre blockchain da última semana"
    • "Resuma os artigos de melhor qualidade dos meus feeds de tecnologia"
    • "Quais são os tópicos em alta nas minhas assinaturas?"

O Claude usará automaticamente o serviço MCP do RSSidian para acessar seu conteúdo RSS e fornecer respostas informadas com base nos seus feeds.

Requisitos

  • Python 3.9+
  • Acesso à API OpenRouter
  • Arquivo OPML com assinaturas RSS
  • Cofre Obsidian (opcional)

Desenvolvimento

# Setup development environment
./scripts/setup_dev.sh

# Activate environment
source .venv/bin/activate

Licença

Este projeto é open source e está disponível sob a Licença MIT.