🔨 Implement core functionality for Job Search MCP Server, including user profile management, job search, cover letter generation, and Q&A response tools. Add configuration and service layers, and establish dependency management with uv. Introduce .gitignore and .python-version files for environment setup.

.cursor/rules/uv-package-manager.mdc

@@ -0,0 +1,70 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Package Management with `uv`
+
+These rules define strict guidelines for managing Python dependencies in this project using the `uv` dependency manager.
+
+**✅ Use `uv` exclusively**
+
+- All Python dependencies **must be installed, synchronized, and locked** using `uv`.
+- Never use `pip`, `pip-tools`, or `poetry` directly for dependency management.
+
+**🔁 Managing Dependencies**
+
+Always use these commands:
+
+```bash
+# Add or upgrade dependencies
+uv add <package>
+
+# Remove dependencies
+uv remove <package>
+
+# Reinstall all dependencies from lock file
+uv sync
+```
+
+**🔁 Scripts**
+
+```bash
+# Run script with proper dependencies
+uv run script.py
+```
+
+You can edit inline-metadata manually:
+
+```python
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "torch",
+#     "torchvision",
+#     "opencv-python",
+#     "numpy",
+#     "matplotlib",
+#     "Pillow",
+#     "timm",
+# ]
+# ///
+
+print("some python code")
+```
+
+Or using uv cli:
+
+```bash
+# Add or upgrade script dependencies
+uv add package-name --script script.py
+
+# Remove script dependencies
+uv remove package-name --script script.py
+
+# Reinstall all script dependencies from lock file
+uv sync --script script.py
+```
+    
+
+

.gitignore

@@ -0,0 +1,2 @@
+.venv
+__pycache__

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -1 +0,0 @@
-# jobsearch-mcp-server

app.py

@@ -1,230 +0,0 @@
-import gradio as gr
-import json
-from typing import Dict, List, Any
-
-
-class JobSearchMCP:
-    """Job Search MCP Server - Smart job matching and application helper"""
-
-    def __init__(self):
-        self.user_profiles = {}  # In-memory storage for demo purposes
-
-    def profile_upsert(self, user_id: str, profile_data: str) -> Dict[str, Any]:
-        """
-        Stores/updates user résumé, skills, salary expectations, and career goals
-
-        Args:
-            user_id: Unique identifier for the user
-            profile_data: JSON string containing user profile information
-
-        Returns:
-            Dict with success status and message
-        """
-        try:
-            # TODO: Implement profile storage logic
-            # - Parse profile_data JSON
-            # - Validate required fields (resume, skills, salary_wish, career_goals)
-            # - Store in database or persistent storage
-            # - Return success/error response
-
-            return {
-                "success": True,
-                "message": "Profile updated successfully",
-                "user_id": user_id,
-            }
-        except Exception as e:
-            return {"success": False, "message": f"Error updating profile: {str(e)}"}
-
-    def jobs_search(
-        self, user_id: str, query: str = "", location: str = "", job_type: str = ""
-    ) -> Dict[str, Any]:
-        """
-        Pulls fresh job posts, ranks them with GPU embeddings, and returns fit scores
-
-        Args:
-            user_id: User identifier to get personalized results
-            query: Job search query/keywords
-            location: Preferred job location
-            job_type: Type of job (full-time, contract, remote, etc.)
-
-        Returns:
-            Dict with ranked job listings and fit scores
-        """
-        try:
-            # TODO: Implement job search logic
-            # - Fetch jobs from various APIs (LinkedIn, Indeed, etc.)
-            # - Use GPU embeddings to calculate job-profile fit scores
-            # - Rank jobs by relevance and fit score
-            # - Return top matches with metadata
-
-            return {
-                "success": True,
-                "jobs": [],
-                "total_found": 0,
-                "search_params": {
-                    "query": query,
-                    "location": location,
-                    "job_type": job_type,
-                },
-            }
-        except Exception as e:
-            return {"success": False, "message": f"Error searching jobs: {str(e)}"}
-
-    def letter_generate(
-        self, user_id: str, job_description: str, tone: str = "professional"
-    ) -> Dict[str, Any]:
-        """
-        Generates personalized cover letters using LLM
-
-        Args:
-            user_id: User identifier to access profile
-            job_description: The job posting description
-            tone: Tone of the cover letter (professional, casual, enthusiastic, etc.)
-
-        Returns:
-            Dict with generated cover letter
-        """
-        try:
-            # TODO: Implement cover letter generation
-            # - Retrieve user profile
-            # - Use LLM to generate personalized cover letter
-            # - Match user skills with job requirements
-            # - Apply specified tone
-            # - Return formatted cover letter
-
-            return {
-                "success": True,
-                "cover_letter": "",
-                "tone_used": tone,
-                "word_count": 0,
-            }
-        except Exception as e:
-            return {
-                "success": False,
-                "message": f"Error generating cover letter: {str(e)}",
-            }
-
-    def qa_reply(
-        self, user_id: str, question: str, context: str = ""
-    ) -> Dict[str, Any]:
-        """
-        Drafts concise answers to client questions
-
-        Args:
-            user_id: User identifier to access profile
-            question: The question from potential employer/client
-            context: Additional context about the conversation
-
-        Returns:
-            Dict with generated response
-        """
-        try:
-            # TODO: Implement Q&A response generation
-            # - Retrieve user profile and experience
-            # - Generate contextual response using LLM
-            # - Keep response concise and professional
-            # - Tailor to user's background and skills
-
-            return {"success": True, "response": "", "confidence_score": 0.0}
-        except Exception as e:
-            return {"success": False, "message": f"Error generating response: {str(e)}"}
-
-
-# Initialize the MCP server
-mcp_server = JobSearchMCP()
-
-# Create Gradio interface for each endpoint
-with gr.Blocks(title="Job Search MCP Server") as demo:
-    gr.Markdown("# 🔍 Job Search MCP Server")
-    gr.Markdown("Smart job matching and instant application helper")
-
-    with gr.Tab("Profile Management"):
-        gr.Markdown("### Store and update your professional profile")
-        with gr.Row():
-            profile_user_id = gr.Textbox(
-                label="User ID", placeholder="Enter your unique user ID"
-            )
-            profile_data = gr.TextArea(
-                label="Profile Data (JSON)",
-                placeholder='{"resume": "...", "skills": [...], "salary_wish": "...", "career_goals": "..."}',
-                lines=5,
-            )
-        profile_submit = gr.Button("Update Profile", variant="primary")
-        profile_output = gr.JSON(label="Response")
-
-        profile_submit.click(
-            fn=mcp_server.profile_upsert,
-            inputs=[profile_user_id, profile_data],
-            outputs=profile_output,
-        )
-
-    with gr.Tab("Job Search"):
-        gr.Markdown("### Find and rank relevant job opportunities")
-        with gr.Row():
-            search_user_id = gr.Textbox(label="User ID")
-            search_query = gr.Textbox(
-                label="Search Query", placeholder="e.g., Python developer"
-            )
-        with gr.Row():
-            search_location = gr.Textbox(
-                label="Location", placeholder="e.g., Remote, New York"
-            )
-            search_job_type = gr.Dropdown(
-                label="Job Type",
-                choices=["full-time", "part-time", "contract", "freelance", "remote"],
-                value="full-time",
-            )
-        search_submit = gr.Button("Search Jobs", variant="primary")
-        search_output = gr.JSON(label="Job Results")
-
-        search_submit.click(
-            fn=mcp_server.jobs_search,
-            inputs=[search_user_id, search_query, search_location, search_job_type],
-            outputs=search_output,
-        )
-
-    with gr.Tab("Cover Letter Generator"):
-        gr.Markdown("### Generate personalized cover letters")
-        with gr.Row():
-            letter_user_id = gr.Textbox(label="User ID")
-            letter_tone = gr.Dropdown(
-                label="Tone",
-                choices=["professional", "casual", "enthusiastic", "formal"],
-                value="professional",
-            )
-        letter_job_desc = gr.TextArea(
-            label="Job Description",
-            placeholder="Paste the job description here...",
-            lines=5,
-        )
-        letter_submit = gr.Button("Generate Cover Letter", variant="primary")
-        letter_output = gr.JSON(label="Generated Letter")
-
-        letter_submit.click(
-            fn=mcp_server.letter_generate,
-            inputs=[letter_user_id, letter_job_desc, letter_tone],
-            outputs=letter_output,
-        )
-
-    with gr.Tab("Q&A Assistant"):
-        gr.Markdown("### Get help with interview questions and client responses")
-        with gr.Row():
-            qa_user_id = gr.Textbox(label="User ID")
-            qa_context = gr.Textbox(
-                label="Context (optional)", placeholder="Additional context..."
-            )
-        qa_question = gr.TextArea(
-            label="Question", placeholder="e.g., Why should we hire you?", lines=3
-        )
-        qa_submit = gr.Button("Generate Response", variant="primary")
-        qa_output = gr.JSON(label="Generated Response")
-
-        qa_submit.click(
-            fn=mcp_server.qa_reply,
-            inputs=[qa_user_id, qa_question, qa_context],
-            outputs=qa_output,
-        )
-
-if __name__ == "__main__":
-    # Enable MCP server functionality
-    demo.launch(enable_mcp=True)

config.py

@@ -1,62 +0,0 @@
-import os
-from dotenv import load_dotenv
-
-# Load environment variables from .env file
-load_dotenv()
-
-
-class Config:
-    """Configuration settings for Job Search MCP Server"""
-
-    # API Keys
-    OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
-    ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
-    HUGGINGFACE_API_KEY = os.getenv("HUGGINGFACE_API_KEY")
-
-    # Job Search APIs
-    LINKEDIN_API_KEY = os.getenv("LINKEDIN_API_KEY")
-    INDEED_API_KEY = os.getenv("INDEED_API_KEY")
-    GLASSDOOR_API_KEY = os.getenv("GLASSDOOR_API_KEY")
-
-    # Database Settings (for future implementation)
-    DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///jobsearch.db")
-
-    # Embedding Model Settings
-    EMBEDDING_MODEL = os.getenv(
-        "EMBEDDING_MODEL", "sentence-transformers/all-MiniLM-L6-v2"
-    )
-    EMBEDDING_CACHE_SIZE = int(os.getenv("EMBEDDING_CACHE_SIZE", "1000"))
-
-    # LLM Settings
-    DEFAULT_LLM_MODEL = os.getenv("DEFAULT_LLM_MODEL", "gpt-3.5-turbo")
-    MAX_TOKENS = int(os.getenv("MAX_TOKENS", "1000"))
-    TEMPERATURE = float(os.getenv("TEMPERATURE", "0.7"))
-
-    # Job Search Settings
-    MAX_JOBS_PER_SEARCH = int(os.getenv("MAX_JOBS_PER_SEARCH", "50"))
-    MIN_MATCH_SCORE = float(os.getenv("MIN_MATCH_SCORE", "0.6"))
-
-    # Cover Letter Settings
-    MAX_COVER_LETTER_WORDS = int(os.getenv("MAX_COVER_LETTER_WORDS", "300"))
-
-    # Server Settings
-    SERVER_HOST = os.getenv("SERVER_HOST", "127.0.0.1")
-    SERVER_PORT = int(os.getenv("SERVER_PORT", "7860"))
-    DEBUG = os.getenv("DEBUG", "False").lower() == "true"
-
-    @classmethod
-    def validate_config(cls):
-        """Validate that required configuration is present"""
-        required_keys = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"]
-
-        missing_keys = []
-        for key in required_keys:
-            if not getattr(cls, key):
-                missing_keys.append(key)
-
-        if missing_keys:
-            raise ValueError(
-                f"Missing required environment variables: {', '.join(missing_keys)}"
-            )
-
-        return True

