Skip to content

Latest commit

 

History

History
180 lines (134 loc) · 4 KB

QUICK-START.md

File metadata and controls

180 lines (134 loc) · 4 KB

Quick Start Guide

Installation and Setup

1. Install Dependencies

npm install

2. Configure Environment Variables

Create a .env file in the project root:

GOOGLE_API_KEY=your_google_api_key
GOOGLE_SEARCH_ENGINE_ID=your_custom_search_engine_id

Note: No Anthropic API key required. The server uses agent-based synthesis with your existing Claude session.

3. Build and Run

npm run build
npm run start:v3

4. Use in Claude Code

research_topic({
  topic: "Your topic here",
  depth: "intermediate"
})

Claude will automatically launch an agent to synthesize the research.

Research Process

When you call research_topic:

  1. MCP Tool searches Google, deduplicates, and ranks sources by quality
  2. MCP Tool extracts full content from top sources
  3. MCP Tool packages everything into an agent prompt
  4. Claude Code launches an agent automatically
  5. Agent analyzes all sources and synthesizes insights
  6. Output includes comprehensive research with:
    • Executive summary
    • Key findings (5-7 for intermediate depth)
    • Common themes
    • Source quality scores
    • Focus area analysis (if requested)

Environment Variables

Required

GOOGLE_API_KEY=your_google_api_key
GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id

Optional (Advanced Users Only)

# Only set these if you want Direct API mode instead of Agent mode
ANTHROPIC_API_KEY=your_anthropic_key
USE_DIRECT_API=true

For 99% of users: Don't set the optional vars. Agent mode is better!

Verify It's Working

After npm run start:v3, you should see:

============================================================
Google Research MCP Server v3.0.0 (Enhanced)
============================================================
✓ Source quality assessment
✓ Deduplication
✓ AI synthesis: AGENT MODE (Claude will launch agents)
  └─ No API key needed - uses your existing Claude session
✓ Focus area analysis
✓ Enhanced error handling
✓ Cache metadata
============================================================

If you see AGENT MODE - perfect! You're ready to go.

First Research

Try this:

research_topic({
  topic: "Docker container security best practices",
  depth: "intermediate"
})

Expected:

  1. Tool gathers research from 5 high-quality sources
  2. Returns agent prompt
  3. I launch agent automatically
  4. Agent synthesizes and returns comprehensive analysis
  5. Takes ~10-15 seconds total

Common Issues

"No results found"

  • Check your Google API key is valid
  • Verify search engine ID is correct
  • Try a different topic

"Agent not launching"

  • Make sure you're using v3: npm run start:v3
  • Check server shows "AGENT MODE"
  • Look for [AGENT_SYNTHESIS_REQUIRED] in response

"Want to use API directly"

  • Set ANTHROPIC_API_KEY in .env
  • Set USE_DIRECT_API=true in .env
  • Rebuild: npm run build
  • Not recommended for interactive use

Next Steps

  • Read: AGENT-MODE.md for detailed agent mode explanation
  • Read: README-V3.md for comprehensive feature documentation
  • Experiment: Try different depth levels and focus areas

Examples

Quick Overview

research_topic({
  topic: "GraphQL vs REST APIs",
  depth: "basic"  // 3 sources, quick summary
})

Comprehensive Analysis

research_topic({
  topic: "Microservices architecture patterns",
  depth: "advanced",  // 8-10 sources, deep analysis
  focus_areas: ["API gateway", "service mesh", "observability"]
})

Specific Research

research_topic({
  topic: "Kubernetes security",
  depth: "intermediate",
  focus_areas: ["RBAC", "network policies", "pod security"],
  num_sources: 7
})

The tool will work seamlessly with Claude Code, no extra API keys required.