Skip to content

Latest commit

 

History

History
433 lines (319 loc) · 8.91 KB

SETUP-V3.md

File metadata and controls

433 lines (319 loc) · 8.91 KB

Google Research MCP v3 - Quick Setup Guide

Prerequisites

  • Node.js 18+ installed
  • Google API key and Search Engine ID
  • Anthropic API key (optional but recommended)

Step-by-Step Setup

1. Install Dependencies

cd /path/to/Google-Research-MCP
npm install

This installs the new @anthropic-ai/sdk package.

2. Configure Environment

Edit .env file:

# Required
GOOGLE_API_KEY=your_google_api_key
GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id

# HIGHLY RECOMMENDED (for AI synthesis)
ANTHROPIC_API_KEY=your_anthropic_api_key

# Optional
MCP_TRANSPORT=stdio
PORT=3000

Get Anthropic API Key:

  1. Go to https://console.anthropic.com/
  2. Sign up / Log in
  3. Navigate to API Keys
  4. Create new key (starts with sk-ant-)
  5. Copy to .env

3. Build TypeScript

npm run build

This compiles all the new services:

  • source-quality.service.ts
  • deduplication.service.ts
  • research-synthesis.service.ts
  • google-search-v3.ts

4. Test the Server

Option A: Standalone Test

npm run start:v3

You should see:

==============================================================
Google Research MCP Server v3.0.0 (Enhanced)
==============================================================
✓ Source quality assessment
✓ Deduplication
✓ AI synthesis: ENABLED  ← Should show ENABLED if API key set
✓ Focus area analysis
✓ Enhanced error handling
✓ Cache metadata
==============================================================
Server running on STDIO

Option B: With Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-research": {
      "command": "node",
      "args": [
        "/absolute/path/to/Google-Research-MCP/dist/google-search-v3.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_key",
        "GOOGLE_SEARCH_ENGINE_ID": "your_id",
        "ANTHROPIC_API_KEY": "your_anthropic_key"
      }
    }
  }
}

Restart Claude Desktop.

Testing the Improvements

Test 1: Research Synthesis (CRITICAL)

What to test: AI-powered synthesis instead of "..."

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

Expected output:

  • Real summary paragraph (not "...")
  • 5-7 actual findings extracted from sources
  • Themes identified
  • Quality metrics shown
  • Retrieved timestamp

Failure case: If you see summary: "...", check that:

  • ANTHROPIC_API_KEY is set in .env
  • Server startup shows "AI synthesis: ENABLED"
  • API key is valid (test at console.anthropic.com)

Test 2: Source Quality & Deduplication

What to test: Quality scoring and duplicate removal

google_search({
  query: "python asyncio tutorial",
  num_results: 10
})

Expected output:

✓ Removed 2 duplicate sources
✓ 8 unique domains

Results:
1. Python Official Docs
   Quality: 95% | Authority: 90% | Type: official_documentation
   [snippet]

2. Real Python Tutorial
   Quality: 78% | Authority: 60% | Type: blog
   [snippet]
...

Test 3: Focus Areas

What to test: Dedicated analysis per focus area

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

Expected output:

## Focus Area Analysis

### RBAC
Dedicated analysis of Role-Based Access Control...

**Key Points:**
- Finding 1 specific to RBAC
- Finding 2 specific to RBAC
...

**Best Practices:**
- Practice 1
- Practice 2

### network policies
[Dedicated section for network policies]

### pod security
[Dedicated section for pod security]

Test 4: Enhanced Error Handling

What to test: Helpful error messages

google_search({
  query: "xyzabc123notreal"
})

Expected output:

Error: No results found for "xyzabc123notreal"

Suggestions:
- Try using broader search terms
- Check spelling of search terms
- Try searching for related concepts

Try these alternative queries:
- "xyzabc basics"
- "xyzabc guide"

Test 5: Content Extraction Controls

What to test: Custom preview lengths

extract_webpage_content({
  url: "https://realpython.com/async-io-python/",
  preview_length: 300,
  max_length: 5000
})

Expected output:

Content Preview (300 chars):
[Exactly 300 characters]

