Scout Intel MCP

Inteligencia empresarial y de mercado para agentes de IA — 7 herramientas, 8 fuentes de datos, JSON estructurado

Documentación

Scout MCP
Inteligencia Comercial y de Mercado para Agentes de IA

Google para agentes de IA — en lugar de páginas web, devuelve JSON limpio y estructurado sobre el cual los agentes pueden razonar.

Scout MCP brinda a cualquier agente de IA acceso instantáneo a inteligencia comercial estructurada, investigación de mercado y análisis competitivo. Agrega datos de DuckDuckGo, NewsAPI, Wikipedia, web scraping y perfiles sociales en respuestas JSON validadas con Pydantic, con desgloses de confianza por fuente y calificaciones de calidad de datos.

Instalación Rápida

Claude Desktop

Agregar a ~/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

Agregar en Cursor Settings > 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)

Agregar a .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 (autoalojado)

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

Las 6 Herramientas de Inteligencia

#	Herramienta	Qué Hace	Nivel
1	`scout_company`	Inteligencia estructurada sobre cualquier empresa: industria, financiamiento, stack tecnológico, competidores, noticias, personas clave	Gratis
2	`scout_market`	Investigación de mercado: tamaño, CAGR, actores clave, tendencias, impulsores de crecimiento, riesgos	Gratis
3	`scout_competitors`	Análisis de competidores: posicionamiento, precios, fortalezas, debilidades, diferenciadores	Gratis
4	`scout_trends`	Seguimiento de tendencias: análisis de sentimiento, desarrollos clave, dirección de tendencia, temas relacionados	Gratis
5	`scout_product`	Inteligencia de productos: precios, calificaciones, características, alternativas, actualizaciones recientes	Gratis
6	`scout_person`	Investigación de figuras públicas: rol, antecedentes, logros, perfiles sociales	Pro

Calificaciones de Calidad de Datos

Cada respuesta incluye una data_quality_grade — una calificación con letras que permite a los agentes evaluar instantáneamente la confiabilidad de la inteligencia:

Calificación	Confianza	Significado
A+	90%+	Excepcional — múltiples fuentes de alta calidad confirmadas
A	80-90%	Alta — fuerte corroboración de múltiples fuentes
B	65-80%	Buena — datos sólidos de fuentes clave
C	45-65%	Aceptable — fuentes limitadas, probablemente con vacíos
D	25-45%	Baja — datos escasos, tratar con precaución
F	<25%	Insuficiente — datos mínimos disponibles

Cómo Deben Usar los Agentes las Calificaciones

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)

Desglose de Confianza

Más allá de la calificación con letras, cada respuesta incluye un confidence_breakdown que muestra la confiabilidad por fuente:

{
  "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 de las Fuentes

Diferentes fuentes tienen diferentes pesos en el cálculo general de confianza:

Fuente	Peso	Por Qué
Wikipedia	3x	Curada, estructurada, autoritativa
NewsAPI	2x	Periodismo profesional y fresco
Sitio Web de la Empresa	2x	Datos de primera mano, más actuales
Búsqueda DuckDuckGo	1x	Amplia pero de calidad variable
Extracción de Competidores	1x	Análisis derivado
Perfiles Sociales	1x	Complementario

Referencia Completa de la API

URL Base

POST /api/scout/{tool_name}

Autenticación

Pasa tu clave de API mediante el encabezado X-Api-Key:

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

Sin clave = nivel gratuito (50 solicitudes/día).

Salud e Información

Endpoint	Método	Descripción
`/api/`	GET	Información del servicio + lista de herramientas
`/api/health`	GET	Verificación de salud + estado de retroceso de DuckDuckGo
`/api/tools`	GET	Todas las herramientas con parámetros, niveles y descripciones de calificaciones
`/api/cache/stats`	GET	Estadísticas de aciertos/fallos de caché
`/api/cache/clear`	POST	Limpiar todas las respuestas en caché

Endpoints de Herramientas

`POST /api/scout/company`

Investiga cualquier empresa.

Parámetro	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de la empresa (p. ej., "Stripe", "OpenAI")
`domain`	string	No	Dominio de la empresa (p. ej., "stripe.com"). Se detecta automáticamente si se omite.

Campos de respuesta: 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`

Investiga cualquier mercado o industria.

Parámetro	Tipo	Obligatorio	Descripción
`query`	string	Sí	Mercado a investigar (p. ej., "SaaS de IA", "vehículos eléctricos")
`depth`	string	No	`"summary"` (predeterminado) o `"detailed"`

Campos de respuesta: 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`

Encuentra y analiza competidores.

Parámetro	Tipo	Obligatorio	Descripción
`company_or_product`	string	Sí	Nombre de la empresa o producto (p. ej., "Notion")
`max`	integer	No	Máximo de competidores a devolver (predeterminado 10)

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

`POST /api/scout/trends`

Sigue tendencias y sentimiento.

Parámetro	Tipo	Obligatorio	Descripción
`topic`	string	Sí	Tema a seguir (p. ej., "IA generativa")
`timeframe`	string	No	`"1d"`, `"7d"` (predeterminado), `"30d"`, `"1y"`

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

`POST /api/scout/product`

Obtén inteligencia sobre cualquier producto.

Parámetro	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre del producto (p. ej., "Slack", "Vercel")

Campos de respuesta: name, category, description, pricing, ratings, features, ideal_for, alternatives, recent_updates, confidence, confidence_breakdown, data_quality_grade

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

Investiga una figura pública. Requiere nivel Pro o superior.

Parámetro	Tipo	Obligatorio	Descripción
`name`	string	Sí	Nombre de la persona (p. ej., "Sam Altman")
`company`	string	No	Contexto de la empresa (p. ej., "OpenAI")

Campos de respuesta: name, current_role, company, location, background_summary, social_profiles, recent_activity, notable_achievements, confidence, confidence_breakdown, data_quality_grade

Devuelve HTTP 403 para usuarios del nivel gratuito.

Ejemplos de Respuestas

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("generative AI", 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"}
  }
}

