Scout Intel MCP README

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

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

{
  "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 install scout-mcp
scout-mcp  # starts STDIO server for MCP clients

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)

{
  "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"
    }
  }
}

POST /api/scout/{tool_name}

curl -X POST /api/scout/company \
  -H "X-Api-Key: your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"name": "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"
}

{
  "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"}
  }
}

{
  "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"}
  }
}

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

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

# Check cache stats
curl /api/cache/stats

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

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

# 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

# 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

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