Note: Content limited to 5000 characters

Retrieved at: 2025-11-07T...

Test 6: Cache Metadata

What to test: Timestamps on all responses

google_search({
  query: "rust programming"
})

Expected in output:

Retrieved at: 2025-11-07T21:45:00.000Z

[structuredContent includes cache_info]

Verification Checklist

  • Server starts without errors
  • Shows ✓ AI synthesis: ENABLED
  • Research summaries are actual analysis (not "...")
  • Sources show quality scores
  • Duplicates are removed (check for "Removed X duplicates")
  • Focus areas get dedicated sections
  • Errors provide helpful suggestions
  • All responses include timestamps
  • Preview lengths are consistent

Common Issues

Issue: Agent synthesis not working

Cause: Server not in agent mode or configuration issue

Fix:

  1. Verify server shows "AGENT MODE" on startup
  2. Check for [AGENT_SYNTHESIS_REQUIRED] in output
  3. Rebuild: npm run build
  4. Restart server

Issue: TypeScript compilation errors

Cause: New dependencies not installed

Fix:

rm -rf node_modules package-lock.json
npm install
npm run build

Issue: Research still returns "..."

Possible causes:

  1. API key not set (check startup message)
  2. API rate limit reached
  3. Network issues

Debug:

# Check API key is loaded
npm run start:v3

# Look for this line:
# ✓ AI synthesis: ENABLED  ← Should be ENABLED

Issue: No quality scores on sources

Cause: Using v2 instead of v3

Fix:

# Make sure you're running v3:
npm run start:v3  # NOT start:v2

Issue: Focus areas not working

Symptoms: No "Focus Area Analysis" section

Check:

  1. Did you pass focus_areas parameter?
  2. Using v3 server?
  3. AI synthesis enabled?

Example:

research_topic({
  topic: "topic name",
  focus_areas: ["area1", "area2"],  // Must be array
  depth: "advanced"                  // Advanced recommended
})

Performance Expectations

Search Operations

Operation Expected Time Notes
google_search 1-2s +0.3s for quality scoring
extract_webpage_content 2-3s Per URL
research_topic (basic) 8-10s 3 sources + AI synthesis
research_topic (intermediate) 12-15s 5 sources + synthesis
research_topic (advanced) 18-25s 8-10 sources + deep analysis

Note: AI synthesis adds 3-8s depending on content size and depth.

Token Usage (Anthropic)

Depth Input Tokens Output Tokens Est. Cost
basic ~3,000 ~500 $0.01
intermediate ~6,000 ~1,000 $0.02
advanced ~10,000 ~1,500 $0.04

Prices based on Claude 3.5 Sonnet rates as of 2025

Next Steps

  1. Verify all tests pass
  2. Check agent synthesis is working
  3. Read README.md for comprehensive documentation
  4. Review tool-evaluation-report.md for detailed analysis
  5. Check implementation-guide.md for implementation details
  6. Start using the improved research capabilities

Quick Reference

Commands

# Build
npm run build

# Run v3 (STDIO)
npm run start:v3

# Run v3 (HTTP)
npm run start:v3:http

# Run v2 (fallback)
npm run start:v2

Environment Variables

GOOGLE_API_KEY=xxx              # Required
GOOGLE_SEARCH_ENGINE_ID=xxx     # Required
ANTHROPIC_API_KEY=xxx           # Recommended
MCP_TRANSPORT=stdio             # Optional
PORT=3000                       # Optional (HTTP mode)

Tool Names

  • google_search - Enhanced search with quality scores
  • extract_webpage_content - Enhanced with depth controls
  • extract_multiple_webpages - Batch extraction
  • research_topic - Completely rewritten with AI synthesis

Support

  • Issues: Check tool-evaluation-report.md first
  • Code Examples: See implementation-guide.md
  • Full Docs: See README-V3.md

Setup Complete

The server is now configured with:

  • AI-powered research synthesis (agent mode)
  • Source quality assessment
  • Deduplication
  • Focus area analysis
  • Enhanced error handling
  • All 10 improvements active