main.py

@@ -0,0 +1,430 @@
+#!/usr/bin/env python3
+"""
+Job Search MCP Server - Smart job matching and instant application helper
+
+Main entry point for the MCP server that exposes the four core endpoints:
+1. profile.upsert - Store user résumé, skills, salary wish, and career goals
+2. jobs.search - Pull fresh job posts, rank with GPU embeddings, return fit scores
+3. letter.generate - Create personalized cover letters using LLM
+4. qa.reply - Draft concise answers to client questions
+
+This server uses both GPU processing for embeddings and LLM APIs for text generation,
+demonstrating efficient use of both credit pools.
+"""
+
+import asyncio
+import gradio as gr
+from typing import Dict, Any
+
+from src.tools import ProfileTool, JobSearchTool, CoverLetterTool, QATool
+from src.config import get_settings
+
+
+class JobSearchMCPServer:
+    """Main MCP server class integrating all job search tools."""
+
+    def __init__(self):
+        self.settings = get_settings()
+
+        # Initialize all tools
+        self.profile_tool = ProfileTool()
+        self.job_search_tool = JobSearchTool()
+        self.cover_letter_tool = CoverLetterTool()
+        self.qa_tool = QATool()
+
+        print(f"🚀 Job Search MCP Server initialized")
+        print(f"📊 GPU Embeddings: {self.settings.embedding_model}")
+        print(f"🤖 LLM Provider: {self.settings.llm_provider}")
+
+    # Core MCP Endpoints
+
+    def profile_upsert(self, user_id: str, profile_data: str) -> Dict[str, Any]:
+        """
+        MCP Endpoint: profile.upsert
+
+        Stores the user résumé, skills, salary expectations, and career goals.
+        Keeps personal context so every later call is tailored.
+        """
+        return self.profile_tool.upsert(user_id, profile_data)
+
+    def jobs_search(
+        self, user_id: str, query: str = "", location: str = "", job_type: str = ""
+    ) -> Dict[str, Any]:
+        """
+        MCP Endpoint: jobs.search
+
+        Pulls fresh job posts, ranks them with GPU embeddings, and returns a fit score.
+        Users see the most relevant roles first, no endless scrolling.
+        """
+        return self.job_search_tool.search(user_id, query, location, job_type)
+
+    def letter_generate(
+        self, user_id: str, job_description: str, tone: str = "professional"
+    ) -> Dict[str, Any]:
+        """
+        MCP Endpoint: letter.generate
+
+        Calls an LLM to create a short, personalized cover letter in any tone.
+        Saves time and improves response quality.
+        """
+        return self.cover_letter_tool.generate(user_id, job_description, tone)
+
+    def qa_reply(
+        self, user_id: str, question: str, context: str = ""
+    ) -> Dict[str, Any]:
+        """
+        MCP Endpoint: qa.reply
+
+        Drafts concise answers to client questions like "Why should we hire you?"
+        Speeds up Upwork, Fiverr, or LinkedIn chats.
+        """
+        return self.qa_tool.reply(user_id, question, context)
+
+    # Additional Helper Endpoints
+
+    def get_server_stats(self) -> Dict[str, Any]:
+        """Get server statistics and health information."""
+        try:
+            from src.services import EmbeddingService
+
+            embedding_service = EmbeddingService()
+            embed_stats = embedding_service.get_index_stats()
+
+            return {
+                "success": True,
+                "server_info": {
+                    "app_name": self.settings.app_name,
+                    "embedding_model": self.settings.embedding_model,
+                    "llm_provider": self.settings.llm_provider,
+                    "llm_model": self.settings.llm_model,
+                },
+                "embedding_stats": embed_stats,
+                "endpoints": [
+                    "profile.upsert",
+                    "jobs.search",
+                    "letter.generate",
+                    "qa.reply",
+                ],
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"Error getting server stats: {str(e)}",
+            }
+
+
+# Initialize the MCP server
+mcp_server = JobSearchMCPServer()
+
+
+# Create Gradio interface for easy testing and demonstration
+def create_gradio_interface():
+    """Create a Gradio interface for the MCP server."""
+
+    with gr.Blocks(
+        title="Job Search MCP Server",
+        theme=gr.themes.Soft(),
+        css="""
+        .gradio-container {
+            max-width: 1200px !important;
+        }
+        .main-header {
+            text-align: center;
+            background: linear-gradient(45deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            padding: 20px;
+            border-radius: 10px;
+            margin-bottom: 20px;
+        }
+        """,
+    ) as demo:
+        # Header
+        gr.HTML("""
+        <div class="main-header">
+            <h1>🔍 Job Search MCP Server</h1>
+            <p>Smart job matching and instant application helper</p>
+            <p><strong>4 Core Endpoints:</strong> profile.upsert | jobs.search | letter.generate | qa.reply</p>
+        </div>
+        """)
+
+        # Server Stats
+        with gr.Row():
+            with gr.Column():
+                stats_button = gr.Button("📊 Get Server Stats", variant="secondary")
+                stats_output = gr.JSON(label="Server Statistics")
+
+                stats_button.click(fn=mcp_server.get_server_stats, outputs=stats_output)
+
+        # Main endpoints in tabs
+        with gr.Tabs():
+            # Profile Management Tab
+            with gr.Tab("👤 Profile Management (profile.upsert)"):
+                gr.Markdown("### Store and update your professional profile")
+                gr.Markdown(
+                    "*This endpoint keeps personal context so every later call is tailored*"
+                )
+
+                with gr.Row():
+                    with gr.Column():
+                        profile_user_id = gr.Textbox(
+                            label="User ID",
+                            placeholder="Enter your unique user ID (e.g., john_doe_2024)",
+                            value="demo_user",
+                        )
+                        profile_data = gr.TextArea(
+                            label="Profile Data (JSON)",
+                            placeholder='{\n  "resume": "Full resume text here...",\n  "skills": ["Python", "JavaScript", "React", "Node.js"],\n  "salary_wish": "$80,000 - $120,000 annually",\n  "career_goals": "Looking to transition into a senior full-stack developer role at a tech company",\n  "experience_level": "Mid-level",\n  "location": "Remote",\n  "education": "BS Computer Science"\n}',
+                            lines=8,
+                        )
+                        profile_submit = gr.Button(
+                            "💾 Update Profile", variant="primary"
+                        )
+
+                    with gr.Column():
+                        profile_output = gr.JSON(label="Response")
+
+                        # Quick profile actions
+                        with gr.Row():
+                            get_profile_btn = gr.Button(
+                                "👁️ View Profile", variant="secondary"
+                            )
+                            delete_profile_btn = gr.Button(
+                                "🗑️ Delete Profile", variant="secondary"
+                            )
+
+                profile_submit.click(
+                    fn=mcp_server.profile_upsert,
+                    inputs=[profile_user_id, profile_data],
+                    outputs=profile_output,
+                )
+
+                get_profile_btn.click(
+                    fn=mcp_server.profile_tool.get,
+                    inputs=[profile_user_id],
+                    outputs=profile_output,
+                )
+
+                delete_profile_btn.click(
+                    fn=mcp_server.profile_tool.delete,
+                    inputs=[profile_user_id],
+                    outputs=profile_output,
+                )
+
+            # Job Search Tab
+            with gr.Tab("🔍 Job Search (jobs.search)"):
+                gr.Markdown(
+                    "### Find and rank relevant job opportunities with GPU embeddings"
+                )
+                gr.Markdown(
+                    "*Pulls fresh job posts, ranks them with GPU embeddings, and returns fit scores*"
+                )
+
+                with gr.Row():
+                    with gr.Column():
+                        search_user_id = gr.Textbox(label="User ID", value="demo_user")
+                        search_query = gr.Textbox(
+                            label="Search Query",
+                            placeholder="e.g., Python developer, Data scientist, Frontend engineer",
+                        )
+
+                        with gr.Row():
+                            search_location = gr.Textbox(
+                                label="Location",
+                                placeholder="e.g., Remote, New York, San Francisco",
+                            )
+                            search_job_type = gr.Dropdown(
+                                label="Job Type",
+                                choices=[
+                                    "full-time",
+                                    "part-time",
+                                    "contract",
+                                    "freelance",
+                                    "remote",
+                                ],
+                                value="full-time",
+                            )
+
+                        search_submit = gr.Button("🔍 Search Jobs", variant="primary")
+
+                    with gr.Column():
+                        search_output = gr.JSON(label="Job Results with Fit Scores")
+
+                        # Additional job search features
+                        suggestions_btn = gr.Button(
+                            "💡 Get Search Suggestions", variant="secondary"
+                        )
+                        clear_cache_btn = gr.Button(
+                            "🗑️ Clear Job Cache", variant="secondary"
+                        )
+
+                search_submit.click(
+                    fn=mcp_server.jobs_search,
+                    inputs=[
+                        search_user_id,
+                        search_query,
+                        search_location,
+                        search_job_type,
+                    ],
+                    outputs=search_output,
+                )
+
+                suggestions_btn.click(
+                    fn=mcp_server.job_search_tool.get_search_suggestions,
+                    inputs=[search_user_id],
+                    outputs=search_output,
+                )
+
+                clear_cache_btn.click(
+                    fn=mcp_server.job_search_tool.clear_job_cache, outputs=search_output
+                )
+
+            # Cover Letter Generator Tab
+            with gr.Tab("📝 Cover Letter (letter.generate)"):
+                gr.Markdown("### Generate personalized cover letters using LLM")
+                gr.Markdown(
+                    "*Creates short, personalized cover letters in any tone - saves time and improves quality*"
+                )
+
+                with gr.Row():
+                    with gr.Column():
+                        letter_user_id = gr.Textbox(label="User ID", value="demo_user")
+                        letter_tone = gr.Dropdown(
+                            label="Tone",
+                            choices=[
+                                "professional",
+                                "casual",
+                                "enthusiastic",
+                                "formal",
+                            ],
+                            value="professional",
+                        )
+                        letter_job_desc = gr.TextArea(
+                            label="Job Description",
+                            placeholder="Paste the complete job description here...",
+                            lines=6,
+                        )
+                        letter_submit = gr.Button(
+                            "📝 Generate Cover Letter", variant="primary"
+                        )
+
+                    with gr.Column():
+                        letter_output = gr.JSON(label="Generated Cover Letter")
+
+                        # Additional cover letter features
+                        multiple_tones_btn = gr.Button(
+                            "🎭 Generate Multiple Tones", variant="secondary"
+                        )
+                        template_btn = gr.Button("📋 Get Template", variant="secondary")
+
+                letter_submit.click(
+                    fn=mcp_server.letter_generate,
+                    inputs=[letter_user_id, letter_job_desc, letter_tone],
+                    outputs=letter_output,
+                )
+
+                multiple_tones_btn.click(
+                    fn=mcp_server.cover_letter_tool.generate_multiple_tones,
+                    inputs=[letter_user_id, letter_job_desc],
+                    outputs=letter_output,
+                )
+
+                template_btn.click(
+                    fn=mcp_server.cover_letter_tool.get_cover_letter_template,
+                    inputs=[letter_tone],
+                    outputs=letter_output,
+                )
+
+            # Q&A Assistant Tab
+            with gr.Tab("💬 Q&A Assistant (qa.reply)"):
+                gr.Markdown(
+                    "### Get help with interview questions and client responses"
+                )
+                gr.Markdown(
+                    "*Drafts concise answers to speed up Upwork, Fiverr, or LinkedIn chats*"
+                )
+
+                with gr.Row():
+                    with gr.Column():
+                        qa_user_id = gr.Textbox(label="User ID", value="demo_user")
+                        qa_question = gr.TextArea(
+                            label="Question",
+                            placeholder="e.g., Why should we hire you?\nWhat's your experience with Python?\nHow much do you charge for this project?",
+                            lines=4,
+                        )
+                        qa_context = gr.Textbox(
+                            label="Context (optional)",
+                            placeholder="Additional context about the role or conversation...",
+                        )
+                        qa_submit = gr.Button("💬 Generate Response", variant="primary")
+
+                    with gr.Column():
+                        qa_output = gr.JSON(label="Generated Response")
+
+                        # Additional Q&A features
+                        with gr.Row():
+                            common_questions_btn = gr.Button(
+                                "❓ Common Questions", variant="secondary"
+                            )
+                            practice_session_btn = gr.Button(
+                                "🎯 Practice Session", variant="secondary"
+                            )
+
+                qa_submit.click(
+                    fn=mcp_server.qa_reply,
+                    inputs=[qa_user_id, qa_question, qa_context],
+                    outputs=qa_output,
+                )
+
+                common_questions_btn.click(
+                    fn=lambda: mcp_server.qa_tool.get_common_questions("developer"),
+                    outputs=qa_output,
+                )
+
+                practice_session_btn.click(
+                    fn=lambda uid: mcp_server.qa_tool.practice_session(
+                        uid, "developer", 3
+                    ),
+                    inputs=[qa_user_id],
+                    outputs=qa_output,
+                )
+
+        # Footer with usage information
+        gr.HTML("""
+        <div style="margin-top: 40px; padding: 20px; background-color: #f0f0f0; border-radius: 10px;">
+            <h3>🎯 How It Works</h3>
+            <p><strong>GPU Part (T4-small):</strong> The server embeds user profile text and each job post with a modern sentence-embedding model. A FAISS index runs similarity search in real time.</p>
+            <p><strong>Inference-API Part:</strong> A hosted LLM writes cover letters and Q&A replies. Average call is under 300 tokens.</p>
+            <p><strong>Typical User Flow:</strong></p>
+            <ol>
+                <li>Upload résumé and skills once using <code>profile.upsert</code></li>
+                <li>Call <code>jobs.search</code> with a role keyword (e.g., "LLM engineer")</li>
+                <li>Get a ranked list of matches with fit percentages</li>
+                <li>Pick a job ID and call <code>letter.generate</code> to copy a ready cover letter</li>
+                <li>When the recruiter asks something, send the question to <code>qa.reply</code> for an instant answer</li>
+            </ol>
+            <p><strong>Benefits:</strong> Cuts application time by 80%+, reduces copy-pasted cover letters, improves job-to-skill matching</p>
+        </div>
+        """)
+
+    return demo
+
+
+def main():
+    """Main entry point for the application."""
+    print("🚀 Starting Job Search MCP Server...")
+
+    # Create and launch Gradio interface
+    demo = create_gradio_interface()
+
+    # Launch with MCP enabled
+    demo.launch(
+        server_name=mcp_server.settings.host,
+        server_port=mcp_server.settings.port,
+        enable_mcp=True,
+        share=False,
+        show_error=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "jobsearch-mcp-server"
+version = "0.1.0"
+description = "Smart job matching and instant application helper MCP server"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "gradio[mcp]>=5.0.0",
+    "openai>=1.0.0",
+    "anthropic>=0.30.0",
+    "requests>=2.31.0",
+    "python-dotenv>=1.0.0",
+    "numpy>=1.24.0",
+    "sentence-transformers>=2.2.0",
+    "scikit-learn>=1.3.0",
+    "pandas>=2.0.0",
+    "beautifulsoup4>=4.12.0",
+    "lxml>=4.9.0",
+    "httpx>=0.24.0",
+    "pydantic>=2.0.0",
+    "python-multipart>=0.0.6",
+    "faiss-cpu>=1.7.0",
+    "torch>=2.0.0",
+    "transformers>=4.30.0",
+    "datasets>=2.14.0",
+    "aiohttp>=3.8.0",
+    "typing-extensions>=4.5.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+    "flake8>=6.0.0",
+    "mypy>=1.0.0"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+
+[tool.isort]
+profile = "black"

src/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration module for Job Search MCP Server."""
+
+from .settings import Settings, get_settings
+
+__all__ = ["Settings", "get_settings"]

src/config/settings.py

@@ -0,0 +1,62 @@
+"""Settings and configuration for the Job Search MCP Server."""
+
+import os
+from functools import lru_cache
+from typing import Optional
+
+from pydantic import BaseSettings, Field
+
+
+class Settings(BaseSettings):
+    """Application settings and configuration."""
+
+    # API Keys
+    openai_api_key: Optional[str] = Field(default=None, env="OPENAI_API_KEY")
+    anthropic_api_key: Optional[str] = Field(default=None, env="ANTHROPIC_API_KEY")
+
+    # Job Search APIs
+    linkedin_api_key: Optional[str] = Field(default=None, env="LINKEDIN_API_KEY")
+    indeed_api_key: Optional[str] = Field(default=None, env="INDEED_API_KEY")
+
+    # Embedding Model Settings
+    embedding_model: str = Field(default="all-MiniLM-L6-v2", env="EMBEDDING_MODEL")
+    embedding_dimension: int = Field(default=384, env="EMBEDDING_DIMENSION")
+
+    # LLM Settings
+    llm_provider: str = Field(default="openai", env="LLM_PROVIDER")  # openai, anthropic
+    llm_model: str = Field(default="gpt-3.5-turbo", env="LLM_MODEL")
+    max_tokens: int = Field(default=300, env="MAX_TOKENS")
+    temperature: float = Field(default=0.7, env="TEMPERATURE")
+
+    # Application Settings
+    app_name: str = Field(default="Job Search MCP Server", env="APP_NAME")
+    debug: bool = Field(default=False, env="DEBUG")
+    host: str = Field(default="127.0.0.1", env="HOST")
+    port: int = Field(default=7860, env="PORT")
+
+    # Storage Settings
+    profiles_db_path: str = Field(
+        default="./data/profiles.json", env="PROFILES_DB_PATH"
+    )
+    jobs_cache_path: str = Field(
+        default="./data/jobs_cache.json", env="JOBS_CACHE_PATH"
+    )
+    embeddings_cache_path: str = Field(
+        default="./data/embeddings.faiss", env="EMBEDDINGS_CACHE_PATH"
+    )
+
+    # Search Settings
+    max_jobs_per_search: int = Field(default=50, env="MAX_JOBS_PER_SEARCH")
+    similarity_threshold: float = Field(default=0.7, env="SIMILARITY_THRESHOLD")
+
+    class Config:
+        """Pydantic config."""
+
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Get cached settings instance."""
+    return Settings()

src/services/__init__.py

@@ -0,0 +1,8 @@
+"""Services module for Job Search MCP Server."""
+
+from .embedding_service import EmbeddingService
+from .llm_service import LLMService
+from .job_search_service import JobSearchService
+from .profile_service import ProfileService
+
+__all__ = ["EmbeddingService", "LLMService", "JobSearchService", "ProfileService"]

src/services/embedding_service.py

@@ -0,0 +1,206 @@
+"""Embedding service for text embeddings and similarity search using GPU."""
+
+import json
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+import faiss
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+from ..config import get_settings
+
+
+class EmbeddingService:
+    """Service for text embeddings and similarity search."""
+
+    def __init__(self):
+        self.settings = get_settings()
+        self.model = None
+        self.index = None
+        self.job_metadata = {}
+        self._load_model()
+        self._load_index()
+
+    def _load_model(self):
+        """Load the sentence transformer model."""
+        try:
+            self.model = SentenceTransformer(self.settings.embedding_model)
+            # Use GPU if available
+            if hasattr(self.model, "to"):
+                import torch
+
+                device = "cuda" if torch.cuda.is_available() else "cpu"
+                self.model = self.model.to(device)
+                print(f"Embedding model loaded on: {device}")
+        except Exception as e:
+            print(f"Error loading embedding model: {e}")
+            self.model = None
+
+    def _load_index(self):
+        """Load or create FAISS index."""
+        try:
+            if os.path.exists(self.settings.embeddings_cache_path):
+                self.index = faiss.read_index(self.settings.embeddings_cache_path)
+                # Load metadata
+                metadata_path = self.settings.embeddings_cache_path.replace(
+                    ".faiss", "_metadata.json"
+                )
+                if os.path.exists(metadata_path):
+                    with open(metadata_path, "r", encoding="utf-8") as f:
+                        self.job_metadata = json.load(f)
+                print(f"Loaded FAISS index with {self.index.ntotal} vectors")
+            else:
+                # Create new index
+                self.index = faiss.IndexFlatIP(self.settings.embedding_dimension)
+                print("Created new FAISS index")
+        except Exception as e:
+            print(f"Error loading FAISS index: {e}")
+            self.index = faiss.IndexFlatIP(self.settings.embedding_dimension)
+
+    def _save_index(self):
+        """Save FAISS index and metadata."""
+        try:
+            os.makedirs(
+                os.path.dirname(self.settings.embeddings_cache_path), exist_ok=True
+            )
+            faiss.write_index(self.index, self.settings.embeddings_cache_path)
+
+            # Save metadata
+            metadata_path = self.settings.embeddings_cache_path.replace(
+                ".faiss", "_metadata.json"
+            )
+            with open(metadata_path, "w", encoding="utf-8") as f:
+                json.dump(self.job_metadata, f, indent=2, default=str)
+
+            print(f"Saved FAISS index with {self.index.ntotal} vectors")
+        except Exception as e:
+            print(f"Error saving FAISS index: {e}")
+
+    def get_embedding(self, text: str) -> Optional[np.ndarray]:
+        """Get embedding for a single text."""
+        if not self.model:
+            return None
+
+        try:
+            embedding = self.model.encode([text])
+            # Normalize for cosine similarity (using Inner Product index)
+            embedding = embedding / np.linalg.norm(embedding, axis=1, keepdims=True)
+            return embedding[0]
+        except Exception as e:
+            print(f"Error generating embedding: {e}")
+            return None
+
+    def get_embeddings(self, texts: List[str]) -> Optional[np.ndarray]:
+        """Get embeddings for multiple texts."""
+        if not self.model:
+            return None
+
+        try:
+            embeddings = self.model.encode(texts, show_progress_bar=True)
+            # Normalize for cosine similarity
+            embeddings = embeddings / np.linalg.norm(embeddings, axis=1, keepdims=True)
+            return embeddings
+        except Exception as e:
+            print(f"Error generating embeddings: {e}")
+            return None
+
+    def add_job_embeddings(self, jobs: List[Dict[str, Any]]):
+        """Add job embeddings to the index."""
+        if not jobs:
+            return
+
+        # Prepare texts for embedding
+        texts = []
+        job_ids = []
+
+        for job in jobs:
+            # Combine job title, description, and requirements for embedding
+            job_text = f"{job.get('title', '')} {job.get('description', '')} {job.get('requirements', '')}"
+            texts.append(job_text)
+            job_ids.append(job.get("id", len(self.job_metadata)))
+
+        # Get embeddings
+        embeddings = self.get_embeddings(texts)
+        if embeddings is None:
+            return
+
+        # Add to index
+        self.index.add(embeddings.astype("float32"))
+
+        # Store metadata
+        for i, job in enumerate(jobs):
+            job_id = job_ids[i]
+            self.job_metadata[str(len(self.job_metadata))] = {
+                "job_id": job_id,
+                "title": job.get("title", ""),
+                "company": job.get("company", ""),
+                "location": job.get("location", ""),
+                "salary": job.get("salary", ""),
+                "url": job.get("url", ""),
+                "posted_date": job.get("posted_date", ""),
+                "job_type": job.get("job_type", ""),
+                "description": job.get("description", "")[:500],  # Truncate for storage
+            }
+
+        self._save_index()
+        print(f"Added {len(jobs)} job embeddings to index")
+
+    def search_similar_jobs(
+        self, profile_text: str, k: int = 20
+    ) -> List[Tuple[Dict[str, Any], float]]:
+        """
+        Search for jobs similar to user profile.
+
+        Args:
+            profile_text: Combined user profile text for matching
+            k: Number of top results to return
+
+        Returns:
+            List of tuples (job_metadata, similarity_score)
+        """
+        if not self.index or self.index.ntotal == 0:
+            return []
+
+        # Get profile embedding
+        profile_embedding = self.get_embedding(profile_text)
+        if profile_embedding is None:
+            return []
+
+        # Search index
+        try:
+            scores, indices = self.index.search(
+                profile_embedding[np.newaxis].astype("float32"),
+                min(k, self.index.ntotal),
+            )
+
+            results = []
+            for i, (score, idx) in enumerate(zip(scores[0], indices[0])):
+                if idx == -1:  # Invalid index
+                    continue
+
+                job_meta = self.job_metadata.get(str(idx))
+                if job_meta:
+                    results.append((job_meta, float(score)))
+
+            return results
+
+        except Exception as e:
+            print(f"Error searching similar jobs: {e}")
+            return []
+
+    def clear_index(self):
+        """Clear the index and metadata."""
+        self.index = faiss.IndexFlatIP(self.settings.embedding_dimension)
+        self.job_metadata = {}
+        self._save_index()
+        print("Cleared job embeddings index")
+
+    def get_index_stats(self) -> Dict[str, Any]:
+        """Get statistics about the index."""
+        return {
+            "total_jobs": self.index.ntotal if self.index else 0,
+            "embedding_dimension": self.settings.embedding_dimension,
+            "model_name": self.settings.embedding_model,
+            "metadata_count": len(self.job_metadata),
+        }

src/services/job_search_service.py

@@ -0,0 +1,362 @@
+"""Job search service for fetching and ranking job posts."""
+
+import json
+import os
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+import requests
+from bs4 import BeautifulSoup
+
+from ..config import get_settings
+from .embedding_service import EmbeddingService
+from .profile_service import ProfileService, UserProfile
+
+
+class JobSearchService:
+    """Service for searching and ranking job posts."""
+
+    def __init__(self):
+        self.settings = get_settings()
+        self.embedding_service = EmbeddingService()
+        self.profile_service = ProfileService()
+        self.jobs_cache = {}
+        self._load_cache()
+
+    def _load_cache(self):
+        """Load jobs cache from file."""
+        try:
+            if os.path.exists(self.settings.jobs_cache_path):
+                with open(self.settings.jobs_cache_path, "r", encoding="utf-8") as f:
+                    self.jobs_cache = json.load(f)
+        except Exception as e:
+            print(f"Error loading jobs cache: {e}")
+            self.jobs_cache = {}
+
+    def _save_cache(self):
+        """Save jobs cache to file."""
+        try:
+            os.makedirs(os.path.dirname(self.settings.jobs_cache_path), exist_ok=True)
+            with open(self.settings.jobs_cache_path, "w", encoding="utf-8") as f:
+                json.dump(self.jobs_cache, f, indent=2, default=str)
+        except Exception as e:
+            print(f"Error saving jobs cache: {e}")
+
+    def _fetch_indeed_jobs(
+        self, query: str, location: str, job_type: str
+    ) -> List[Dict[str, Any]]:
+        """Fetch jobs from Indeed (web scraping - for demo purposes)."""
+        jobs = []
+
+        try:
+            # Construct Indeed search URL
+            base_url = "https://www.indeed.com/jobs"
+            params = {
+                "q": query,
+                "l": location,
+                "jt": job_type
+                if job_type in ["fulltime", "parttime", "contract"]
+                else "",
+                "limit": min(self.settings.max_jobs_per_search, 50),
+            }
+
+            # Build URL
+            url = f"{base_url}?" + "&".join(
+                [f"{k}={quote(str(v))}" for k, v in params.items() if v]
+            )
+
+            # Headers to mimic browser request
+            headers = {
+                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
+            }
+
+            # Make request with timeout
+            response = requests.get(url, headers=headers, timeout=10)
+            response.raise_for_status()
+
+            # Parse HTML
+            soup = BeautifulSoup(response.content, "html.parser")
+
+            # Find job cards (Indeed's structure may change)
+            job_cards = soup.find_all("div", class_="job_seen_beacon")
+
+            for i, card in enumerate(job_cards[: self.settings.max_jobs_per_search]):
+                try:
+                    # Extract job information
+                    title_elem = card.find("h2", class_="jobTitle")
+                    title = (
+                        title_elem.get_text(strip=True)
+                        if title_elem
+                        else f"Position {i+1}"
+                    )
+
+                    company_elem = card.find("span", class_="companyName")
+                    company = (
+                        company_elem.get_text(strip=True)
+                        if company_elem
+                        else "Unknown Company"
+                    )
+
+                    location_elem = card.find("div", class_="companyLocation")
+                    job_location = (
+                        location_elem.get_text(strip=True)
+                        if location_elem
+                        else location
+                    )
+
+                    summary_elem = card.find("div", class_="job-snippet")
+                    summary = summary_elem.get_text(strip=True) if summary_elem else ""
+
+                    # Try to get job URL
+                    link_elem = title_elem.find("a") if title_elem else None
+                    job_url = (
+                        f"https://www.indeed.com{link_elem['href']}"
+                        if link_elem and link_elem.get("href")
+                        else ""
+                    )
+
+                    job = {
+                        "id": f"indeed_{i}_{hash(title + company)}",
+                        "title": title,
+                        "company": company,
+                        "location": job_location,
+                        "description": summary,
+                        "requirements": "",  # Would need individual job page scraping
+                        "salary": "",  # Would need more detailed scraping
+                        "url": job_url,
+                        "posted_date": datetime.now().isoformat(),
+                        "job_type": job_type or "full-time",
+                        "source": "indeed",
+                    }
+
+                    jobs.append(job)
+
+                except Exception as e:
+                    print(f"Error parsing job card {i}: {e}")
+                    continue
+
+        except Exception as e:
+            print(f"Error fetching Indeed jobs: {e}")
+
+        return jobs
+
+    def _fetch_sample_jobs(
+        self, query: str, location: str, job_type: str
+    ) -> List[Dict[str, Any]]:
+        """Generate sample jobs for demo purposes."""
+        sample_jobs = [
+            {
+                "id": "sample_1",
+                "title": f"Senior {query} Developer",
+                "company": "TechCorp Solutions",
+                "location": location or "Remote",
+                "description": f"We are looking for an experienced {query} developer to join our dynamic team. You will work on cutting-edge projects using modern technologies and best practices.",
+                "requirements": f"5+ years experience with {query}, strong problem-solving skills, team collaboration",
+                "salary": "$80,000 - $120,000",
+                "url": "https://example.com/job1",
+                "posted_date": datetime.now().isoformat(),
+                "job_type": job_type or "full-time",
+                "source": "sample",
+            },
+            {
+                "id": "sample_2",
+                "title": f"{query} Engineer",
+                "company": "InnovateLabs",
+                "location": location or "New York, NY",
+                "description": f"Join our team as a {query} engineer and help build the next generation of applications. Great opportunity for growth and learning.",
+                "requirements": f"3+ years {query} experience, bachelor's degree preferred, excellent communication skills",
+                "salary": "$70,000 - $95,000",
+                "url": "https://example.com/job2",
+                "posted_date": (datetime.now() - timedelta(days=1)).isoformat(),
+                "job_type": job_type or "full-time",
+                "source": "sample",
+            },
+            {
+                "id": "sample_3",
+                "title": f"Junior {query} Specialist",
+                "company": "StartupXYZ",
+                "location": location or "San Francisco, CA",
+                "description": f"Great entry-level opportunity for {query} enthusiasts. We offer mentorship, training, and a collaborative environment.",
+                "requirements": f"1-2 years {query} experience, willingness to learn, passion for technology",
+                "salary": "$55,000 - $75,000",
+                "url": "https://example.com/job3",
+                "posted_date": (datetime.now() - timedelta(days=2)).isoformat(),
+                "job_type": job_type or "full-time",
+                "source": "sample",
+            },
+        ]
+
+        return sample_jobs
+
+    def search_jobs(
+        self, user_id: str, query: str = "", location: str = "", job_type: str = ""
+    ) -> Dict[str, Any]:
+        """
+        Search for jobs and rank them by relevance to user profile.
+
+        Args:
+            user_id: User identifier for personalization
+            query: Job search query/keywords
+            location: Preferred job location
+            job_type: Type of job (full-time, contract, remote, etc.)
+
+        Returns:
+            Dict with ranked job listings and fit scores
+        """
+        try:
+            # Get user profile
+            profile = self.profile_service.get_profile(user_id)
+            if not profile:
+                return {
+                    "success": False,
+                    "message": "User profile not found. Please create a profile first.",
+                }
+
+            # Create cache key
+            cache_key = f"{query}_{location}_{job_type}"
+            current_time = datetime.now()
+
+            # Check cache (expire after 1 hour)
+            if cache_key in self.jobs_cache:
+                cached_data = self.jobs_cache[cache_key]
+                cache_time = datetime.fromisoformat(cached_data["timestamp"])
+                if current_time - cache_time < timedelta(hours=1):
+                    fresh_jobs = cached_data["jobs"]
+                else:
+                    fresh_jobs = self._fetch_fresh_jobs(query, location, job_type)
+                    self.jobs_cache[cache_key] = {
+                        "jobs": fresh_jobs,
+                        "timestamp": current_time.isoformat(),
+                    }
+                    self._save_cache()
+            else:
+                fresh_jobs = self._fetch_fresh_jobs(query, location, job_type)
+                self.jobs_cache[cache_key] = {
+                    "jobs": fresh_jobs,
+                    "timestamp": current_time.isoformat(),
+                }
+                self._save_cache()
+
+            if not fresh_jobs:
+                return {
+                    "success": True,
+                    "jobs": [],
+                    "total_found": 0,
+                    "message": "No jobs found for the given criteria",
+                    "search_params": {
+                        "query": query,
+                        "location": location,
+                        "job_type": job_type,
+                    },
+                }
+
+            # Add jobs to embedding index
+            self.embedding_service.add_job_embeddings(fresh_jobs)
+
+            # Create profile text for matching
+            profile_text = (
+                f"{' '.join(profile.skills)} {profile.career_goals} {profile.resume}"
+            )
+
+            # Search for similar jobs
+            similar_jobs = self.embedding_service.search_similar_jobs(
+                profile_text, k=min(len(fresh_jobs), self.settings.max_jobs_per_search)
+            )
+
+            # Format results with fit scores
+            ranked_jobs = []
+            for job_meta, similarity_score in similar_jobs:
+                # Find the full job data
+                full_job = next(
+                    (job for job in fresh_jobs if job["id"] == job_meta["job_id"]), None
+                )
+                if full_job:
+                    # Calculate fit percentage (similarity score is cosine similarity)
+                    fit_percentage = max(0, min(100, int(similarity_score * 100)))
+
+                    ranked_job = {
+                        **full_job,
+                        "fit_score": fit_percentage,
+                        "match_reasons": self._get_match_reasons(
+                            profile, full_job, similarity_score
+                        ),
+                    }
+                    ranked_jobs.append(ranked_job)
+
+            # Sort by fit score
+            ranked_jobs.sort(key=lambda x: x["fit_score"], reverse=True)
+
+            return {
+                "success": True,
+                "jobs": ranked_jobs,
+                "total_found": len(ranked_jobs),
+                "search_params": {
+                    "query": query,
+                    "location": location,
+                    "job_type": job_type,
+                },
+                "user_profile": {
+                    "skills_count": len(profile.skills),
+                    "location": profile.location,
+                },
+            }
+
+        except Exception as e:
+            return {"success": False, "message": f"Error searching jobs: {str(e)}"}
+
+    def _fetch_fresh_jobs(
+        self, query: str, location: str, job_type: str
+    ) -> List[Dict[str, Any]]:
+        """Fetch fresh jobs from multiple sources."""
+        all_jobs = []
+
+        # Try Indeed first (commented out for demo - requires careful rate limiting)
+        # indeed_jobs = self._fetch_indeed_jobs(query, location, job_type)
+        # all_jobs.extend(indeed_jobs)
+
+        # Use sample jobs for demo
+        sample_jobs = self._fetch_sample_jobs(query, location, job_type)
+        all_jobs.extend(sample_jobs)
+
+        # TODO: Add more job sources
+        # - LinkedIn API (requires partnership)
+        # - AngelList API
+        # - GitHub Jobs API
+        # - Company career pages scraping
+
+        return all_jobs
+
+    def _get_match_reasons(
+        self, profile: UserProfile, job: Dict[str, Any], similarity_score: float
+    ) -> List[str]:
+        """Generate reasons why this job matches the user profile."""
+        reasons = []
+
+        # Check skill matches
+        job_text = f"{job['title']} {job['description']} {job['requirements']}".lower()
+        matching_skills = [
+            skill for skill in profile.skills if skill.lower() in job_text
+        ]
+
+        if matching_skills:
+            reasons.append(f"Skills match: {', '.join(matching_skills[:3])}")
+
+        # Check location preference
+        if profile.location and profile.location.lower() in job["location"].lower():
+            reasons.append("Location preference match")
+
+        # Check job type preference
+        if similarity_score > 0.8:
+            reasons.append("High relevance to your background")
+        elif similarity_score > 0.6:
+            reasons.append("Good match for your experience")
+
+        # Check career goals alignment
+        if any(
+            goal_word in job_text
+            for goal_word in profile.career_goals.lower().split()[:5]
+        ):
+            reasons.append("Aligns with career goals")
+
+        return reasons[:3]  # Limit to top 3 reasons

src/services/llm_service.py

@@ -0,0 +1,256 @@
+"""LLM service for generating cover letters and Q&A responses."""
+
+from typing import Dict, Any, Optional
+import openai
+from anthropic import Anthropic
+
+from ..config import get_settings
+from .profile_service import UserProfile
+
+
+class LLMService:
+    """Service for LLM-based text generation."""
+
+    def __init__(self):
+        self.settings = get_settings()
+        self.openai_client = None
+        self.anthropic_client = None
+        self._initialize_clients()
+
+    def _initialize_clients(self):
+        """Initialize LLM clients based on available API keys."""
+        if self.settings.openai_api_key:
+            openai.api_key = self.settings.openai_api_key
+            self.openai_client = openai
+
+        if self.settings.anthropic_api_key:
+            self.anthropic_client = Anthropic(api_key=self.settings.anthropic_api_key)
+
+    def _get_client(self):
+        """Get the appropriate LLM client based on provider setting."""
+        if self.settings.llm_provider == "openai" and self.openai_client:
+            return self.openai_client, "openai"
+        elif self.settings.llm_provider == "anthropic" and self.anthropic_client:
+            return self.anthropic_client, "anthropic"
+        elif self.openai_client:
+            return self.openai_client, "openai"
+        elif self.anthropic_client:
+            return self.anthropic_client, "anthropic"
+        else:
+            return None, None
+
+    def _call_openai(self, messages: list, max_tokens: int = None) -> Optional[str]:
+        """Call OpenAI API."""
+        try:
+            response = self.openai_client.ChatCompletion.create(
+                model=self.settings.llm_model,
+                messages=messages,
+                max_tokens=max_tokens or self.settings.max_tokens,
+                temperature=self.settings.temperature,
+            )
+            return response.choices[0].message.content.strip()
+        except Exception as e:
+            print(f"OpenAI API error: {e}")
+            return None
+
+    def _call_anthropic(self, messages: list, max_tokens: int = None) -> Optional[str]:
+        """Call Anthropic API."""
+        try:
+            # Convert messages format for Anthropic
+            system_message = ""
+            user_messages = []
+
+            for msg in messages:
+                if msg["role"] == "system":
+                    system_message = msg["content"]
+                else:
+                    user_messages.append(msg)
+
+            # Combine user messages
+            combined_content = "\n\n".join([msg["content"] for msg in user_messages])
+
+            response = self.anthropic_client.messages.create(
+                model="claude-3-haiku-20240307",  # Using a lighter model for cost efficiency
+                system=system_message,
+                messages=[{"role": "user", "content": combined_content}],
+                max_tokens=max_tokens or self.settings.max_tokens,
+                temperature=self.settings.temperature,
+            )
+            return response.content[0].text.strip()
+        except Exception as e:
+            print(f"Anthropic API error: {e}")
+            return None
+
+    def generate_text(self, messages: list, max_tokens: int = None) -> Optional[str]:
+        """Generate text using the configured LLM."""
+        client, provider = self._get_client()
+        if not client:
+            return None
+
+        if provider == "openai":
+            return self._call_openai(messages, max_tokens)
+        elif provider == "anthropic":
+            return self._call_anthropic(messages, max_tokens)
+
+        return None
+
+    def generate_cover_letter(
+        self, profile: UserProfile, job_description: str, tone: str = "professional"
+    ) -> Dict[str, Any]:
+        """
+        Generate a personalized cover letter.
+
+        Args:
+            profile: User profile containing skills, experience, etc.
+            job_description: The job posting description
+            tone: Desired tone (professional, casual, enthusiastic, formal)
+
+        Returns:
+            Dict with generated cover letter and metadata
+        """
+        try:
+            # Prepare context
+            skills_text = ", ".join(profile.skills[:10])  # Limit skills for brevity
+
+            # Create prompt messages
+            system_prompt = f"""You are an expert cover letter writer. Generate a compelling, personalized cover letter that:
+1. Is concise (under 300 words)
+2. Matches the {tone} tone
+3. Highlights relevant skills and experience
+4. Shows enthusiasm for the specific role
+5. Includes a strong opening and closing
+6. Avoids generic templates
+
+Format as a professional cover letter without date/address headers."""
+
+            user_prompt = f"""Generate a cover letter for this job:
+
+JOB DESCRIPTION:
+{job_description[:2000]}  # Limit to avoid token limits
+
+CANDIDATE PROFILE:
+- Skills: {skills_text}
+- Experience: {profile.experience_level or 'Not specified'}
+- Career Goals: {profile.career_goals}
+- Location: {profile.location or 'Not specified'}
+- Education: {profile.education or 'Not specified'}
+
+RESUME SUMMARY:
+{profile.resume[:1000]}  # Limit resume text
+
+Tone: {tone}
+
+Write a cover letter that specifically connects the candidate's background to this job opportunity."""
+
+            messages = [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ]
+
+            # Generate cover letter
+            cover_letter = self.generate_text(messages, max_tokens=400)
+
+            if cover_letter:
+                return {
+                    "success": True,
+                    "cover_letter": cover_letter,
+                    "tone_used": tone,
+                    "word_count": len(cover_letter.split()),
+                    "character_count": len(cover_letter),
+                }
+            else:
+                return {"success": False, "message": "Failed to generate cover letter"}
+
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"Error generating cover letter: {str(e)}",
+            }
+
+    def generate_qa_response(
+        self, profile: UserProfile, question: str, context: str = ""
+    ) -> Dict[str, Any]:
+        """
+        Generate a response to an interview question or client inquiry.
+
+        Args:
+            profile: User profile for personalization
+            question: The question to answer
+            context: Additional context about the conversation
+
+        Returns:
+            Dict with generated response and confidence score
+        """
+        try:
+            # Create prompt
+            system_prompt = """You are a professional career advisor helping someone answer interview questions and client inquiries. 
+
+Generate responses that are:
+1. Concise (under 150 words)
+2. Professional and confident
+3. Specific to the person's background
+4. Include relevant examples when possible
+5. End with enthusiasm or next steps
+
+Avoid generic answers and be authentic."""
+
+            user_prompt = f"""Answer this question professionally:
+
+QUESTION: {question}
+
+CONTEXT: {context}
+
+CANDIDATE BACKGROUND:
+- Skills: {", ".join(profile.skills[:8])}
+- Experience Level: {profile.experience_level or 'Not specified'}
+- Career Goals: {profile.career_goals}
+- Key Background: {profile.resume[:800]}
+
+Provide a specific, personalized answer that showcases relevant experience and skills."""
+
+            messages = [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ]
+
+            # Generate response
+            response = self.generate_text(messages, max_tokens=200)
+
+            if response:
+                # Simple confidence scoring based on response characteristics
+                word_count = len(response.split())
+                has_examples = any(
+                    keyword in response.lower()
+                    for keyword in [
+                        "experience",
+                        "project",
+                        "worked",
+                        "developed",
+                        "managed",
+                    ]
+                )
+                has_specific_skills = any(
+                    skill.lower() in response.lower() for skill in profile.skills[:5]
+                )
+
+                confidence_score = 0.6  # Base score
+                if has_examples:
+                    confidence_score += 0.2
+                if has_specific_skills:
+                    confidence_score += 0.15
+                if 50 <= word_count <= 150:
+                    confidence_score += 0.05
+
+                confidence_score = min(confidence_score, 1.0)
+
+                return {
+                    "success": True,
+                    "response": response,
+                    "confidence_score": round(confidence_score, 2),
+                    "word_count": word_count,
+                }
+            else:
+                return {"success": False, "message": "Failed to generate response"}
+
+        except Exception as e:
+            return {"success": False, "message": f"Error generating response: {str(e)}"}

