Scout Intel MCP

Inteligência de negócios e mercado para agentes de IA — 7 ferramentas, 8 fontes de dados, JSON estruturado

Documentação

Scout MCP
Inteligência de Negócios e Mercado para Agentes de IA

Google para agentes de IA — em vez de páginas web, ele retorna JSON limpo e estruturado que os agentes podem analisar.

O Scout MCP dá a qualquer agente de IA acesso instantâneo a inteligência de negócios estruturada, pesquisa de mercado e análise competitiva. Ele agrega dados de DuckDuckGo, NewsAPI, Wikipedia, web scraping e perfis sociais em respostas JSON validadas por Pydantic, com detalhamento de confiança por fonte e notas de qualidade de dados.

Instalação Rápida

Claude Desktop

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "scout-mcp": {
      "command": "python",
      "args": ["-m", "scout_mcp.mcp_server"],
      "cwd": "/path/to/scout-mcp/src",
      "env": {
        "NEWS_API_KEY": "your-newsapi-key"
      }
    }
  }
}

Cursor

Adicione em Configurações do Cursor > MCP:

{
  "scout-mcp": {
    "command": "python",
    "args": ["-m", "scout_mcp.mcp_server"],
    "cwd": "/path/to/scout-mcp/src",
    "env": {
      "NEWS_API_KEY": "your-newsapi-key"
    }
  }
}

VS Code (Copilot MCP)

Adicione ao .vscode/mcp.json:

{
  "servers": {
    "scout-mcp": {
      "command": "python",
      "args": ["-m", "scout_mcp.mcp_server"],
      "cwd": "/path/to/scout-mcp/src",
      "env": {
        "NEWS_API_KEY": "your-newsapi-key"
      }
    }
  }
}

pip (self-hosted)

pip install scout-mcp
scout-mcp  # starts STDIO server for MCP clients

As 6 Ferramentas de Inteligência

#	Ferramenta	O Que Faz	Nível
1	`scout_company`	Inteligência estruturada sobre qualquer empresa: setor, financiamento, stack tecnológico, concorrentes, notícias, pessoas-chave	Grátis
2	`scout_market`	Pesquisa de mercado: tamanho, CAGR, principais players, tendências, impulsionadores de crescimento, riscos	Grátis
3	`scout_competitors`	Análise de concorrentes: posicionamento, preços, pontos fortes, pontos fracos, diferenciais	Grátis
4	`scout_trends`	Acompanhamento de tendências: análise de sentimento, principais desenvolvimentos, direção da tendência, tópicos relacionados	Grátis
5	`scout_product`	Inteligência de produto: preços, avaliações, recursos, alternativas, atualizações recentes	Grátis
6	`scout_person`	Pesquisa de figuras públicas: papel, histórico, conquistas, perfis sociais	Pro

Notas de Qualidade de Dados

Toda resposta inclui uma data_quality_grade — uma nota em letras que permite aos agentes avaliar instantaneamente a confiabilidade da inteligência:

Nota	Confiança	Significado
A+	90%+	Excepcional — múltiplas fontes de alta qualidade confirmadas
A	80-90%	Alta — forte corroboração de múltiplas fontes
B	65-80%	Boa — dados sólidos de fontes-chave
C	45-65%	Razoável — fontes limitadas, lacunas prováveis
D	25-45%	Baixa — dados escassos, tratar com cautela
F	<25%	Insuficiente — dados mínimos disponíveis

Como os Agentes Devem Usar as Notas

result = scout_company("Stripe")

if result["data_quality_grade"] in ("A+", "A"):
    # High confidence — safe to make decisions on this data
    proceed_with_analysis(result)
elif result["data_quality_grade"] == "B":
    # Good but verify key claims
    proceed_with_caveats(result)
else:
    # C/D/F — supplement with additional sources
    request_more_data(result)

Detalhamento de Confiança

Além da nota em letras, toda resposta inclui um dicionário confidence_breakdown mostrando a confiabilidade por fonte:

