# Local MCP Server - Introduction

## What is the Tomba MCP Server?

The Tomba MCP Server is a **Model Context Protocol (MCP)** server that provides seamless integration with [Tomba.io](https://tomba.io/)'s powerful email discovery and verification APIs. It allows Large Language Models (LLMs) and AI applications to access comprehensive email intelligence capabilities through a standardized protocol.

## Purpose & Benefits

### For AI Applications

- **Structured Access**: Provides LLMs with reliable, structured access to email data
- **Real-time Intelligence**: Get up-to-date email verification and discovery results
- **Scalable Integration**: Handle multiple concurrent requests with proper error handling
- **Protocol Standardization**: Uses MCP for consistent tool interfaces across different AI systems

### For Developers

- **Easy Integration**: Simple JSON-RPC interface for any MCP-compatible client
- **Type Safety**: Full TypeScript implementation with comprehensive type definitions
- **Comprehensive Testing**: Extensive test suite and debugging tools
- **Professional Grade**: Production-ready with proper error handling and logging

## Architecture Overview

```mermaid
graph TD
    A[AI Assistant/LLM] --> B[MCP Client]
    B --> C[Tomba MCP Server]
    C --> D[Tomba.io API]

    C --> E[Domain Search]
    C --> F[Email Verification]
    C --> G[Contact Enrichment]
    C --> H[Phone Discovery]

    subgraph "MCP Server Tools"
        E
        F
        G
        H
    end
```

### Components

1. **MCP Server Core**: Handles protocol communication and request routing
2. **Tomba Client Wrapper**: Abstracts Tomba.io SDK with error handling
3. **Tool Registry**: Nine specialized tools for different email intelligence tasks
4. **Type System**: Complete TypeScript definitions for all data structures

## Core Capabilities

### Email Discovery

- **Domain Search**: Find all emails associated with any domain
- **Email Finder**: Generate likely email addresses from names + domain
- **Author Finder**: Extract author emails from article URLs
- **LinkedIn Finder**: Discover emails from LinkedIn profile URLs

### Email Intelligence

- **Email Verifier**: Check deliverability and validate email addresses
- **Email Enrichment**: Get comprehensive contact information
- **Company Discovery**: Find relevant companies and their contact data

### Phone Intelligence

- **Phone Finder**: Search phone numbers by email, domain, or LinkedIn
- **Phone Validator**: Validate phone numbers and get carrier information

## Model Context Protocol (MCP)

### What is MCP?

The Model Context Protocol is an open standard that enables secure connections between AI applications and external data sources. It provides:

- **Standardized Communication**: Consistent JSON-RPC based protocol
- **Security**: Controlled access to external APIs and data
- **Flexibility**: Works with any MCP-compatible LLM or AI application
- **Extensibility**: Easy to add new tools and capabilities

### Why MCP for Email Intelligence?

- **Real-time Data**: Access live email verification and discovery data
- **Structured Responses**: Consistent data formats for reliable AI processing
- **Error Handling**: Graceful handling of API limits and errors
- **Scalability**: Handle multiple concurrent requests efficiently

## Use Cases

### For Sales & Marketing

- **Lead Generation**: Find contact information for prospects
- **Email Validation**: Verify email lists before campaigns
- **Contact Enrichment**: Enhance existing contact databases
- **Competitive Intelligence**: Research competitor contact information

### For Recruitment

- **Candidate Research**: Find contact information for potential hires
- **Company Intelligence**: Research target organizations
- **Contact Verification**: Validate candidate-provided information

### For Research & Journalism

- **Source Discovery**: Find expert contacts in specific industries
- **Fact Checking**: Verify contact information and company details
- **Interview Sourcing**: Locate article authors and subject matter experts

### For Data Quality

- **Database Cleaning**: Validate and enrich existing contact data
- **Duplicate Detection**: Identify and merge duplicate contact records
- **Information Verification**: Cross-reference contact details across sources

## 🔧 Technical Specifications

### Supported Protocols

- **MCP Version**: 2024-11-05
- **Transport**: stdio (standard input/output)
- **Message Format**: JSON-RPC 2.0
- **Authentication**: API key + secret key

### System Requirements

- **Node.js**: 16.0.0 or higher
- **TypeScript**: 5.2+ (for development)
- **Memory**: Minimum 512MB RAM
- **Network**: Internet connection for Tomba.io API access

### API Rate Limits

- Respects Tomba.io rate limiting
- Handles 429 responses gracefully
- Implements exponential backoff for retries
- Provides clear error messages for limit exceeded

## Quick Start Example

Here's how the MCP server integrates with an AI application:

```json
// AI requests available tools
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

// Server responds with tool definitions
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "domain_search",
        "description": "Search emails based on domain name",
        "inputSchema": {
          "type": "object",
          "properties": {
            "domain": {"type": "string"},
            "limit": {"type": "number"}
          }
        }
      }
    ]
  }
}

// AI calls a tool
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "domain_search",
    "arguments": {
      "domain": "github.com",
      "limit": 10
    }
  }
}

// Server returns results
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\n  \"emails\": [...],\n  \"total\": 25\n}"
    }]
  }
}
```

## Data Quality & Reliability

### Data Sources

- **Tomba.io Database**: 400+ million email addresses
- **Real-time Verification**: Live deliverability checking
- **Multiple Sources**: Web crawling, social networks, public databases
- **Regular Updates**: Continuously updated data sources

### Accuracy Metrics

- **Email Discovery**: 95%+ accuracy for common domains
- **Verification Results**: Real-time SMTP validation
- **Confidence Scores**: Numerical confidence ratings for results
- **Source Attribution**: Full source tracking for discovered emails

### Privacy & Compliance

- **GDPR Compliant**: Respects data protection regulations
- **Opt-out Respect**: Honors email opt-out requests
- **No Storage**: Server doesn't store or cache personal data
- **Secure Transport**: All communications over secure channels

## Future Roadmap

### Planned Features

- **Bulk Operations**: Batch processing for large datasets
- **Custom Filtering**: Advanced search and filtering capabilities
- **Integration Templates**: Pre-built integrations for popular platforms

### Enhanced Intelligence

- **AI-Powered Matching**: Improved email pattern recognition
- **Social Media Integration**: Extended social profile discovery
- **Company Insights**: Enhanced company intelligence and metrics
- **Predictive Scoring**: ML-powered deliverability predictions

## Next Steps

1. **[Tools Reference](/tools)**: Detailed documentation for each tool
2. **[LLM Integration](/llm)**: Connect with popular AI applications

## Support & Resources

- **GitHub Repository**: [tomba-mcp-server](https://github.com/tomba-io/tomba-mcp-server)
- **Tomba.io Documentation**: [docs.tomba.io](https://docs.tomba.io/)
- **MCP Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
- **Issue Tracker**: Report bugs and request features on GitHub

---

_The Tomba MCP Server bridges the gap between AI applications and professional email intelligence, enabling smarter, data-driven decisions in sales, marketing, recruitment, and research workflows._