collect-contact-information

Dot-Fun/collect-contact-information

3.2

If you are the rightful owner of collect-contact-information and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Contact Information Collection System is a robust B2B contact database and research automation tool built using Claude Code and the Model Context Protocol (MCP). It streamlines the process of researching companies, gathering decision-maker contact information, and managing sales pipelines.

Tools
9
Resources
0
Prompts
0

Contact Information Collection System

A powerful B2B contact database and research automation system built with Claude Code and the Model Context Protocol (MCP). This system helps you efficiently research companies, collect decision-maker contact information, and manage your sales pipeline.

Features

  • Automated Company Research: AI agents that research companies and extract key information
  • Contact Database Management: SQLite-based storage with comprehensive company and contact fields
  • MCP Server Integration: Custom MCP server for seamless database operations
  • Bulk Import/Export: Import company lists and export to CSV for CRM integration
  • Data Visualization: Generate Mermaid diagrams of your database structure and relationships
  • Privacy Compliance: Built-in GDPR, CCPA, and CAN-SPAM compliance tracking

Architecture

Components

  1. Custom MCP Server (./.claude/mcp-servers/contact-db-server/)

    • FastMCP-based server providing 9 database operations
    • Python SQLite backend with comprehensive validation
    • Real-time company research status tracking

  2. Database Schema (data/schema.sql)

    • companies table: 40+ fields for account-level data
    • contacts table: 25+ fields for person-level data
    • Full referential integrity and validation constraints

  3. AI Agents (./.claude/agents/)

    • company-researcher: Automated company research and enrichment
    • Parallel execution for high-throughput research

  4. Utility Scripts (scripts/)

    • Mermaid diagram generator (ER diagrams and data visualizations)
    • CSV export for CRM integration

Quick Start

Prerequisites

  • Python 3.10+
  • SQLite 3
  • Claude Code CLI

Installation

  1. Clone the repository:
git clone https://github.com/dot-fun/collect-contact-information.git
cd collect-contact-information
  1. Set up the MCP server virtual environment:
cd ./.claude/mcp-servers/contact-db-server
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cd ../../..
  1. Initialize the database:
# The database will be initialized automatically when you first use MCP tools
# Or manually with: sqlite3 ./data/contacts.db < ./data/schema.sql

Basic Usage

1. Import Company Names

Create ./inputs/companies.txt with one company name per line:

Acme Corp
TechStart Inc
Global Solutions Ltd

Then run the ingest command:

# In Claude Code CLI
/ingest-companies

This creates placeholder records with researched=0 status.

2. Research Companies

Use the automated research workflow:

# In Claude Code CLI
/research-all-companies

This command:

  • Spawns parallel AI agents (10 by default)
  • Researches each unresearched company
  • Finds company details (website, LinkedIn, industry, location)
  • Identifies key decision-makers
  • Adds contacts to the database
  • Marks companies as researched
3. Export Data

Generate Mermaid diagrams:

# Database schema diagram
python3 ./scripts/generate_mermaid_from_db.py --mode schema -o ./outputs/schema.md

# Company and contact relationships
python3 ./scripts/generate_mermaid_from_db.py -o ./outputs/company_contacts.md

Export to CSV:

python3 ./scripts/export_data_to_csv.py -o ./outputs/company_contacts.csv

MCP Tools Reference

The custom MCP server provides 9 tools:

Core Operations

  • add_company - Add company with full details
  • add_contact - Add contact to a company
  • get_company - Retrieve company by ID or domain
  • get_contacts_by_company - List all contacts for a company
  • list_companies - Browse all companies with optional filtering

Research Workflow

  • ingest_companies_from_file - Bulk import from text file
  • get_unresearched_companies - Find companies marked as unresearched
  • mark_company_as_researched - Update research status
  • initialize_database - Run schema setup

See ai_docs/mcp-tools-reference.md for detailed documentation.

File Structure

├── .claude/
│   ├── agents/                    # AI agent definitions
│   │   ├── company-researcher.md  # Company research agent
│   │   └── README.md
│   ├── commands/                  # Custom slash commands
│   │   ├── ingest-companies.md
│   │   └── research-all-companies.md
│   └── mcp-servers/
│       └── contact-db-server/     # Custom MCP server
│           ├── server.py
│           ├── requirements.txt
│           └── venv/
├── ai_docs/                       # Documentation for AI agents
│   ├── contact-data-specification.md
│   ├── mcp-tools-reference.md
│   ├── mcp-tools-cheatsheet.md
│   └── mcp-tools-examples.md
├── data/
│   ├── contacts.db                # SQLite database
│   ├── schema.sql                 # Database schema
│   └── migrate_*.sql              # Migration scripts
├── inputs/
│   ├── companies.txt              # Your company list (gitignored)
│   └── companies.example.txt      # Example format
├── outputs/                       # Generated reports
│   ├── company_contacts.md
│   ├── company_contacts.csv
│   └── schema.md
├── scripts/
│   ├── generate_mermaid_from_db.py
│   ├── export_data_to_csv.py
│   └── README.md
├── .mcp.json                      # MCP server configuration
├── AGENTS.md                      # Agent guidelines
└── CLAUDE.md                      # Project documentation

