Tavily Web Search MCP Server

Instructions

Implementation Reference

• server.py:38-53 (handler)

  The MCP tool handler function for 'organize_and_categorize'. It uses the BookmarkOrganizer class to perform cleaning, deduplication, categorization, organization, saving, and reporting of bookmark data.
  @mcp.tool() def organize_and_categorize(data_folder: str = "data", output_folder: str = "organized") -> str: """Clean, deduplicate, and categorize bookmark data""" try: from bookmark_organizer import BookmarkOrganizer organizer = BookmarkOrganizer(data_folder) organizer.load_data() organizer.clean_and_deduplicate() organizer.categorize_and_tag() organized_data = organizer.organize_by_category() organizer.save_organized_data(organized_data, output_folder) report = organizer.generate_report(organized_data) return f"Organization complete!\n\n{report}" except Exception as e: return f"Error organizing data: {str(e)}"
• bookmark_organizer.py:217-343 (helper)

  The BookmarkOrganizer class provides all supporting utility methods used by the tool handler: load_data(), clean_and_deduplicate(), categorize_and_tag(), organize_by_category(), generate_report(), and save_organized_data().
  class BookmarkOrganizer: """Main organizer class""" def __init__(self, data_folder: str = "data"): self.data_folder = Path(data_folder) self.parser = BookmarkParser() self.analyzer = ContentAnalyzer() self.deduplicator = Deduplicator() self.all_items = [] def load_data(self): """Load all bookmark and history data""" print("Loading data from files...") # Load bookmarks bookmark_file = self.data_folder / "bookmarks_10_26_25.html" if bookmark_file.exists(): bookmarks = self.parser.parse_netscape_html(str(bookmark_file)) self.all_items.extend(bookmarks) print(f"Loaded {len(bookmarks)} bookmarks") # Load history history_file = self.data_folder / "BrowserHistory_10_26_25.csv" if history_file.exists(): history = self.parser.parse_csv_history(str(history_file)) self.all_items.extend(history) print(f"Loaded {len(history)} history entries") print(f"Total items loaded: {len(self.all_items)}") def clean_and_deduplicate(self): """Remove duplicates and clean data""" print("Cleaning and deduplicating...") cleaned_items = [] duplicates_removed = 0 for item in self.all_items: if not self.deduplicator.is_duplicate(item['url'], item.get('title', '')): cleaned_items.append(item) else: duplicates_removed += 1 self.all_items = cleaned_items print(f"Removed {duplicates_removed} duplicates") print(f"Clean items remaining: {len(self.all_items)}") def categorize_and_tag(self): """Categorize items and add keywords""" print("Categorizing and tagging items...") for item in self.all_items: item['category'] = self.analyzer.categorize_url(item['url'], item.get('title', '')) item['keywords'] = self.analyzer.extract_keywords(item['url'], item.get('title', '')) def organize_by_category(self) -> Dict[str, List[Dict]]: """Organize items by category""" organized = defaultdict(list) for item in self.all_items: organized[item['category']].append(item) # Sort each category by domain frequency for category, items in organized.items(): domain_counts = Counter(item['domain'] for item in items) items.sort(key=lambda x: domain_counts[x['domain']], reverse=True) return dict(organized) def generate_report(self, organized_data: Dict[str, List[Dict]]) -> str: """Generate a summary report""" report = [] report.append("=" * 60) report.append("BOOKMARK & HISTORY ORGANIZATION REPORT") report.append("=" * 60) report.append(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}") report.append("") # Summary statistics total_items = sum(len(items) for items in organized_data.values()) report.append(f"Total organized items: {total_items}") report.append(f"Categories: {len(organized_data)}") report.append("") # Category breakdown report.append("CATEGORY BREAKDOWN:") report.append("-" * 30) for category, items in sorted(organized_data.items(), key=lambda x: len(x[1]), reverse=True): report.append(f"{category.upper()}: {len(items)} items") # Top domains in this category domain_counts = Counter(item['domain'] for item in items) top_domains = domain_counts.most_common(3) for domain, count in top_domains: report.append(f" - {domain}: {count} items") report.append("") return "\n".join(report) def save_organized_data(self, organized_data: Dict[str, List[Dict]], output_folder: str = "organized"): """Save organized data to files""" output_path = Path(output_folder) output_path.mkdir(exist_ok=True) print(f"Saving organized data to {output_path}...") # Save each category to separate JSON file for category, items in organized_data.items(): category_file = output_path / f"{category}.json" with open(category_file, 'w', encoding='utf-8') as f: json.dump(items, f, indent=2, ensure_ascii=False) # Save complete organized data complete_file = output_path / "complete_organized.json" with open(complete_file, 'w', encoding='utf-8') as f: json.dump(organized_data, f, indent=2, ensure_ascii=False) # Save report report_file = output_path / "organization_report.txt" report = self.generate_report(organized_data) with open(report_file, 'w', encoding='utf-8') as f: f.write(report) print(f"Saved {len(organized_data)} category files") print(f"Report saved to {report_file}")