src/services/profile_service.py

@@ -0,0 +1,135 @@
+"""Profile service for managing user profiles and data."""
+
+import json
+import os
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+from ..config import get_settings
+
+
+class UserProfile(BaseModel):
+    """User profile data model."""
+
+    user_id: str
+    resume: str
+    skills: list[str]
+    salary_wish: str
+    career_goals: str
+    experience_level: Optional[str] = None
+    location: Optional[str] = None
+    education: Optional[str] = None
+    certifications: Optional[list[str]] = None
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+
+class ProfileService:
+    """Service for managing user profiles."""
+
+    def __init__(self):
+        self.settings = get_settings()
+        self.profiles_path = self.settings.profiles_db_path
+        self._ensure_data_dir()
+
+    def _ensure_data_dir(self):
+        """Ensure data directory exists."""
+        os.makedirs(os.path.dirname(self.profiles_path), exist_ok=True)
+
+    def _load_profiles(self) -> Dict[str, Dict[str, Any]]:
+        """Load profiles from file."""
+        if not os.path.exists(self.profiles_path):
+            return {}
+
+        try:
+            with open(self.profiles_path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, FileNotFoundError):
+            return {}
+
+    def _save_profiles(self, profiles: Dict[str, Dict[str, Any]]):
+        """Save profiles to file."""
+        with open(self.profiles_path, "w", encoding="utf-8") as f:
+            json.dump(profiles, f, indent=2, default=str)
+
+    def upsert_profile(self, user_id: str, profile_data: str) -> Dict[str, Any]:
+        """
+        Store or update user profile.
+
+        Args:
+            user_id: Unique user identifier
+            profile_data: JSON string containing profile information
+
+        Returns:
+            Dict with operation result
+        """
+        try:
+            # Parse profile data
+            profile_dict = json.loads(profile_data)
+
+            # Validate required fields
+            required_fields = ["resume", "skills", "salary_wish", "career_goals"]
+            missing_fields = [
+                field for field in required_fields if field not in profile_dict
+            ]
+
+            if missing_fields:
+                return {
+                    "success": False,
+                    "message": f"Missing required fields: {', '.join(missing_fields)}",
+                }
+
+            # Create profile model
+            profile_dict["user_id"] = user_id
+            profile = UserProfile(**profile_dict)
+
+            # Load existing profiles
+            profiles = self._load_profiles()
+
+            # Update timestamp if profile exists
+            if user_id in profiles:
+                profile.updated_at = datetime.now()
+
+            # Store profile
+            profiles[user_id] = profile.dict()
+            self._save_profiles(profiles)
+
+            return {
+                "success": True,
+                "message": "Profile updated successfully",
+                "user_id": user_id,
+                "profile": {
+                    "skills_count": len(profile.skills),
+                    "updated_at": profile.updated_at.isoformat(),
+                },
+            }
+
+        except json.JSONDecodeError:
+            return {"success": False, "message": "Invalid JSON format in profile data"}
+        except Exception as e:
+            return {"success": False, "message": f"Error updating profile: {str(e)}"}
+
+    def get_profile(self, user_id: str) -> Optional[UserProfile]:
+        """Get user profile by ID."""
+        profiles = self._load_profiles()
+        profile_data = profiles.get(user_id)
+
+        if profile_data:
+            return UserProfile(**profile_data)
+        return None
+
+    def delete_profile(self, user_id: str) -> bool:
+        """Delete user profile."""
+        profiles = self._load_profiles()
+        if user_id in profiles:
+            del profiles[user_id]
+            self._save_profiles(profiles)
+            return True
+        return False
+
+    def list_profiles(self) -> list[str]:
+        """List all user IDs."""
+        profiles = self._load_profiles()
+        return list(profiles.keys())

