Skip to content

Latest commit

 

History

History
348 lines (262 loc) · 8.03 KB

CONTRIBUTING.md

File metadata and controls

348 lines (262 loc) · 8.03 KB

Contributing to Google Research MCP

Thank you for your interest in contributing to the Google Research MCP Server. This document provides guidelines and instructions for contributing to the project.

Table of Contents

Code of Conduct

By participating in this project, you agree to maintain a professional and respectful environment for all contributors.

Getting Started

  1. Fork the repository
  2. Clone your fork locally
  3. Create a new branch for your feature or fix
  4. Make your changes
  5. Test thoroughly
  6. Submit a pull request

Development Setup

Prerequisites

  • Node.js 18 or higher
  • npm or yarn package manager
  • Google Cloud Platform account with Custom Search API access
  • Text editor or IDE (VS Code recommended)

Installation

# Clone your fork
git clone https://github.com/YOUR_USERNAME/Google-Research-MCP.git
cd Google-Research-MCP

# Install dependencies
npm install

# Create .env file
cp .env.example .env

# Add your credentials to .env
# GOOGLE_API_KEY=your_google_api_key
# GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id

# Build the project
npm run build

# Run the server
npm run start:v3

Verify Installation

After running 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)
Focus area analysis
Enhanced error handling
Cache metadata
============================================================
Server running on STDIO

Project Structure

src/
├── google-search-v3.ts              # Main MCP server
├── services/
│   ├── google-search.service.ts     # Google API integration
│   ├── content-extractor.service.ts # Web content extraction
│   ├── source-quality.service.ts    # Source ranking
│   ├── deduplication.service.ts     # Duplicate detection
│   └── research-synthesis.service.ts # Agent-based synthesis
├── types.ts                          # TypeScript interfaces
└── utils/                            # Utility functions

Making Changes

Branch Naming

Use descriptive branch names:

  • feature/add-new-tool - For new features
  • fix/search-bug - For bug fixes
  • docs/update-readme - For documentation updates
  • refactor/improve-dedup - For code refactoring

Commit Messages

Write clear, descriptive commit messages:

feat: add support for image search filtering
fix: resolve deduplication edge case for Reddit URLs
docs: update AGENT-MODE.md with troubleshooting section
refactor: extract URL normalization to utility function

Format:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Test additions or modifications
  • chore: - Maintenance tasks

Testing

Manual Testing

Before submitting changes, test all affected functionality:

// Test basic search
google_search({
  query: "test query",
  num_results: 5
})

// Test research with agent mode
research_topic({
  topic: "test topic",
  depth: "intermediate"
})

// Test content extraction
extract_webpage_content({
  url: "https://example.com"
})

Testing Checklist

  • Server starts without errors
  • All tools execute successfully
  • Agent mode synthesis works correctly
  • Quality scores appear in search results
  • Deduplication functions properly
  • Error handling provides helpful messages
  • TypeScript compiles without errors
  • No console warnings or errors

Build Testing

# Clean build
rm -rf dist/
npm run build

# Check for TypeScript errors
npx tsc --noEmit

Submitting Changes

Pull Request Process

  1. Update Documentation

    • Update README.md if adding features
    • Update relevant .md files in docs
    • Add JSDoc comments to new functions

  2. Test Thoroughly

    • Run the testing checklist above
    • Test edge cases
    • Verify no regressions

  3. Create Pull Request

    • Provide clear description of changes
    • Reference related issues
    • Include testing performed
    • Add screenshots if UI-related

Pull Request Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing Performed
- Describe testing done
- List test cases covered

## Checklist
- [ ] Code follows project style guidelines
- [ ] Documentation updated
- [ ] TypeScript compiles without errors
- [ ] All tests pass
- [ ] No console warnings

Code Style Guidelines

TypeScript

  • Use TypeScript strict mode
  • Define interfaces for all data structures
  • Avoid any type when possible
  • Use descriptive variable and function names
  • Add JSDoc comments for public APIs
/**
 * Assesses the quality of a source based on URL and content.
 * @param url - The source URL
 * @param content - Optional webpage content
 * @returns Source quality assessment
 */
assessSource(url: string, content?: WebpageContent): SourceQuality {
  // Implementation
}

Formatting

  • Use 2 spaces for indentation
  • Max line length: 100 characters
  • Use single quotes for strings
  • Add trailing commas in multi-line objects/arrays
const config = {
  option1: 'value1',
  option2: 'value2',
  option3: 'value3',
};

Error Handling

Always provide helpful error messages:

throw new Error(
  `Failed to extract content from ${url}. ` +
  `Ensure the URL is accessible and returns valid HTML.`
);

Service Pattern

Follow existing service patterns:

export class NewService {
  private config: Config;

  constructor(config?: Partial<Config>) {
    this.config = { ...DEFAULT_CONFIG, ...config };
  }

  public async performAction(params: Params): Promise<Result> {
    // Implementation
  }

  private helperMethod(): void {
    // Helper implementation
  }
}

Reporting Issues

Bug Reports

Include:

  1. Description - Clear description of the bug
  2. Steps to Reproduce - Exact steps to trigger the bug
  3. Expected Behavior - What should happen
  4. Actual Behavior - What actually happens
  5. Environment
    • Node.js version
    • Operating system
    • MCP client (Claude Code, Claude Desktop, etc.)
  6. Error Messages - Complete error output
  7. Additional Context - Screenshots, logs, etc.

Feature Requests

Include:

  1. Problem Description - What problem does this solve?
  2. Proposed Solution - How should it work?
  3. Alternatives Considered - Other approaches considered
  4. Use Cases - Real-world usage scenarios
  5. Additional Context - Examples, mockups, etc.

Areas for Contribution

High Priority

  • Additional source quality heuristics
  • Performance optimizations
  • Enhanced deduplication algorithms
  • Additional output formats
  • Improved error recovery

Medium Priority

  • Additional search filters
  • Content extraction improvements
  • Cache management
  • Rate limiting enhancements

Documentation

  • Additional usage examples
  • API documentation
  • Troubleshooting guides
  • Video tutorials

Questions?

If you have questions about contributing:

  1. Check existing documentation
  2. Search existing issues
  3. Open a new issue with the question label

Thank you for contributing to Google Research MCP Server!