topic-scout-mcp/README.md

MCP Server para buscar notícias e identificar tendências sobre tópicos específicos

# Topic Scout MCP - NPM Package

MCP Server para buscar notícias e identificar tendências sobre tópicos específicos, disponível como pacote npm executável.

## Publicação no NPM

Para usar este pacote, ele precisa ser publicado no npm registry:

```bash
# Login no npm (se necessário)
npm login

# Publicar o pacote
npm publish
```

## Instalação e Uso

### Via npx (recomendado)

```bash
# Executar diretamente via npx
npx topic-scout-mcp -y

# Executar com nome personalizado do servidor
npx topic-scout-mcp -y my-news-server

# Executar com flag longa
npx topic-scout-mcp --yes custom-server-name
```

### Instalação global (opcional)

```bash
npm install -g topic-scout-mcp

# Executar com confirmação automática
topic-scout-mcp -y

# Executar com nome personalizado do servidor
topic-scout-mcp -y my-news-server
```

## Configuração

### Variável de Ambiente

Configure sua chave da API de notícias:

```bash
export NEWS_API_KEY="sua_chave_aqui"
```

### Configuração MCP

Adicione ao seu arquivo de configuração MCP:

```json
{
  "mcpServers": {
    "topic-scout": {
      "command": "npx",
      "args": ["topic-scout-mcp", "-y", "topic-scout-server"],
      "env": {
        "NEWS_API_KEY": "sua_chave_aqui"
      }
    }
  }
}
```

## Ferramentas Disponíveis

### 1. search_news_articles
Busca artigos de notícias sobre um tópico específico.

**Parâmetros:**
- `topic` (obrigatório): Tópico para buscar (ex: "Real Estate", "Technology")
- `timeframe` (opcional): Período de busca ("7d", "30d", "90d") - padrão: "7d"
- `max_articles` (opcional): Máximo de artigos - padrão: 50
- `language` (opcional): Idioma ("en", "pt") - padrão: "en"

### 2. get_news_sources
Lista as principais fontes de notícias disponíveis.

**Parâmetros:**
- `category` (opcional): Categoria de fontes ("business", "technology", "general")
- `language` (opcional): Idioma das fontes - padrão: "en"

## Desenvolvimento

### Instalar dependências
```bash
npm install
```

### Compilar
```bash
npm run build
```

### Executar em desenvolvimento
```bash
npm run dev
```

### Testar CLI
```bash
npm run cli
```

### Publicar no npm
```bash
npm publish
```

## Estrutura do Projeto

```
src/
├── index.ts      # Servidor MCP principal
├── cli.ts        # Interface de linha de comando
└── types.ts      # Tipos TypeScript

dist/             # Código compilado
package.json      # Configuração do pacote
```

## Licença

MIT