Data Model

Company Fields (40+)

Core Identifiers:

  • legal_name, domain, website_url, company_linkedin_url

Location:

  • hq_country, hq_region, hq_city, timezone

Firmographics:

  • industry, employee_range, founded_date

Funding:

  • funding_stage, funding_round

Signals & Intelligence:

  • fit_score, fit_notes, tech_stack, tech_signals
  • pain_points, intent_signals, engagement_score

Pipeline:

  • stage (lead/mql/sql/opportunity/negotiation/closed_won/closed_lost/nurture)
  • owner, territory, account_type
  • next_step, next_step_due_at

Contact Fields (25+)

Core Information:

  • first_name, last_name, email (lowercase required)
  • linkedin_url, title, seniority, function

Contact Details:

  • phone_direct, phone_main, email_status

Relationship:

  • role_in_deal (decision-maker/influencer/champion/user/blocker)
  • company_id (foreign key)

Compliance:

  • consent_basis (legitimate_interest/explicit_consent/contract/compliance_review)
  • consent_captured_at, source, source_url
  • dnc_email, dnc_phone, contact_preferences
  • gdpr_compliant, ccpa_compliant, compliance_notes

See ai_docs/contact-data-specification.md for complete field definitions.

Privacy & Compliance

This system is designed with privacy compliance in mind:

  • Consent Tracking: Every contact requires a consent_basis
  • Source Attribution: All data must have a documented source
  • DNC Management: Do-not-contact flags for email and phone
  • GDPR/CCPA: Compliance fields tracked per contact
  • Data Minimization: Only collect what's necessary
  • Validation: Email lowercase, phone E.164 format

See section 10 of ai_docs/contact-data-specification.md for full compliance requirements.

Development

Running Tests

cd ./.claude/mcp-servers/contact-db-server
source venv/bin/activate
pytest

Database Queries

# Check unresearched companies
sqlite3 ./data/contacts.db "SELECT legal_name FROM companies WHERE researched=0"

# Count contacts by company
sqlite3 ./data/contacts.db "SELECT c.legal_name, COUNT(ct.id) as contact_count
FROM companies c LEFT JOIN contacts ct ON c.id = ct.company_id
GROUP BY c.id ORDER BY contact_count DESC"

# View all decision-makers
sqlite3 ./data/contacts.db "SELECT c.legal_name, ct.first_name, ct.last_name, ct.title
FROM contacts ct JOIN companies c ON ct.company_id = c.id
WHERE ct.role_in_deal = 'decision-maker'"

Coding Style

  • Python: PEP 8, type hints, 4-space indentation
  • SQL: Uppercase keywords, inline comments
  • Markdown: Sentence-case headings

Workflows

Bulk Company Research

  1. Add company names to ./inputs/companies.txt (one per line)
  2. Run /ingest-companies to create placeholder records
  3. Run /research-all-companies to spawn parallel research agents
  4. Monitor progress as agents research and populate data
  5. Export results: python3 ./scripts/export_data_to_csv.py -o ./outputs/output.csv

Manual Company Addition

# In Claude Code, use MCP tools directly
add_company(
    legal_name="Example Corp",
    domain="example.com",
    website_url="https://example.com",
    company_linkedin_url="https://linkedin.com/company/example-corp",
    industry="SaaS",
    employee_range="51-200",
    hq_country="United States",
    stage="lead"
)

Finding Contacts

# Get company
company = get_company(domain="example.com")

# Get all contacts for company
contacts = get_contacts_by_company(company_id=company['company_id'])

Contributing

  1. Follow the coding style guidelines in AGENTS.md
  2. Add tests for new features
  3. Update documentation
  4. Run pytest before committing
  5. Write commits in imperative mood

License

MIT License - feel free to use this system for your B2B research and outreach.

Support

For issues, questions, or contributions, please open an issue on GitHub.

Credits

Built with:

  • Claude Code - AI-powered development
  • FastMCP - MCP server framework
  • SQLite - Database engine
  • Python 3 - Backend logic