Arquitectura

                      +------------------+
                      |  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      |
          +----------------+  +----------------+

Retroceso Exponencial (DuckDuckGo)

La API gratuita de DuckDuckGo tiene límites de tasa. Scout MCP maneja esto con retroceso 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 llamada también se reintenta una vez antes de rendirse. Monitorea el estado de retroceso en GET /api/health.

Motor de Extracción de Competidores

La extracción de competidores utiliza 6 categorías de patrones regex con más de 350 palabras de exclusión:

Patrones VS — coincidencia de "X vs Y"
Listas separadas por comas/y — "las alternativas incluyen X, Y y Z"
Listas numeradas/viñetas — "1. Asana 2. Monday 3. ClickUp"
Patrones de encabezado — "Asana -- herramienta de gestión de proyectos"
Patrones contextuales — "como X" o "tales como X"
Nombres en mayúscula inicial — nombres de productos capitalizados cerca del contexto de competidores

Los validadores de múltiples palabras rechazan: títulos de artículos, nombres con prefijo de verbo, nombres con prefijo de pronombre, nombres con sufijo de rol, probables nombres de personas, nombres de empresas matrices gigantes y nombres de plataformas.

Configuración

Variables de Entorno

Variable	Obligatoria	Predeterminado	Descripción
`NEWS_API_KEY`	Sí	—	Clave de API de NewsAPI.org (obtén una gratis)
`SCOUT_API_KEY`	No	—	Clave de API maestra (asigna automáticamente el nivel "scale")
`MONGO_URL`	Auto	—	Cadena de conexión de MongoDB (para servidor de API REST)
`DB_NAME`	Auto	—	Nombre de la base de datos de MongoDB
`CORS_ORIGINS`	No	`*`	Orígenes CORS permitidos

Configuración de Caché

Las respuestas se almacenan en caché durante 24 horas en memoria (dict). Estadísticas de caché y endpoints de limpieza:

# Check cache stats
curl /api/cache/stats

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

Precios y Límites de Tasa

Nivel	Precio	Límite Diario	Herramientas	Características
Gratis	$0/mes	50 solicitudes	5 de 6	Profundidad de resumen, calificaciones básicas
Pro	$29/mes	1,000 solicitudes	Las 6	+ `scout_person` + informes de mercado detallados
Scale	$99/mes	10,000 solicitudes	Las 6	Todo + soporte prioritario

La información del límite de tasa se incluye en el campo _meta de cada respuesta:

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

Autoalojamiento

Desarrollo 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

Ejecutar Pruebas

# 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	Tecnología	Propósito
Marco MCP	FastMCP 3.x	Registro de herramientas, transporte STDIO/SSE
API REST	FastAPI	Endpoints HTTP para pruebas
Cliente HTTP	httpx	Web scraping asíncrono
Parser HTML	BeautifulSoup4 + lxml	Extracción de datos estructurados
Búsqueda	DuckDuckGo (ddgs)	Búsqueda web y de noticias gratuita
Noticias	NewsAPI.org	Artículos de noticias profesionales
Conocimiento	API de Wikipedia	Datos de antecedentes estructurados
Validación	Pydantic 2.x	Validación del modelo de respuesta
Caché	Dict en memoria (TTL 24h)	Almacenamiento en caché de respuestas
Servidor	uvicorn	Servidor de producción ASGI

Fuentes de Datos

Fuente	¿Clave de API?	Costo	Límite de Tasa	Confiabilidad
Búsqueda DuckDuckGo	No	Gratis	Límites suaves (retroceso)	Variable
Noticias DuckDuckGo	No	Gratis	Límites suaves (retroceso)	Variable
NewsAPI.org	Sí	Nivel gratuito	100 solicitudes/día	Alta
API de Wikipedia	No	Gratis	Ilimitado (cortés)	Muy Alta
Web Scraping (httpx)	No	Gratis	Límites por sitio	Media
Detección de Perfiles Sociales	No	Gratis	Vía DuckDuckGo	Variable

Fuentes Futuras (Planificadas)

API de Crunchbase (datos de financiamiento)
API de SimilarWeb (datos de tráfico)
API de GitHub (herramientas para desarrolladores)
API de SEMrush (datos SEO)

Contribuciones

Haz un fork del repositorio
Crea una rama de características: git checkout -b feature/my-feature
Instala las dependencias de desarrollo: pip install -e ".[dev]"
Realiza tus cambios
Ejecuta las pruebas: pytest
Envía una solicitud de pull

Agregar una Nueva Fuente de Datos

Crea src/scout_mcp/sources/your_source.py
Implementa funciones asíncronas que devuelvan datos estructurados
Agrega la fuente a las herramientas relevantes en src/scout_mcp/tools/
Agrega puntuación de confianza por fuente
Actualiza este README

Agregar una Nueva Herramienta

Crea src/scout_mcp/tools/your_tool.py
Agrega un modelo Pydantic en models.py (incluye confidence_breakdown y data_quality_grade)
Regístralo en mcp_server.py con @mcp.tool()
Agrega el endpoint REST en server.py
Actualiza este README

Licencia

MIT

Construido con FastMCP, httpx, BeautifulSoup4, Pydantic
Scout MCP v0.1.0

🚀 También echa un vistazo a ProfitSpot MCP — inteligencia DeFi entre cadenas para agentes de IA. Rendimientos con puntuación de riesgo, simulaciones de Monte Carlo, seguimiento de ballenas en 86 cadenas.