{
  "confidence": 0.86,
  "data_quality_grade": "A",
  "confidence_breakdown": {
    "duckduckgo": {
      "score": 0.60,
      "reason": "8 results found"
    },
    "company_website": {
      "score": 0.90,
      "reason": "scraped stripe.com, 3 data points extracted"
    },
    "wikipedia": {
      "score": 0.90,
      "reason": "page found, structured data extracted"
    },
    "newsapi": {
      "score": 0.90,
      "reason": "6 articles found"
    },
    "competitor_extraction": {
      "score": 0.80,
      "reason": "5 competitors identified"
    }
  }
}

Pesos das Fontes

Diferentes fontes carregam pesos diferentes no cálculo geral de confiança:

Fonte	Peso	Porquê
Wikipedia	3x	Curada, estruturada, autoritativa
NewsAPI	2x	Jornalismo profissional e atualizado
Site da Empresa	2x	Dados de primeira mão, mais atuais
Busca DuckDuckGo	1x	Ampla, mas qualidade variável
Extração de Concorrentes	1x	Análise derivada
Perfis Sociais	1x	Complementar

Referência Completa da API

URL Base

POST /api/scout/{tool_name}

Autenticação

Envie sua chave de API via o cabeçalho X-Api-Key:

curl -X POST /api/scout/company \
  -H "X-Api-Key: your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Stripe"}'

Sem chave = nível gratuito (50 requisições/dia).

Saúde e Informações

Endpoint	Método	Descrição
`/api/`	GET	Informações do serviço + lista de ferramentas
`/api/health`	GET	Verificação de saúde + status de backoff do DuckDuckGo
`/api/tools`	GET	Todas as ferramentas com parâmetros, níveis e descrições de notas
`/api/cache/stats`	GET	Estatísticas de acerto/erro de cache
`/api/cache/clear`	POST	Limpar todas as respostas em cache

Endpoints das Ferramentas

`POST /api/scout/company`

Pesquise qualquer empresa.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da empresa (ex.: "Stripe", "OpenAI")
`domain`	string	Não	Domínio da empresa (ex.: "stripe.com"). Detectado automaticamente se omitido.

Campos da resposta: name, domain, description, industry, founded, headquarters, employee_range, funding, tech_stack, social_profiles, recent_news, top_competitors, key_people, confidence, confidence_breakdown, data_quality_grade, data_freshness, sources_used, sources_failed

`POST /api/scout/market`

Pesquise qualquer mercado ou setor.

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	Mercado a pesquisar (ex.: "SaaS de IA", "veículos elétricos")
`depth`	string	Não	`"summary"` (padrão) ou `"detailed"`

Campos da resposta: market_name, query, depth, market_size, market_size_projections, cagr, key_players, trends, growth_drivers, risks, source_links, confidence, confidence_breakdown, data_quality_grade

`POST /api/scout/competitors`

Encontre e analise concorrentes.

Parâmetro	Tipo	Obrigatório	Descrição
`company_or_product`	string	Sim	Nome da empresa ou produto (ex.: "Notion")
`max`	integer	Não	Máximo de concorrentes a retornar (padrão 10)

Campos da resposta: target, competitors (array de {name, domain, positioning, pricing, strengths, weaknesses, key_differentiator}), market_positioning_summary, confidence, confidence_breakdown, data_quality_grade

`POST /api/scout/trends`

Acompanhe tendências e sentimento.

Parâmetro	Tipo	Obrigatório	Descrição
`topic`	string	Sim	Tópico a acompanhar (ex.: "IA generativa")
`timeframe`	string	Não	`"1d"`, `"7d"` (padrão), `"30d"`, `"1y"`

Campos da resposta: topic, timeframe, sentiment ({score, label}), trending_direction, key_developments, related_topics, social_buzz, confidence, confidence_breakdown, data_quality_grade

`POST /api/scout/product`

Obtenha inteligência sobre qualquer produto.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do produto (ex.: "Slack", "Vercel")