• server.py:38-38 (registration)

  The @mcp.tool() decorator registers the organize_and_categorize function as an MCP tool.
  @mcp.tool()
• bookmark_organizer.py:20-73 (helper)

  BookmarkParser class with methods to parse bookmark HTML and history CSV files.
  class BookmarkParser: """Parse different bookmark formats""" @staticmethod def parse_netscape_html(file_path: str) -> List[Dict]: """Parse Netscape bookmark HTML format""" bookmarks = [] with open(file_path, 'r', encoding='utf-8') as f: content = f.read() # Extract bookmark links using regex pattern = r'<A HREF="([^"]+)"[^>]*>([^<]+)</A>' matches = re.findall(pattern, content) for url, title in matches: # Decode HTML entities title = html.unescape(title) url = html.unescape(url) bookmarks.append({ 'url': url, 'title': title, 'source': 'bookmarks', 'domain': urlparse(url).netloc, 'added_date': datetime.now().isoformat() }) return bookmarks @staticmethod def parse_csv_history(file_path: str) -> List[Dict]: """Parse CSV browser history format""" history = [] with open(file_path, 'r', encoding='utf-8-sig') as f: # Use utf-8-sig to handle BOM reader = csv.DictReader(f) for row in reader: try: # Handle BOM in column names datetime_key = 'DateTime' if 'DateTime' in row else 'DateTime' history.append({ 'url': row['NavigatedToUrl'], 'title': row['PageTitle'], 'source': 'history', 'domain': urlparse(row['NavigatedToUrl']).netloc, 'visit_date': row[datetime_key] }) except KeyError as e: print(f"Warning: Missing column {e} in CSV file") continue return history
• bookmark_organizer.py:154-216 (helper)

  Deduplicator class for cleaning duplicate and similar entries.
  class Deduplicator: """Remove duplicate and redundant URLs""" def __init__(self): self.seen_urls = set() self.seen_titles = set() def normalize_url(self, url: str) -> str: """Normalize URL for comparison""" parsed = urlparse(url) # Remove common tracking parameters query_params = parse_qs(parsed.query) filtered_params = {} for key, value in query_params.items(): if key.lower() not in ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term', 'fbclid', 'gclid']: filtered_params[key] = value # Rebuild URL new_query = '&'.join([f"{k}={v[0]}" for k, v in filtered_params.items()]) normalized = f"{parsed.scheme}://{parsed.netloc}{parsed.path}" if new_query: normalized += f"?{new_query}" return normalized def is_duplicate(self, url: str, title: str = "") -> bool: """Check if URL is a duplicate""" normalized_url = self.normalize_url(url) # Check for exact URL match if normalized_url in self.seen_urls: return True # Check for similar titles (fuzzy matching) if title: title_lower = title.lower().strip() for seen_title in self.seen_titles: if self._similarity(title_lower, seen_title.lower()) > 0.8: return True # Add to seen sets self.seen_urls.add(normalized_url) if title: self.seen_titles.add(title.lower().strip()) return False def _similarity(self, s1: str, s2: str) -> float: """Calculate similarity between two strings""" if not s1 or not s2: return 0.0 # Simple Jaccard similarity set1 = set(s1.split()) set2 = set(s2.split()) intersection = len(set1.intersection(set2)) union = len(set1.union(set2)) return intersection / union if union > 0 else 0.0