src/tools/__init__.py

@@ -0,0 +1,8 @@
+"""Tools module for Job Search MCP Server."""
+
+from .profile_tool import ProfileTool
+from .job_search_tool import JobSearchTool
+from .cover_letter_tool import CoverLetterTool
+from .qa_tool import QATool
+
+__all__ = ["ProfileTool", "JobSearchTool", "CoverLetterTool", "QATool"]

src/tools/cover_letter_tool.py

@@ -0,0 +1,249 @@
+"""Cover letter tool for generating personalized cover letters - letter.generate endpoint."""
+
+from typing import Dict, Any
+
+from ..services import LLMService, ProfileService
+
+
+class CoverLetterTool:
+    """Tool for generating personalized cover letters."""
+
+    def __init__(self):
+        self.llm_service = LLMService()
+        self.profile_service = ProfileService()
+
+    def generate(
+        self, user_id: str, job_description: str, tone: str = "professional"
+    ) -> Dict[str, Any]:
+        """
+        Generate a personalized cover letter using LLM.
+
+        This is the main letter.generate endpoint that calls an LLM to create
+        a short, personalized cover letter in any tone.
+
+        Args:
+            user_id: User identifier to access profile for personalization
+            job_description: The job posting description to tailor the letter to
+            tone: Tone of the cover letter
+                  Options: "professional", "casual", "enthusiastic", "formal"
+                  Default: "professional"
+
+        Returns:
+            Dict with generated cover letter and metadata:
+            {
+                "success": True,
+                "cover_letter": "Dear Hiring Manager,\n\nI am writing to express...",
+                "tone_used": "professional",
+                "word_count": 245,
+                "character_count": 1456,
+                "estimated_reading_time": "1 minute"
+            }
+        """
+        try:
+            # Get user profile
+            profile = self.profile_service.get_profile(user_id)
+            if not profile:
+                return {
+                    "success": False,
+                    "message": "User profile not found. Please create a profile first.",
+                }
+
+            # Validate tone
+            valid_tones = ["professional", "casual", "enthusiastic", "formal"]
+            if tone not in valid_tones:
+                return {
+                    "success": False,
+                    "message": f"Invalid tone. Must be one of: {', '.join(valid_tones)}",
+                }
+
+            # Validate job description
+            if not job_description or len(job_description.strip()) < 50:
+                return {
+                    "success": False,
+                    "message": "Job description must be at least 50 characters long",
+                }
+
+            # Generate cover letter
+            result = self.llm_service.generate_cover_letter(
+                profile, job_description, tone
+            )
+
+            # Add additional metadata if successful
+            if result.get("success") and result.get("cover_letter"):
+                word_count = result.get("word_count", 0)
+                result["estimated_reading_time"] = self._estimate_reading_time(
+                    word_count
+                )
+                result["tips"] = self._get_cover_letter_tips(tone)
+
+            return result
+
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"Error generating cover letter: {str(e)}",
+            }
+
+    def generate_multiple_tones(
+        self, user_id: str, job_description: str, tones: list[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Generate cover letters in multiple tones for comparison.
+
+        Args:
+            user_id: User identifier
+            job_description: Job posting description
+            tones: List of tones to generate (default: ["professional", "enthusiastic"])
+
+        Returns:
+            Dict with multiple cover letters in different tones
+        """
+        if tones is None:
+            tones = ["professional", "enthusiastic"]
+
+        results = {}
+        errors = []
+
+        for tone in tones:
+            result = self.generate(user_id, job_description, tone)
+            if result.get("success"):
+                results[tone] = result
+            else:
+                errors.append(f"{tone}: {result.get('message', 'Unknown error')}")
+
+        if results:
+            return {
+                "success": True,
+                "cover_letters": results,
+                "tones_generated": list(results.keys()),
+                "errors": errors if errors else None,
+            }
+        else:
+            return {
+                "success": False,
+                "message": "Failed to generate any cover letters",
+                "errors": errors,
+            }
+
+    def customize_for_company(
+        self,
+        user_id: str,
+        job_description: str,
+        company_info: str,
+        tone: str = "professional",
+    ) -> Dict[str, Any]:
+        """
+        Generate a cover letter with additional company-specific customization.
+
+        Args:
+            user_id: User identifier
+            job_description: Job posting description
+            company_info: Additional information about the company
+            tone: Tone for the cover letter
+
+        Returns:
+            Dict with customized cover letter
+        """
+        try:
+            # Enhance job description with company info
+            enhanced_description = (
+                f"{job_description}\n\nCompany Information:\n{company_info}"
+            )
+
+            # Generate the cover letter
+            result = self.generate(user_id, enhanced_description, tone)
+
+            if result.get("success"):
+                result["customization"] = "Company-specific information included"
+
+            return result
+
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"Error generating customized cover letter: {str(e)}",
+            }
+
+    def _estimate_reading_time(self, word_count: int) -> str:
+        """Estimate reading time based on word count (average 200 words per minute)."""
+        if word_count == 0:
+            return "0 minutes"
+
+        minutes = max(1, round(word_count / 200))
+        if minutes == 1:
+            return "1 minute"
+        else:
+            return f"{minutes} minutes"
+
+    def _get_cover_letter_tips(self, tone: str) -> list[str]:
+        """Get tone-specific tips for cover letters."""
+        tips_by_tone = {
+            "professional": [
+                "Keep it concise and focused on achievements",
+                "Use formal language and proper business format",
+                "Highlight quantifiable results when possible",
+            ],
+            "casual": [
+                "Show personality while remaining respectful",
+                "Use conversational language but avoid slang",
+                "Focus on cultural fit and team collaboration",
+            ],
+            "enthusiastic": [
+                "Express genuine excitement for the role",
+                "Use energetic language and positive adjectives",
+                "Show passion for the company's mission",
+            ],
+            "formal": [
+                "Follow strict business letter format",
+                "Use traditional and respectful language",
+                "Emphasize credentials and qualifications",
+            ],
+        }
+
+        return tips_by_tone.get(
+            tone, ["Tailor the letter to the specific job and company"]
+        )
+
+    def get_cover_letter_template(self, tone: str = "professional") -> Dict[str, Any]:
+        """
+        Get a basic cover letter template for the specified tone.
+
+        Args:
+            tone: Desired tone for the template
+
+        Returns:
+            Dict with template structure and guidelines
+        """
+        templates = {
+            "professional": {
+                "structure": [
+                    "Header with your contact information",
+                    "Date and employer contact information",
+                    "Professional greeting",
+                    "Opening paragraph: Position and brief introduction",
+                    "Body paragraph 1: Relevant experience and skills",
+                    "Body paragraph 2: Achievements and value proposition",
+                    "Closing paragraph: Next steps and gratitude",
+                    "Professional closing",
+                ],
+                "sample_opening": "I am writing to express my strong interest in the [Position Title] role at [Company Name].",
+                "sample_closing": "I would welcome the opportunity to discuss how my experience can contribute to your team's success.",
+            },
+            "enthusiastic": {
+                "structure": [
+                    "Energetic opening that shows excitement",
+                    "Passionate description of relevant experience",
+                    "Connection to company mission and values",
+                    "Enthusiastic closing with call to action",
+                ],
+                "sample_opening": "I am thrilled to apply for the [Position Title] position at [Company Name]!",
+                "sample_closing": "I can't wait to bring my passion and skills to your amazing team!",
+            },
+        }
+
+        return {
+            "success": True,
+            "tone": tone,
+            "template": templates.get(tone, templates["professional"]),
+            "tips": self._get_cover_letter_tips(tone),
+        }

src/tools/job_search_tool.py

@@ -0,0 +1,157 @@
+"""Job search tool for finding and ranking relevant jobs - jobs.search endpoint."""
+
+from typing import Dict, Any
+
+from ..services import JobSearchService
+
+
+class JobSearchTool:
+    """Tool for searching and ranking job opportunities."""
+
+    def __init__(self):
+        self.job_search_service = JobSearchService()
+
+    def search(
+        self, user_id: str, query: str = "", location: str = "", job_type: str = ""
+    ) -> Dict[str, Any]:
+        """
+        Search for jobs and rank them by relevance to user profile.
+
+        This is the main jobs.search endpoint that pulls fresh job posts,
+        ranks them with GPU embeddings, and returns fit scores.
+
+        Args:
+            user_id: User identifier to get personalized results based on profile
+            query: Job search query/keywords (e.g., "Python developer", "Data scientist")
+            location: Preferred job location (e.g., "Remote", "New York", "San Francisco")
+            job_type: Type of job (e.g., "full-time", "part-time", "contract", "remote", "freelance")
+
+        Returns:
+            Dict with ranked job listings and fit scores:
+            {
+                "success": True,
+                "jobs": [
+                    {
+                        "id": "job_123",
+                        "title": "Senior Python Developer",
+                        "company": "TechCorp",
+                        "location": "Remote",
+                        "description": "Job description...",
+                        "requirements": "Skills required...",
+                        "salary": "$80,000 - $120,000",
+                        "url": "https://company.com/jobs/123",
+                        "posted_date": "2024-01-15T10:30:00",
+                        "job_type": "full-time",
+                        "fit_score": 85,  # Percentage match (0-100)
+                        "match_reasons": ["Skills match: Python, Django", "Location preference match"]
+                    }
+                ],
+                "total_found": 10,
+                "search_params": {
+                    "query": "Python developer",
+                    "location": "Remote",
+                    "job_type": "full-time"
+                },
+                "user_profile": {
+                    "skills_count": 15,
+                    "location": "Remote"
+                }
+            }
+        """
+        return self.job_search_service.search_jobs(user_id, query, location, job_type)
+
+    def get_job_details(self, job_id: str) -> Dict[str, Any]:
+        """
+        Get detailed information about a specific job.
+
+        Args:
+            job_id: Unique job identifier
+
+        Returns:
+            Dict with detailed job information or error message
+        """
+        # This would typically fetch from job cache or re-scrape
+        # For now, return a placeholder implementation
+        return {
+            "success": False,
+            "message": "Job details retrieval not implemented yet",
+        }
+
+    def get_search_suggestions(self, user_id: str) -> Dict[str, Any]:
+        """
+        Get personalized job search suggestions based on user profile.
+
+        Args:
+            user_id: User identifier
+
+        Returns:
+            Dict with suggested search queries and parameters
+        """
+        try:
+            from ..services import ProfileService
+
+            profile_service = ProfileService()
+            profile = profile_service.get_profile(user_id)
+
+            if not profile:
+                return {"success": False, "message": "User profile not found"}
+
+            # Generate suggestions based on skills and career goals
+            suggestions = []
+
+            # Skill-based suggestions
+            top_skills = profile.skills[:5]  # Top 5 skills
+            for skill in top_skills:
+                suggestions.append(
+                    {
+                        "query": f"{skill} developer",
+                        "reason": f"Based on your {skill} skills",
+                    }
+                )
+
+            # Career goal-based suggestions
+            if "senior" in profile.career_goals.lower():
+                suggestions.append(
+                    {
+                        "query": "senior developer",
+                        "reason": "Based on your career goals",
+                    }
+                )
+
+            if "remote" in profile.career_goals.lower():
+                suggestions.append(
+                    {
+                        "location": "Remote",
+                        "reason": "Based on your location preferences",
+                    }
+                )
+
+            return {
+                "success": True,
+                "suggestions": suggestions[:10],  # Limit to 10 suggestions
+                "profile_skills": profile.skills[:10],
+            }
+
+        except Exception as e:
+            return {"success": False, "message": f"Error getting suggestions: {str(e)}"}
+
+    def clear_job_cache(self) -> Dict[str, Any]:
+        """
+        Clear the job search cache to force fresh results.
+
+        Returns:
+            Dict with operation result
+        """
+        try:
+            self.job_search_service.jobs_cache = {}
+            self.job_search_service._save_cache()
+
+            # Also clear embedding index
+            self.job_search_service.embedding_service.clear_index()
+
+            return {
+                "success": True,
+                "message": "Job cache and embeddings cleared successfully",
+            }
+        except Exception as e:
+            return {"success": False, "message": f"Error clearing cache: {str(e)}"}

src/tools/profile_tool.py

@@ -0,0 +1,90 @@
+"""Profile tool for managing user profiles - profile.upsert endpoint."""
+
+from typing import Dict, Any
+
+from ..services import ProfileService
+
+
+class ProfileTool:
+    """Tool for managing user profiles."""
+
+    def __init__(self):
+        self.profile_service = ProfileService()
+
+    def upsert(self, user_id: str, profile_data: str) -> Dict[str, Any]:
+        """
+        Store or update user profile.
+
+        This is the main profile.upsert endpoint that stores the user résumé,
+        skills, salary expectations, and career goals.
+
+        Args:
+            user_id: Unique identifier for the user
+            profile_data: JSON string containing user profile information
+                Expected format:
+                {
+                    "resume": "Full resume text...",
+                    "skills": ["Python", "JavaScript", "React", ...],
+                    "salary_wish": "$80,000 - $120,000 annually",
+                    "career_goals": "Looking to transition into senior developer role...",
+                    "experience_level": "Mid-level",  # Optional
+                    "location": "Remote",             # Optional
+                    "education": "BS Computer Science", # Optional
+                    "certifications": ["AWS Certified"] # Optional
+                }
+
+        Returns:
+            Dict with success status, message, and profile metadata
+        """
+        return self.profile_service.upsert_profile(user_id, profile_data)
+
+    def get(self, user_id: str) -> Dict[str, Any]:
+        """
+        Get user profile by ID.
+
+        Args:
+            user_id: Unique user identifier
+
+        Returns:
+            Dict with profile data or error message
+        """
+        try:
+            profile = self.profile_service.get_profile(user_id)
+            if profile:
+                return {"success": True, "profile": profile.dict()}
+            else:
+                return {"success": False, "message": "Profile not found"}
+        except Exception as e:
+            return {"success": False, "message": f"Error retrieving profile: {str(e)}"}
+
+    def delete(self, user_id: str) -> Dict[str, Any]:
+        """
+        Delete user profile.
+
+        Args:
+            user_id: Unique user identifier
+
+        Returns:
+            Dict with operation result
+        """
+        try:
+            deleted = self.profile_service.delete_profile(user_id)
+            if deleted:
+                return {"success": True, "message": "Profile deleted successfully"}
+            else:
+                return {"success": False, "message": "Profile not found"}
+        except Exception as e:
+            return {"success": False, "message": f"Error deleting profile: {str(e)}"}
+
+    def list_all(self) -> Dict[str, Any]:
+        """
+        List all user IDs with profiles.
+
+        Returns:
+            Dict with list of user IDs
+        """
+        try:
+            user_ids = self.profile_service.list_profiles()
+            return {"success": True, "user_ids": user_ids, "count": len(user_ids)}
+        except Exception as e:
+            return {"success": False, "message": f"Error listing profiles: {str(e)}"}

src/tools/qa_tool.py

@@ -0,0 +1,354 @@
+"""Q&A tool for drafting responses to interview questions - qa.reply endpoint."""
+
+from typing import Dict, Any, List
+
+from ..services import LLMService, ProfileService
+
+
+class QATool:
+    """Tool for generating responses to interview questions and client inquiries."""
+
+    def __init__(self):
+        self.llm_service = LLMService()
+        self.profile_service = ProfileService()
+
+    def reply(self, user_id: str, question: str, context: str = "") -> Dict[str, Any]:
+        """
+        Generate a response to an interview question or client inquiry.
+
+        This is the main qa.reply endpoint that drafts concise answers to
+        client questions like "Why should we hire you?" to speed up
+        Upwork, Fiverr, or LinkedIn chats.
+
+        Args:
+            user_id: User identifier to access profile for personalization
+            question: The question from potential employer/client to answer
+            context: Additional context about the conversation or role (optional)
+
+        Returns:
+            Dict with generated response and metadata:
+            {
+                "success": True,
+                "response": "I bring 5+ years of Python development experience...",
+                "confidence_score": 0.85,  # 0.0 to 1.0 confidence in the response
+                "word_count": 78,
+                "estimated_delivery_time": "2-3 days",  # For project-based questions
+                "follow_up_suggestions": ["What's the project timeline?", "What's the budget range?"]
+            }
+        """
+        try:
+            # Get user profile
+            profile = self.profile_service.get_profile(user_id)
+            if not profile:
+                return {
+                    "success": False,
+                    "message": "User profile not found. Please create a profile first.",
+                }
+
+            # Validate question
+            if not question or len(question.strip()) < 5:
+                return {
+                    "success": False,
+                    "message": "Question must be at least 5 characters long",
+                }
+
+            # Generate response
+            result = self.llm_service.generate_qa_response(profile, question, context)
+
+            # Add additional features if successful
+            if result.get("success") and result.get("response"):
+                # Add follow-up suggestions
+                result["follow_up_suggestions"] = self._get_follow_up_suggestions(
+                    question, context
+                )
+
+                # Add estimated delivery time for project-related questions
+                if self._is_project_question(question):
+                    result["estimated_delivery_time"] = self._estimate_delivery_time(
+                        question, profile
+                    )
+
+                # Add question category
+                result["question_category"] = self._categorize_question(question)
+
+            return result
+
+        except Exception as e:
+            return {"success": False, "message": f"Error generating response: {str(e)}"}
+
+    def batch_reply(
+        self, user_id: str, questions: List[Dict[str, str]]
+    ) -> Dict[str, Any]:
+        """
+        Generate responses to multiple questions at once.
+
+        Args:
+            user_id: User identifier
+            questions: List of question dictionaries with 'question' and optional 'context'
+                      Example: [{"question": "Why should we hire you?", "context": "Senior role"}]
+
+        Returns:
+            Dict with multiple responses
+        """
+        try:
+            if not questions:
+                return {
+                    "success": False,
+                    "message": "At least one question is required",
+                }
+
+            responses = []
+            errors = []
+
+            for i, q_data in enumerate(questions):
+                question = q_data.get("question", "")
+                context = q_data.get("context", "")
+
+                result = self.reply(user_id, question, context)
+
+                if result.get("success"):
+                    responses.append({"index": i, "question": question, **result})
+                else:
+                    errors.append(
+                        {
+                            "index": i,
+                            "question": question,
+                            "error": result.get("message", "Unknown error"),
+                        }
+                    )
+
+            return {
+                "success": True,
+                "responses": responses,
+                "total_processed": len(responses),
+                "errors": errors if errors else None,
+            }
+
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"Error processing batch questions: {str(e)}",
+            }
+
+    def get_common_questions(self, job_type: str = "general") -> Dict[str, Any]:
+        """
+        Get a list of common interview questions with suggested approaches.
+
+        Args:
+            job_type: Type of job (e.g., "developer", "designer", "manager", "general")
+
+        Returns:
+            Dict with common questions and tips
+        """
+        common_questions = {
+            "general": [
+                "Tell me about yourself",
+                "Why are you interested in this role?",
+                "What are your greatest strengths?",
+                "What is your biggest weakness?",
+                "Where do you see yourself in 5 years?",
+                "Why should we hire you?",
+                "What motivates you?",
+                "How do you handle stress and pressure?",
+                "What's your ideal work environment?",
+                "Do you have any questions for us?",
+            ],
+            "developer": [
+                "Describe your development process",
+                "How do you stay updated with new technologies?",
+                "Tell me about a challenging bug you fixed",
+                "How do you ensure code quality?",
+                "What's your experience with version control?",
+                "How do you approach debugging?",
+                "What's your preferred development environment?",
+                "How do you handle tight deadlines?",
+                "Tell me about a project you're proud of",
+                "How do you learn new programming languages?",
+            ],
+            "freelance": [
+                "What's your hourly rate?",
+                "How long will this project take?",
+                "Can you show me examples of similar work?",
+                "What's your communication style?",
+                "How do you handle revisions?",
+                "What's included in your price?",
+                "Can you work in our timezone?",
+                "How do you ensure project quality?",
+                "What happens if you miss a deadline?",
+                "Can you sign an NDA?",
+            ],
+        }
+
+        questions = common_questions.get(job_type, common_questions["general"])
+
+        return {
+            "success": True,
+            "job_type": job_type,
+            "questions": questions,
+            "tips": self._get_interview_tips(job_type),
+        }
+
+    def practice_session(
+        self, user_id: str, job_type: str = "general", num_questions: int = 5
+    ) -> Dict[str, Any]:
+        """
+        Generate a practice interview session with questions and sample answers.
+
+        Args:
+            user_id: User identifier
+            job_type: Type of job for targeted questions
+            num_questions: Number of questions to include (default: 5)
+
+        Returns:
+            Dict with practice questions and personalized sample answers
+        """
+        try:
+            # Get common questions
+            questions_data = self.get_common_questions(job_type)
+            all_questions = questions_data["questions"]
+
+            # Select subset of questions
+            import random
+
+            selected_questions = random.sample(
+                all_questions, min(num_questions, len(all_questions))
+            )
+
+            # Generate responses for each question
+            practice_qa = []
+            for question in selected_questions:
+                response_result = self.reply(
+                    user_id, question, f"Practice for {job_type} role"
+                )
+
+                if response_result.get("success"):
+                    practice_qa.append(
+                        {
+                            "question": question,
+                            "sample_answer": response_result["response"],
+                            "tips": response_result.get("follow_up_suggestions", []),
+                        }
+                    )
+
+            return {
+                "success": True,
+                "job_type": job_type,
+                "practice_questions": practice_qa,
+                "total_questions": len(practice_qa),
+                "general_tips": self._get_interview_tips(job_type),
+            }
+
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"Error creating practice session: {str(e)}",
+            }
+
+    def _get_follow_up_suggestions(self, question: str, context: str) -> List[str]:
+        """Generate follow-up questions or conversation starters."""
+        suggestions = []
+
+        question_lower = question.lower()
+
+        if "project" in question_lower or "work" in question_lower:
+            suggestions.extend(
+                [
+                    "What's the expected timeline for this project?",
+                    "What's the budget range?",
+                    "Who will I be working with?",
+                    "What are the main deliverables?",
+                ]
+            )
+
+        if "experience" in question_lower or "skills" in question_lower:
+            suggestions.extend(
+                [
+                    "Would you like to see examples of my work?",
+                    "I can provide references from previous clients",
+                    "What specific skills are most important for this role?",
+                ]
+            )
+
+        if "rate" in question_lower or "price" in question_lower:
+            suggestions.extend(
+                [
+                    "I'm flexible on pricing for long-term projects",
+                    "What's your budget for this project?",
+                    "I can provide a detailed project breakdown",
+                ]
+            )
+
+        return suggestions[:3]  # Limit to top 3 suggestions
+
+    def _is_project_question(self, question: str) -> bool:
+        """Determine if the question is about a specific project."""
+        project_keywords = [
+            "project",
+            "timeline",
+            "deadline",
+            "deliver",
+            "complete",
+            "build",
+            "develop",
+            "create",
+        ]
+        return any(keyword in question.lower() for keyword in project_keywords)
+
+    def _estimate_delivery_time(self, question: str, profile) -> str:
+        """Estimate project delivery time based on question and profile."""
+        # Simple estimation based on project complexity indicators
+        if any(word in question.lower() for word in ["simple", "basic", "small"]):
+            return "1-2 days"
+        elif any(word in question.lower() for word in ["complex", "large", "advanced"]):
+            return "1-2 weeks"
+        else:
+            return "3-5 days"
+
+    def _categorize_question(self, question: str) -> str:
+        """Categorize the type of question."""
+        question_lower = question.lower()
+
+        if any(
+            word in question_lower
+            for word in ["experience", "background", "skills", "qualification"]
+        ):
+            return "experience"
+        elif any(
+            word in question_lower
+            for word in ["project", "timeline", "deadline", "deliver"]
+        ):
+            return "project"
+        elif any(
+            word in question_lower
+            for word in ["rate", "price", "cost", "budget", "payment"]
+        ):
+            return "pricing"
+        elif any(word in question_lower for word in ["why", "motivation", "interest"]):
+            return "motivation"
+        else:
+            return "general"
+
+    def _get_interview_tips(self, job_type: str) -> List[str]:
+        """Get job-type specific interview tips."""
+        tips = {
+            "general": [
+                "Be specific with examples and achievements",
+                "Prepare questions to ask the interviewer",
+                "Research the company beforehand",
+                "Practice your elevator pitch",
+            ],
+            "developer": [
+                "Be ready to discuss your code and technical decisions",
+                "Prepare for coding challenges or technical questions",
+                "Show enthusiasm for learning new technologies",
+                "Discuss your development methodology",
+            ],
+            "freelance": [
+                "Have a portfolio ready to share",
+                "Be clear about your process and timeline",
+                "Discuss communication preferences upfront",
+                "Be professional but personable",
+            ],
+        }
+
+        return tips.get(job_type, tips["general"])