Campos da resposta: name, category, description, pricing, ratings, features, ideal_for, alternatives, recent_updates, confidence, confidence_breakdown, data_quality_grade

`POST /api/scout/person` (PRO)

Pesquise uma figura pública. Requer nível Pro ou superior.

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome da pessoa (ex.: "Sam Altman")
`company`	string	Não	Contexto da empresa (ex.: "OpenAI")

Campos da resposta: name, current_role, company, location, background_summary, social_profiles, recent_activity, notable_achievements, confidence, confidence_breakdown, data_quality_grade

Retorna HTTP 403 para usuários do nível gratuito.

Exemplos de Respostas

scout_company("Stripe")

{
  "name": "Stripe",
  "domain": "stripe.com",
  "description": "Stripe, Inc. is an Irish-American multinational financial services and software as a service company...",
  "industry": "Software & Technology",
  "founded": "2010",
  "headquarters": "San Francisco",
  "top_competitors": ["PayPal", "Adyen", "Square", "Braintree", "Checkout.com"],
  "tech_stack": ["Next.js", "React"],
  "recent_news": [
    {"headline": "Stripe launches AI billing features", "source": "TechCrunch", "date": "2026-04-08"},
    {"headline": "Stripe revenue grows 30% in 2025", "source": "Bloomberg", "date": "2026-03-15"}
  ],
  "confidence": 0.86,
  "data_quality_grade": "A",
  "confidence_breakdown": {
    "duckduckgo": {"score": 0.60, "reason": "8 results found"},
    "company_website": {"score": 0.90, "reason": "scraped stripe.com, 3 data points extracted"},
    "wikipedia": {"score": 0.90, "reason": "page found, structured data extracted"},
    "newsapi": {"score": 0.90, "reason": "6 articles found"},
    "competitor_extraction": {"score": 0.80, "reason": "5 competitors identified"}
  },
  "data_freshness": "2026-04-12T12:00:00Z"
}

scout_trends("IA generativa", timeframe="7d")

{
  "topic": "generative AI",
  "timeframe": "7d",
  "sentiment": {"score": 0.72, "label": "positive"},
  "trending_direction": "up",
  "key_developments": [
    {
      "headline": "OpenAI releases GPT-5.2 with reasoning capabilities",
      "date": "2026-04-10",
      "impact_level": "high",
      "source": "The Verge"
    }
  ],
  "related_topics": ["Large Language Models", "AI Safety", "Enterprise AI"],
  "confidence": 0.83,
  "data_quality_grade": "A",
  "confidence_breakdown": {
    "duckduckgo_news": {"score": 0.90, "reason": "10 news articles found"},
    "newsapi": {"score": 0.90, "reason": "4 articles found"},
    "web_search": {"score": 0.50, "reason": "5 web results for context"}
  }
}

scout_competitors("Notion")

{
  "target": "Notion",
  "competitors": [
    {
      "name": "Obsidian",
      "domain": "obsidian.md",
      "positioning": "Privacy-focused local-first knowledge base with Markdown",
      "strengths": ["Open source", "Free tier available", "Offline support"],
      "key_differentiator": "Local-first with plain Markdown files"
    },
    {
      "name": "Coda",
      "positioning": "All-in-one doc with app-building capabilities",
      "strengths": ["AI-powered features"],
      "key_differentiator": "Document-as-app paradigm"
    },
    {
      "name": "Logseq",
      "positioning": "Open-source outliner with bidirectional links"
    }
  ],
  "market_positioning_summary": "Found 7 competitors for Notion. Top alternatives: Obsidian, Coda, Logseq, Anytype, AppFlowy.",
  "confidence": 0.65,
  "data_quality_grade": "B",
  "confidence_breakdown": {
    "search_Notion alternative": {"score": 0.70, "reason": "8 results for 'Notion alternatives'"},
    "search_Notion vs competi": {"score": 0.60, "reason": "6 results for 'Notion vs competitors'"},
    "extraction_quality": {"score": 0.86, "reason": "7 competitors extracted and enriched"}
  }
}