• bookmark_organizer.py:74-153 (helper)

  ContentAnalyzer class for categorization and keyword extraction.
  class ContentAnalyzer: """Analyze content and categorize URLs""" def __init__(self): self.categories = { 'programming': { 'keywords': ['github', 'stackoverflow', 'coding', 'programming', 'developer', 'api', 'documentation', 'tutorial', 'code', 'python', 'javascript', 'java', 'react', 'node', 'git'], 'domains': ['github.com', 'stackoverflow.com', 'developer.mozilla.org', 'docs.python.org', 'nodejs.org', 'reactjs.org'] }, 'data_science': { 'keywords': ['data', 'analytics', 'machine learning', 'ai', 'pandas', 'numpy', 'tensorflow', 'pytorch', 'jupyter', 'databricks', 'spark', 'sql', 'database'], 'domains': ['kaggle.com', 'databricks.com', 'pandas.pydata.org', 'numpy.org', 'tensorflow.org', 'pytorch.org'] }, 'education': { 'keywords': ['course', 'learn', 'education', 'university', 'college', 'tutorial', 'lesson', 'study', 'academic', 'research'], 'domains': ['coursera.org', 'edx.org', 'udemy.com', 'khanacademy.org', 'mit.edu', 'stanford.edu'] }, 'news': { 'keywords': ['news', 'article', 'blog', 'post', 'medium', 'substack', 'newsletter'], 'domains': ['bbc.com', 'cnn.com', 'reuters.com', 'medium.com', 'substack.com'] }, 'social': { 'keywords': ['twitter', 'facebook', 'instagram', 'linkedin', 'reddit', 'social', 'community'], 'domains': ['twitter.com', 'x.com', 'facebook.com', 'instagram.com', 'linkedin.com', 'reddit.com'] }, 'tools': { 'keywords': ['tool', 'utility', 'converter', 'calculator', 'generator', 'editor', 'design', 'productivity'], 'domains': ['canva.com', 'figma.com', 'notion.so', 'trello.com', 'slack.com'] }, 'entertainment': { 'keywords': ['video', 'music', 'game', 'movie', 'entertainment', 'youtube', 'netflix', 'spotify'], 'domains': ['youtube.com', 'netflix.com', 'spotify.com', 'twitch.tv', 'steam.com'] }, 'shopping': { 'keywords': ['shop', 'buy', 'store', 'amazon', 'ebay', 'price', 'deal', 'discount'], 'domains': ['amazon.com', 'ebay.com', 'etsy.com', 'shopify.com'] } } def categorize_url(self, url: str, title: str = "") -> str: """Categorize a URL based on domain and content""" domain = urlparse(url).netloc.lower() text_to_analyze = f"{url} {title}".lower() scores = defaultdict(int) for category, data in self.categories.items(): # Check domain matches for cat_domain in data['domains']: if cat_domain in domain: scores[category] += 3 # Check keyword matches for keyword in data['keywords']: if keyword in text_to_analyze: scores[category] += 1 if scores: return max(scores, key=scores.get) return 'uncategorized' def extract_keywords(self, url: str, title: str = "") -> List[str]: """Extract relevant keywords from URL and title""" keywords = set() # Extract from URL path parsed = urlparse(url) path_parts = [part for part in parsed.path.split('/') if part and len(part) > 2] keywords.update(path_parts) # Extract from title title_words = re.findall(r'\b\w+\b', title.lower()) keywords.update([word for word in title_words if len(word) > 3]) # Extract from domain domain_parts = parsed.netloc.split('.') keywords.update([part for part in domain_parts if len(part) > 2 and part not in ['com', 'org', 'net', 'edu']]) return list(keywords)[:10] # Limit to 10 keywords