Arquitetura

                      +------------------+
                      |  AI Agent        |
                      |  (Claude, etc.)  |
                      +--------+---------+
                               |
                    STDIO / SSE / REST
                               |
              +----------------+----------------+
              |          Scout MCP              |
              |  FastMCP 3.x + FastAPI REST     |
              +----------------+----------------+
              |  Cache (24h TTL, in-memory)     |
              |  Auth (API key, tier limits)     |
              |  Rate Limiter (per-key, daily)   |
              +----+--------+--------+----------+
                   |        |        |
          +--------+  +-----+--+  +--+--------+
          | DuckDuckGo| | NewsAPI | | Wikipedia |
          | (free)    | | (.org)  | | (free)    |
          +-----------+ +---------+ +-----------+
                   |                    |
          +--------+--------+  +-------+-------+
          | Web Scraper     |  | Social Profile |
          | (httpx + BS4)   |  | Detection      |
          +----------------+  +----------------+

Backoff Exponencial (DuckDuckGo)

A API gratuita do DuckDuckGo tem limites de taxa. O Scout MCP lida com isso usando backoff adaptativo:

Success  : interval = 2s (base)
Failure 1: interval = 4s
Failure 2: interval = 8s
Failure 3: interval = 16s
Failure 4: interval = 32s
Failure 5: interval = 48s (cap)
Next success: interval resets to 2s

Cada chamada também tenta novamente uma vez antes de desistir. Monitore o status de backoff em GET /api/health.

Mecanismo de Extração de Concorrentes

A extração de concorrentes usa 6 categorias de padrões regex com mais de 350 palavras de parada:

Padrões VS — correspondência "X vs Y"
Listas separadas por vírgula/"e" — "alternativas incluem X, Y e Z"
Listas numeradas/com marcadores — "1. Asana 2. Monday 3. ClickUp"
Padrões de cabeçalho — "Asana -- ferramenta de gerenciamento de projetos"
Padrões contextuais — "como X" ou "tais como X"
Nomes em Title Case — nomes de produtos capitalizados próximos ao contexto de concorrentes

Validadores de múltiplas palavras rejeitam: títulos de artigos, nomes com prefixo de verbo, nomes com prefixo de pronome, nomes com sufixo de função, prováveis nomes de pessoas, nomes de empresas-mãe gigantes e nomes de plataformas.

Configuração

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`NEWS_API_KEY`	Sim	—	Chave de API do NewsAPI.org (obtenha uma grátis)
`SCOUT_API_KEY`	Não	—	Chave de API mestre (atribui automaticamente o nível "scale")
`MONGO_URL`	Automática	—	String de conexão MongoDB (para servidor da API REST)
`DB_NAME`	Automática	—	Nome do banco de dados MongoDB
`CORS_ORIGINS`	Não	`*`	Origens CORS permitidas

Configurações de Cache

As respostas são armazenadas em cache por 24 horas em memória (dict). Estatísticas de cache e endpoints de limpeza:

# Check cache stats
curl /api/cache/stats

# Clear all cache
curl -X POST /api/cache/clear

Preços e Limites de Taxa

Nível	Preço	Limite Diário	Ferramentas	Recursos
Grátis	$0/mês	50 requisições	5 de 6	Profundidade de resumo, notas básicas
Pro	$29/mês	1.000 requisições	Todas as 6	+ `scout_person` + relatórios de mercado detalhados
Scale	$99/mês	10.000 requisições	Todas as 6	Tudo + suporte prioritário

As informações de limite de taxa estão incluídas no campo _meta de toda resposta:

{
  "_meta": {
    "tier": "free",
    "remaining": 47
  }
}

Self-Hosting

Desenvolvimento Local

# Clone and install
git clone https://github.com/your-org/scout-mcp.git
cd scout-mcp/backend
pip install -e ".[dev,server]"

# Set up environment
echo "NEWS_API_KEY=your-key" > .env

# Run MCP server (STDIO for Claude Desktop)
cd src && python -m scout_mcp.mcp_server

# Run REST API server
uvicorn server:app --host 0.0.0.0 --port 8001 --reload

# Inspect with MCP Inspector
fastmcp inspect src/scout_mcp/mcp_server.py

Executando Testes

# Test the API
curl -X POST http://localhost:8001/api/scout/company \
  -H "Content-Type: application/json" \
  -d '{"name": "OpenAI"}'

# Check health + backoff status
curl http://localhost:8001/api/health

# List all tools
curl http://localhost:8001/api/tools

Docker

FROM python:3.12-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends gcc libxml2-dev libxslt1-dev && rm -rf /var/lib/apt/lists/*
COPY pyproject.toml .
COPY src/ src/
RUN pip install --no-cache-dir .
EXPOSE 8001
CMD ["python", "-c", "from scout_mcp.mcp_server import mcp; mcp.run(transport='sse', port=8001)"]

# Build and run
docker build -t scout-mcp .
docker run -p 8001:8001 -e NEWS_API_KEY=your-key scout-mcp

Stack Tecnológico

Componente	Tecnologia	Finalidade
Framework MCP	FastMCP 3.x	Registro de ferramentas, transporte STDIO/SSE
API REST	FastAPI	Endpoints HTTP para testes
Cliente HTTP	httpx	Web scraping assíncrono
Parser HTML	BeautifulSoup4 + lxml	Extração de dados estruturados
Busca	DuckDuckGo (ddgs)	Busca gratuita na web e notícias
Notícias	NewsAPI.org	Artigos de notícias profissionais
Conhecimento	API da Wikipedia	Dados estruturados de contexto
Validação	Pydantic 2.x	Validação de modelos de resposta
Cache	Dict em memória (TTL 24h)	Cache de respostas
Servidor	uvicorn	Servidor de produção ASGI

Fontes de Dados

Fonte	Chave de API?	Custo	Limite de Taxa	Confiabilidade
Busca DuckDuckGo	Não	Grátis	Limites flexíveis (backoff)	Variável
Notícias DuckDuckGo	Não	Grátis	Limites flexíveis (backoff)	Variável
NewsAPI.org	Sim	Nível gratuito	100 req/dia	Alta
API da Wikipedia	Não	Grátis	Ilimitado (educado)	Muito Alta
Web Scraping (httpx)	Não	Grátis	Limites por site	Média
Detecção de Perfis Sociais	Não	Grátis	Via DuckDuckGo	Variável

Fontes Futuras (Planejadas)

API Crunchbase (dados de financiamento)
API SimilarWeb (dados de tráfego)
API GitHub (ferramentas para desenvolvedores)
API SEMrush (dados de SEO)

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade: git checkout -b feature/my-feature
Instale as dependências de desenvolvimento: pip install -e ".[dev]"
Faça suas alterações
Execute os testes: pytest
Envie um pull request

Adicionando uma Nova Fonte de Dados

Crie src/scout_mcp/sources/your_source.py
Implemente funções assíncronas que retornam dados estruturados
Adicione a fonte às ferramentas relevantes em src/scout_mcp/tools/
Adicione pontuação de confiança por fonte
Atualize este README

Adicionando uma Nova Ferramenta

Crie src/scout_mcp/tools/your_tool.py
Adicione um modelo Pydantic em models.py (inclua confidence_breakdown e data_quality_grade)
Registre em mcp_server.py com @mcp.tool()
Adicione o endpoint REST em server.py
Atualize este README

Licença

MIT

Construído com FastMCP, httpx, BeautifulSoup4, Pydantic
Scout MCP v0.1.0

🚀 Confira também ProfitSpot MCP — inteligência DeFi cross-chain para agentes de IA. Rendimentos com pontuação de risco, simulações de Monte Carlo, rastreamento de baleias em 86 cadeias.