phone-a-friend-mcp-server 0.1.0__py3-none-any.whl

phone_a_friend_mcp_server/__init__.py

@@ -0,0 +1,53 @@
+import asyncio
+import logging
+import os
+import sys
+
+import click
+
+from phone_a_friend_mcp_server.config import PhoneAFriendConfig
+from phone_a_friend_mcp_server.server import serve
+
+
+@click.command()
+@click.option("-v", "--verbose", count=True, help="Increase verbosity")
+@click.option("--api-key", help="API key for external AI services")
+@click.option("--model", help="Model to use (e.g., 'gpt-4', 'anthropic/claude-3.5-sonnet')")
+@click.option("--provider", help="Provider type ('openai', 'openrouter', 'anthropic', 'google')")
+@click.option("--base-url", help="Base URL for API")
+def main(verbose: int, api_key: str = None, model: str = None, provider: str = None, base_url: str = None) -> None:
+    """MCP server for Phone-a-Friend AI consultation"""
+    logging_level = logging.WARN
+    if verbose == 1:
+        logging_level = logging.INFO
+    elif verbose >= 2:
+        logging_level = logging.DEBUG
+
+    logging.basicConfig(level=logging_level, stream=sys.stderr)
+
+    # Read environment variables with proper precedence
+    config_api_key = (
+        api_key
+        or os.environ.get("OPENROUTER_API_KEY")
+        or os.environ.get("OPENAI_API_KEY")
+        or os.environ.get("ANTHROPIC_API_KEY")
+        or os.environ.get("GOOGLE_API_KEY")
+        or os.environ.get("GEMINI_API_KEY")
+    )
+    config_model = model or os.environ.get("PHONE_A_FRIEND_MODEL")
+    config_provider = provider or os.environ.get("PHONE_A_FRIEND_PROVIDER")
+    config_base_url = base_url or os.environ.get("PHONE_A_FRIEND_BASE_URL")
+
+    # Initialize configuration
+    try:
+        config = PhoneAFriendConfig(api_key=config_api_key, model=config_model, provider=config_provider, base_url=config_base_url)
+    except ValueError as e:
+        click.echo(f"Configuration error: {e}", err=True)
+        sys.exit(1)
+
+    # Start the server
+    asyncio.run(serve(config))
+
+
+if __name__ == "__main__":
+    main()

phone_a_friend_mcp_server/__main__.py

@@ -0,0 +1,3 @@
+from phone_a_friend_mcp_server import main
+
+main()

phone_a_friend_mcp_server/client/__init__.py

@@ -0,0 +1 @@
+# Client package for Phone-a-Friend MCP server

phone_a_friend_mcp_server/config.py

@@ -0,0 +1,48 @@
+class PhoneAFriendConfig:
+    """Centralized configuration for Phone-a-Friend MCP server."""
+
+    def __init__(self, api_key: str | None = None, model: str | None = None, base_url: str | None = None, provider: str | None = None) -> None:
+        """Initialize configuration with provided values.
+
+        Args:
+            api_key: API key for external AI services
+            model: Model to use (e.g., 'gpt-4', 'anthropic/claude-3.5-sonnet')
+            base_url: Custom base URL for API (optional, providers use defaults)
+            provider: Provider type ('openai', 'openrouter', 'anthropic')
+        """
+        self.api_key = api_key
+        self.provider = provider or self._detect_provider()
+        self.model = model or self._get_default_model()
+        self.base_url = base_url  # Only use if explicitly provided
+
+        # Validate required configuration
+        if not self.api_key:
+            raise ValueError(f"Missing required API key for {self.provider}. Set {self._get_env_var_name()} environment variable or pass --api-key")
+
+    def _detect_provider(self) -> str:
+        """Detect provider based on available environment variables."""
+        import os
+
+        if os.environ.get("OPENROUTER_API_KEY"):
+            return "openrouter"
+        elif os.environ.get("ANTHROPIC_API_KEY"):
+            return "anthropic"
+        elif os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY"):
+            return "google"
+        elif os.environ.get("OPENAI_API_KEY"):
+            return "openai"
+        else:
+            # Default to OpenAI
+            return "openai"
+
+    def _get_default_model(self) -> str:
+        """Get default model based on provider."""
+        models = {"openai": "o3", "openrouter": "anthropic/claude-4-opus", "anthropic": "claude-4-opus", "google": "gemini-2.5-pro-preview-05-06"}
+        if self.provider not in models:
+            raise ValueError(f"Unknown provider: {self.provider}. Supported providers: {list(models.keys())}")
+        return models[self.provider]
+
+    def _get_env_var_name(self) -> str:
+        """Get environment variable name for the provider."""
+        env_vars = {"openai": "OPENAI_API_KEY", "openrouter": "OPENROUTER_API_KEY", "anthropic": "ANTHROPIC_API_KEY", "google": "GOOGLE_API_KEY or GEMINI_API_KEY"}
+        return env_vars.get(self.provider, "OPENAI_API_KEY")

phone_a_friend_mcp_server/server.py

@@ -0,0 +1,87 @@
+import logging
+from typing import Any
+
+import anyio
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Prompt, Resource, ResourceTemplate, TextContent, Tool
+
+from phone_a_friend_mcp_server.config import PhoneAFriendConfig
+from phone_a_friend_mcp_server.tools.tool_manager import ToolManager
+
+logger = logging.getLogger(__name__)
+
+
+async def serve(config: PhoneAFriendConfig) -> None:
+    """Start the Phone-a-Friend MCP server.
+
+    Args:
+        config: Configuration object with settings
+    """
+    server = Server("phone-a-friend-mcp-server")
+    tool_manager = ToolManager(config)
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        """List all available tools."""
+        try:
+            return tool_manager.list_tools()
+        except Exception as e:
+            logger.error("Failed to list tools: %s", e)
+            raise
+
+    @server.list_resources()
+    async def list_resources() -> list[Resource]:
+        """List available resources (returns empty list for now)."""
+        logger.info("Resources list requested - returning empty list")
+        return []
+
+    @server.list_resource_templates()
+    async def list_resource_templates() -> list[ResourceTemplate]:
+        """List available resource templates (returns empty list for now)."""
+        logger.info("Resource templates list requested - returning empty list")
+        return []
+
+    @server.list_prompts()
+    async def list_prompts() -> list[Prompt]:
+        """List available prompts (returns empty list for now)."""
+        logger.info("Prompts list requested - returning empty list")
+        return []
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+        """Execute a tool with the given arguments."""
+        try:
+            logger.info(f"Calling tool: {name} with arguments: {arguments}")
+            tool = tool_manager.get_tool(name)
+            result = await tool.run(**arguments)
+
+            if isinstance(result, dict):
+                formatted_result = ""
+                for key, value in result.items():
+                    if isinstance(value, list):
+                        formatted_result += f"{key.title()}:\n"
+                        for item in value:
+                            formatted_result += f"  • {item}\n"
+                    else:
+                        formatted_result += f"{key.title()}: {value}\n"
+                return [TextContent(type="text", text=formatted_result.strip())]
+            else:
+                return [TextContent(type="text", text=str(result))]
+
+        except Exception as e:
+            logger.error("Tool execution failed: %s", e)
+            error_msg = f"Error executing tool '{name}': {str(e)}"
+            return [TextContent(type="text", text=error_msg)]
+
+    # Start the server
+    options = server.create_initialization_options()
+    async with stdio_server() as (read_stream, write_stream):
+        try:
+            logger.info("Starting Phone-a-Friend MCP server...")
+            await server.run(read_stream, write_stream, options, raise_exceptions=True)
+        except anyio.BrokenResourceError:
+            logger.error("BrokenResourceError: Stream was closed unexpectedly. Exiting gracefully.")
+        except Exception as e:
+            logger.error(f"Unexpected error in server.run: {e}")
+            raise

phone_a_friend_mcp_server/tools/__init__.py

@@ -0,0 +1 @@
+# Tools package for Phone-a-Friend MCP server

phone_a_friend_mcp_server/tools/base_tools.py

@@ -0,0 +1,34 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from phone_a_friend_mcp_server.config import PhoneAFriendConfig
+
+
+class BaseTool(ABC):
+    """Base class for all Phone-a-Friend tools."""
+
+    def __init__(self, config: PhoneAFriendConfig):
+        self.config = config
+
+    @abstractmethod
+    async def run(self, **kwargs) -> dict[str, Any]:
+        """Execute the tool with given parameters."""
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Tool name."""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Tool description."""
+        pass
+
+    @property
+    @abstractmethod
+    def parameters(self) -> dict[str, Any]:
+        """Tool parameters schema."""
+        pass

phone_a_friend_mcp_server/tools/fax_tool.py

@@ -0,0 +1,202 @@
+import os
+from typing import Any
+
+import aiofiles
+
+from phone_a_friend_mcp_server.tools.base_tools import BaseTool
+
+
+class FaxAFriendTool(BaseTool):
+    """
+    Fax-a-Friend: Generate a master prompt file for manual AI consultation.
+
+    ⚠️  ONLY USE WHEN EXPLICITLY REQUESTED BY USER ⚠️
+
+    This tool creates a comprehensive master prompt and saves it to a file for manual
+    copy-paste into external AI interfaces. It uses the same prompt structure as the
+    phone_a_friend tool but requires manual intervention to get the AI response.
+    """
+
+    @property
+    def name(self) -> str:
+        return "fax_a_friend"
+
+    @property
+    def description(self) -> str:
+        return """🚨  **USE ONLY WHEN USER ASKS TO "fax a friend".**
+
+Purpose: pair-programming caliber *coding help* — reviews, debugging,
+refactors, design, migrations.
+
+This tool creates a file for manual AI consultation. After file creation,
+wait for the user to return with the external AI's response.
+
+Hard restrictions:
+  • Generated prompt includes *only* the two context blocks you send.
+  • No memory, no internet, no tools.
+  • You must spell out every fact it should rely on.
+
+Required I/O format:
+```
+<file_tree>
+.
+├── Dockerfile
+├── some_doc_file.md
+├── LICENSE
+├── pyproject.toml
+├── README.md
+├── src
+│   └── some_module
+│       ├── **init**.py
+│       ├── **main**.py
+│       ├── client
+│       │   └── **init**.py
+│       ├── config.py
+│       ├── server.py
+│       └── tools
+│           ├── **init**.py
+│           ├── base_tools.py
+│           └── tool_manager.py
+├── tests
+│   ├── **init**.py
+│   └── test_tools.py
+└── uv.lock
+</file_tree>
+
+<file="src/some_module/server.py">
+# full source here …
+</file>
+```
+The generated prompt expects AI to reply in the same XML structure, adding or
+replacing <file="…"> blocks as needed. Commentary goes outside those tags."""
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "all_related_context": {
+                    "type": "string",
+                    "description": (
+                        "MANDATORY. Everything the friend AI needs to see:\n"
+                        "- The full <file_tree> block (ASCII tree).\n"
+                        '- One or more <file="…"> blocks with the current code.\n'
+                        "- Known constraints (Python version, allowed deps, runtime limits, etc.).\n"
+                        "- Any failing test output or traceback.\n"
+                        "If it's not here, the friend AI can't use it."
+                    ),
+                },
+                "any_additional_context": {
+                    "type": "string",
+                    "description": (
+                        "Optional extras that help but aren't core code:\n"
+                        "- Style guides, architecture docs, API specs.\n"
+                        "- Performance targets, security rules, deployment notes.\n"
+                        "- Similar past solutions or reference snippets.\n"
+                        "Skip it if there's nothing useful."
+                    ),
+                },
+                "task": {
+                    "type": "string",
+                    "description": (
+                        "Plain-English ask. Be surgical.\n"
+                        "Good examples:\n"
+                        "- Refactor synchronous Flask app to async Quart. Keep py3.10.\n"
+                        "- Identify and fix memory leak in src/cache.py.\n"
+                        "- Add unit tests for edge cases in utils/math.py.\n"
+                        'Bad: vague stuff like "make code better".'
+                    ),
+                },
+            },
+            "required": ["all_related_context", "task"],
+        }
+
+    async def run(self, **kwargs) -> dict[str, Any]:
+        all_related_context = kwargs.get("all_related_context", "")
+        any_additional_context = kwargs.get("any_additional_context", "")
+        task = kwargs.get("task", "")
+
+        # Create master prompt using the same logic as phone_a_friend
+        master_prompt = self._create_master_prompt(all_related_context, any_additional_context, task)
+
+        try:
+            # Write to fax_a_friend.md in current working directory
+            file_path = "fax_a_friend.md"
+
+            async with aiofiles.open(file_path, "w", encoding="utf-8") as f:
+                await f.write(master_prompt)
+
+            # Get absolute path for user reference
+            abs_path = os.path.abspath(file_path)
+
+            return {
+                "status": "success",
+                "file_path": abs_path,
+                "file_name": "fax_a_friend.md",
+                "prompt_length": len(master_prompt),
+                "context_length": len(all_related_context + any_additional_context),
+                "task": task,
+                "instructions": self._get_manual_workflow_instructions(abs_path),
+            }
+
+        except Exception as e:
+            return {"status": "failed", "error": str(e), "file_path": "fax_a_friend.md", "context_length": len(all_related_context + any_additional_context), "task": task}
+
+    def _create_master_prompt(self, all_related_context: str, any_additional_context: str, task: str) -> str:
+        """Create a comprehensive prompt identical to PhoneAFriendTool's version."""
+
+        prompt_parts = [
+            "You are a highly capable AI assistant being consulted for critical thinking, complex reasoning and pair-programming caliber coding help.",
+            "You have no memory of previous conversations, so all necessary context is provided below.",
+            "",
+            "=== TASK ===",
+            task,
+            "",
+            "=== ALL RELATED CONTEXT ===",
+            all_related_context,
+        ]
+
+        if any_additional_context.strip():
+            prompt_parts.extend(
+                [
+                    "",
+                    "=== ADDITIONAL CONTEXT ===",
+                    any_additional_context,
+                ]
+            )
+
+        prompt_parts.extend(
+            [
+                "",
+                "=== INSTRUCTIONS ===",
+                "- Analyze the code and requirements step-by-step.",
+                "- Show your reasoning and propose concrete changes.",
+                '- Provide updated code using the XML format (<file_tree> plus <file="…"> blocks).',
+                "- Be explicit and practical.",
+                "",
+                "Please provide your analysis and updated code:",
+            ]
+        )
+
+        return "\n".join(prompt_parts)
+
+    def _get_manual_workflow_instructions(self, file_path: str) -> str:
+        """Generate clear instructions for the manual workflow."""
+        return f"""
+🚨 MANUAL INTERVENTION REQUIRED 🚨
+
+Your master prompt has been saved to: {file_path}
+
+NEXT STEPS - Please follow these instructions:
+
+1. 📂 Open the file: {file_path}
+2. 📋 Copy the ENTIRE prompt content from the file
+3. 🤖 Paste it into your preferred AI chat interface (ChatGPT, Claude, Gemini, etc.)
+4. ⏳ Wait for the AI's response
+5. 📝 Copy the AI's complete response
+6. 🔄 Return to this conversation and provide the AI's response
+
+The prompt is ready for any external AI service. Simply copy and paste the entire content.
+
+💡 TIP: You can use the same prompt with multiple AI services to compare responses!
+"""

phone_a_friend_mcp_server/tools/phone_tool.py

@@ -0,0 +1,216 @@
+from typing import Any
+
+from pydantic_ai import Agent
+from pydantic_ai.models.anthropic import AnthropicModel
+from pydantic_ai.models.google import GoogleModel
+from pydantic_ai.models.openai import OpenAIModel
+from pydantic_ai.providers.anthropic import AnthropicProvider
+from pydantic_ai.providers.google import GoogleProvider
+from pydantic_ai.providers.openai import OpenAIProvider
+from pydantic_ai.providers.openrouter import OpenRouterProvider
+
+from phone_a_friend_mcp_server.tools.base_tools import BaseTool
+
+
+class PhoneAFriendTool(BaseTool):
+    """
+    Phone-a-Friend: Consult an external AI for critical thinking and complex reasoning.
+
+    ⚠️  ONLY USE WHEN EXPLICITLY REQUESTED BY USER ⚠️
+
+    This tool sends your problem to an external AI model for analysis and gets back a response.
+    The external AI has no memory of previous conversations, so you must provide all relevant context.
+    """
+
+    @property
+    def name(self) -> str:
+        return "phone_a_friend"
+
+    @property
+    def description(self) -> str:
+        return """🚨  **USE ONLY WHEN USER ASKS TO "phone a friend".**
+
+Purpose: pair-programming caliber *coding help* — reviews, debugging,
+refactors, design, migrations.
+
+Hard restrictions:
+  • Friend AI sees *only* the two context blocks you send.
+  • No memory, no internet, no tools.
+  • You must spell out every fact it should rely on.
+
+Required I/O format:
+```
+<file_tree>
+.
+├── Dockerfile
+├── some_doc_file.md
+├── LICENSE
+├── pyproject.toml
+├── README.md
+├── src
+│   └── some_module
+│       ├── **init**.py
+│       ├── **main**.py
+│       ├── client
+│       │   └── **init**.py
+│       ├── config.py
+│       ├── server.py
+│       └── tools
+│           ├── **init**.py
+│           ├── base_tools.py
+│           └── tool_manager.py
+├── tests
+│   ├── **init**.py
+│   └── test_tools.py
+└── uv.lock
+</file_tree>
+
+<file="src/some_module/server.py">
+# full source here …
+</file>
+```
+The friend AI must reply in the same XML structure, adding or
+replacing <file="…"> blocks as needed. Commentary goes outside those tags."""
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "all_related_context": {
+                    "type": "string",
+                    "description": (
+                        "MANDATORY. Everything the friend AI needs to see:\n"
+                        "- The full <file_tree> block (ASCII tree).\n"
+                        '- One or more <file="…"> blocks with the current code.\n'
+                        "- Known constraints (Python version, allowed deps, runtime limits, etc.).\n"
+                        "- Any failing test output or traceback.\n"
+                        "If it's not here, the friend AI can't use it."
+                    ),
+                },
+                "any_additional_context": {
+                    "type": "string",
+                    "description": (
+                        "Optional extras that help but aren't core code:\n"
+                        "- Style guides, architecture docs, API specs.\n"
+                        "- Performance targets, security rules, deployment notes.\n"
+                        "- Similar past solutions or reference snippets.\n"
+                        "Skip it if there's nothing useful."
+                    ),
+                },
+                "task": {
+                    "type": "string",
+                    "description": (
+                        "Plain-English ask. Be surgical.\n"
+                        "Good examples:\n"
+                        "- Refactor synchronous Flask app to async Quart. Keep py3.10.\n"
+                        "- Identify and fix memory leak in src/cache.py.\n"
+                        "- Add unit tests for edge cases in utils/math.py.\n"
+                        'Bad: vague stuff like "make code better".'
+                    ),
+                },
+            },
+            "required": ["all_related_context", "task"],
+        }
+
+    async def run(self, **kwargs) -> dict[str, Any]:
+        all_related_context = kwargs.get("all_related_context", "")
+        any_additional_context = kwargs.get("any_additional_context", "")
+        task = kwargs.get("task", "")
+
+        # Create master prompt for external AI
+        master_prompt = self._create_master_prompt(all_related_context, any_additional_context, task)
+
+        try:
+            # Create Pydantic-AI agent with appropriate provider
+            agent = self._create_agent()
+
+            # Send to external AI
+            result = await agent.run(master_prompt)
+
+            return {
+                "response": result.data,
+                "status": "success",
+                "provider": self.config.provider,
+                "model": self.config.model,
+                "context_length": len(all_related_context + any_additional_context),
+                "task": task,
+            }
+
+        except Exception as e:
+            return {
+                "error": str(e),
+                "status": "failed",
+                "provider": self.config.provider,
+                "model": self.config.model,
+                "context_length": len(all_related_context + any_additional_context),
+                "task": task,
+                "master_prompt": master_prompt,  # Include for debugging
+            }
+
+    def _create_agent(self) -> Agent:
+        """Create Pydantic-AI agent with appropriate provider."""
+        if self.config.provider == "openrouter":
+            # OpenRouter has its own dedicated provider
+            provider_kwargs = {"api_key": self.config.api_key}
+            if self.config.base_url:
+                provider_kwargs["base_url"] = self.config.base_url
+            provider = OpenRouterProvider(**provider_kwargs)
+            model = OpenAIModel(self.config.model, provider=provider)
+        elif self.config.provider == "anthropic":
+            # Use Anthropic directly
+            provider_kwargs = {"api_key": self.config.api_key}
+            provider = AnthropicProvider(**provider_kwargs)
+            model = AnthropicModel(self.config.model, provider=provider)
+        elif self.config.provider == "google":
+            # Use Google/Gemini directly
+            provider_kwargs = {"api_key": self.config.api_key}
+            provider = GoogleProvider(**provider_kwargs)
+            model = GoogleModel(self.config.model, provider=provider)
+        else:
+            # Default to OpenAI
+            provider_kwargs = {"api_key": self.config.api_key}
+            if self.config.base_url:
+                provider_kwargs["base_url"] = self.config.base_url
+            provider = OpenAIProvider(**provider_kwargs)
+            model = OpenAIModel(self.config.model, provider=provider)
+
+        return Agent(model)
+
+    def _create_master_prompt(self, all_related_context: str, any_additional_context: str, task: str) -> str:
+        """Create a comprehensive prompt for the external AI."""
+
+        prompt_parts = [
+            "You are a highly capable AI assistant being consulted for critical thinking, complex reasoning and pair-programming caliber coding help.",
+            "You have no memory of previous conversations, so all necessary context is provided below.",
+            "",
+            "=== TASK ===",
+            task,
+            "",
+            "=== ALL RELATED CONTEXT ===",
+            all_related_context,
+        ]
+
+        if any_additional_context.strip():
+            prompt_parts.extend(
+                [
+                    "",
+                    "=== ADDITIONAL CONTEXT ===",
+                    any_additional_context,
+                ]
+            )
+
+        prompt_parts.extend(
+            [
+                "",
+                "=== INSTRUCTIONS ===",
+                "- Analyze the code and requirements step-by-step.",
+                "- Show your reasoning and propose concrete changes.",
+                '- Provide updated code using the XML format (<file_tree> plus <file="…"> blocks).',
+                "- Be explicit and practical.",
+                "",
+                "Please provide your analysis and updated code:",
+            ]
+        )
+
+        return "\n".join(prompt_parts)

phone_a_friend_mcp_server/tools/tool_manager.py

@@ -0,0 +1,43 @@
+from mcp.types import Tool
+
+from phone_a_friend_mcp_server.config import PhoneAFriendConfig
+from phone_a_friend_mcp_server.tools.base_tools import BaseTool
+from phone_a_friend_mcp_server.tools.fax_tool import FaxAFriendTool
+from phone_a_friend_mcp_server.tools.phone_tool import PhoneAFriendTool
+
+
+class ToolManager:
+    """Manages all available tools for the Phone-a-Friend MCP server."""
+
+    def __init__(self, config: PhoneAFriendConfig):
+        self.config = config
+        self._tools: dict[str, BaseTool] = {}
+        self._initialize_tools()
+
+    def _initialize_tools(self):
+        """Initialize all available tools."""
+        tools = [
+            PhoneAFriendTool(self.config),
+            FaxAFriendTool(self.config),
+        ]
+
+        for tool in tools:
+            self._tools[tool.name] = tool
+
+    def get_tool(self, name: str) -> BaseTool:
+        """Get a tool by name."""
+        if name not in self._tools:
+            raise ValueError(f"Tool '{name}' not found")
+        return self._tools[name]
+
+    def list_tools(self) -> list[Tool]:
+        """List all available tools in MCP format."""
+        mcp_tools = []
+        for tool in self._tools.values():
+            mcp_tool = Tool(name=tool.name, description=tool.description, inputSchema=tool.parameters)
+            mcp_tools.append(mcp_tool)
+        return mcp_tools
+
+    def get_tool_names(self) -> list[str]:
+        """Get list of all tool names."""
+        return list(self._tools.keys())

phone_a_friend_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: phone-a-friend-mcp-server
+Version: 0.1.0
+Summary: MCP Server for Phone-a-Friend assistance
+Project-URL: GitHub, https://github.com/abhishekbhakat/phone-a-friend-mcp-server
+Project-URL: Issues, https://github.com/abhishekbhakat/phone-a-friend-mcp-server/issues
+Author-email: Abhishek Bhakat <abhishek.bhakat@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.12.7
+Requires-Dist: click>=8.2.1
+Requires-Dist: mcp>=1.9.2
+Requires-Dist: pydantic-ai-slim[anthropic,google,openai]>=0.2.14
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2.post1; extra == 'dev'
+Requires-Dist: pre-commit>=4.2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.26.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.11.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Phone-a-Friend MCP Server 🧠📞
+
+An AI-to-AI consultation system that enables one AI to "phone a friend" (another AI) for critical thinking, long context reasoning, and complex problem solving via OpenRouter.
+
+## The Problem 🤔
+
+Sometimes an AI encounters complex problems that require:
+- **Deep critical thinking** beyond immediate capabilities
+- **Long context reasoning** with extensive information
+- **Multi-step analysis** that benefits from external perspective
+- **Specialized expertise** from different AI models
+
+## The Solution �
+
+Phone-a-Friend MCP Server creates a **two-step consultation process**:
+
+1. **Context + Reasoning**: Package all relevant context and send to external AI for deep analysis
+2. **Extract Actionable Insights**: Process the reasoning response into usable format for the primary AI
+
+This enables AI systems to leverage other AI models as "consultants" for complex reasoning tasks.
+
+## Architecture 🏗️
+
+```
+Primary AI → Phone-a-Friend MCP → OpenRouter → External AI (GPT-4, Claude, etc.) → Processed Response → Primary AI
+```
+
+**Sequential Workflow:**
+1. `analyze_context` - Gather and structure all relevant context
+2. `get_critical_thinking` - Send context to external AI via OpenRouter for reasoning
+3. `extract_actionable_insights` - Process response into actionable format
+
+## When to Use 🎯
+
+**Ideal for:**
+- Complex multi-step problems requiring deep analysis
+- Situations needing long context reasoning (>100k tokens)
+- Cross-domain expertise consultation
+- Critical decision-making with high stakes
+- Problems requiring multiple perspectives
+
+**Not needed for:**
+- Simple factual questions
+- Basic reasoning tasks
+- Quick responses
+- Well-defined procedural tasks
+
+## Installation 🚀
+
+1. Clone the repository:
+```bash
+git clone https://github.com/abhishekbhakat/phone-a-friend-mcp-server.git
+cd phone-a-friend-mcp-server
+```
+
+2. Install dependencies:
+```bash
+uv pip install -e .
+```
+
+3. Configure your preferred AI provider:
+
+**OpenRouter (recommended - access to multiple models):**
+```bash
+export OPENROUTER_API_KEY="your-openrouter-key"
+# Model will auto-select based on provider
+```
+
+**OpenAI:**
+```bash
+export OPENAI_API_KEY="your-openai-key"
+# Uses latest available model by default
+```
+
+**Anthropic:**
+```bash
+export ANTHROPIC_API_KEY="your-anthropic-key"
+# Uses latest available model by default
+```
+
+**Google/Gemini:**
+```bash
+export GOOGLE_API_KEY="your-google-key"  # or GEMINI_API_KEY
+# Uses latest available model by default
+```
+
+## Usage 💡
+
+### Command Line
+```bash
+# Start the server
+phone-a-friend-mcp-server
+
+# With verbose logging
+phone-a-friend-mcp-server -v
+
+# With specific provider (uses optimal model automatically)
+phone-a-friend-mcp-server --provider anthropic
+phone-a-friend-mcp-server --provider google
+
+# Override with custom model if needed
+phone-a-friend-mcp-server --provider anthropic --model "your-preferred-model"
+```
+
+### Environment Variables
+```bash
+# Auto-detects provider based on available API keys
+export OPENROUTER_API_KEY="your-openrouter-key"  # Preferred
+export OPENAI_API_KEY="your-openai-key"          # Default fallback
+export ANTHROPIC_API_KEY="your-anthropic-key"    # Direct Anthropic
+export GOOGLE_API_KEY="your-google-key"          # Google/Gemini
+
+# Optional overrides (only if you want to override auto-selection)
+export PHONE_A_FRIEND_MODEL="your-preferred-model"
+export PHONE_A_FRIEND_PROVIDER="your-preferred-provider"
+```
+
+## Model Selection 🤖
+
+The system automatically selects the most capable model for each provider:
+- **OpenAI**: Latest reasoning model
+- **Anthropic**: Latest Claude model
+- **Google**: Latest Gemini Pro model
+- **OpenRouter**: Access to latest models from all providers
+
+You can override the auto-selection by setting `PHONE_A_FRIEND_MODEL` environment variable or using the `--model` CLI option.
+
+## Available Tools 🛠️
+
+### phone_a_friend
+Consult an external AI for critical thinking and complex reasoning via OpenRouter.
+
+**IMPORTANT:** The external AI is very smart but has NO MEMORY of previous conversations.
+The quality of the response depends ENTIRELY on the quality and completeness of the context you provide.
+
+**Parameters:**
+- `all_related_context` (required): ALL context directly related to the problem. Include:
+  - Background information and history
+  - Previous attempts and their outcomes
+  - Stakeholders and their perspectives
+  - Constraints, requirements, and limitations
+  - Current situation and circumstances
+  - Any relevant data, metrics, or examples
+  - Timeline and deadlines
+  - Success criteria and goals
+
+- `any_additional_context` (optional): ANY additional context that might be helpful. Include:
+  - Relevant documentation, specifications, or guidelines
+  - Industry standards or best practices
+  - Similar cases or precedents
+  - Technical details or domain knowledge
+  - Regulatory or compliance requirements
+  - Tools, resources, or technologies available
+  - Budget or resource constraints
+  - Organizational context or culture
+
+- `task` (required): The specific task or question for the external AI. Be clear about:
+  - What exactly you need help with
+  - What type of analysis or reasoning you want
+  - What format you prefer for the response
+  - What decisions need to be made
+  - What problems need to be solved
+
+**Example Usage:**
+```
+all_related_context: "We're a SaaS startup with 50 employees. Our customer churn rate increased from 5% to 12% over the last quarter. We recently changed our pricing model and added new features. Customer support tickets increased 40%. Our main competitors are offering similar features at lower prices."
+
+any_additional_context: "Industry benchmark for SaaS churn is 6-8%. Our pricing increased by 30%. New features include AI analytics and advanced reporting. Customer feedback mentions complexity and cost concerns."
+
+task: "Analyze the churn increase and provide a comprehensive action plan to reduce it back to 5% within 6 months. Include specific strategies, timeline, and success metrics."
+```
+
+The system will automatically route this to the most capable AI model available based on your configured provider.
+
+## Claude Desktop Configuration 🖥️
+
+To use Phone-a-Friend MCP server with Claude Desktop, add this configuration to your `claude_desktop_config.json` file:
+
+### Configuration File Location
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Configuration
+
+**Option 1: Using uv (Recommended)**
+```json
+{
+  "mcpServers": {
+    "phone-a-friend": {
+      "command": "uvx",
+      "args": [
+        "run",
+        "--refresh",
+        "phone-a-friend-mcp-server",
+      ],
+      "env": {
+        "OPENROUTER_API_KEY": "your-openrouter-api-key",
+        "PHONE_A_FRIEND_MODEL": "anthropic/claude-4-opus"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables in Configuration
+
+You can configure different AI providers directly in the Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "phone-a-friend": {
+      "command": "phone-a-friend-mcp-server",
+      "env": {
+        "OPENROUTER_API_KEY": "your-openrouter-api-key",
+        "PHONE_A_FRIEND_MODEL": "anthropic/claude-4-opus"
+      }
+    }
+  }
+}
+```
+
+**Alternative Providers:**
+```json
+{
+  "mcpServers": {
+    "phone-a-friend-openai": {
+      "command": "phone-a-friend-mcp-server",
+      "env": {
+        "OPENAI_API_KEY": "your-openai-api-key"
+      }
+    },
+    "phone-a-friend-anthropic": {
+      "command": "phone-a-friend-mcp-server",
+      "env": {
+        "ANTHROPIC_API_KEY": "your-anthropic-api-key"
+      }
+    },
+    "phone-a-friend-google": {
+      "command": "phone-a-friend-mcp-server",
+      "env": {
+        "GOOGLE_API_KEY": "your-google-api-key"
+      }
+    }
+  }
+}
+```
+
+### Setup Steps
+
+1. **Install Phone-a-Friend MCP Server** (see Installation section above)
+2. **Open Claude Desktop Settings** → Developer → Edit Config
+3. **Add the configuration** (choose one of the options above)
+4. **Replace paths and API keys** with your actual values
+5. **Restart Claude Desktop**
+6. **Look for the 🔨 hammer icon** in the input box to confirm the server is connected
+
+### Troubleshooting
+
+If the server doesn't appear in Claude Desktop:
+
+1. **Check logs**:
+   - macOS: `~/Library/Logs/Claude/mcp*.log`
+   - Windows: `%APPDATA%\Claude\logs\mcp*.log`
+
+2. **Verify paths** are absolute and correct
+3. **Test manually** in terminal:
+   ```bash
+   phone-a-friend-mcp-server -v
+   ```
+4. **Restart Claude Desktop** completely
+5. **Check API keys** are valid and have sufficient credits
+
+## Development 🔧
+
+### Running Tests
+```bash
+pytest
+```
+
+### Code Formatting
+```bash
+ruff format .
+ruff check .
+```
+
+## License 📄
+
+MIT License - see LICENSE file for details.

phone_a_friend_mcp_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+phone_a_friend_mcp_server/__init__.py,sha256=RaayGu6L95bFNEioVLZwFifnKMl9-yhUU7glBInuqXA,1895
+phone_a_friend_mcp_server/__main__.py,sha256=A-8-jkY2FK2foabew5I-Wk2A54IwzWZcydlQKfiR-p4,51
+phone_a_friend_mcp_server/config.py,sha256=Wfs68Zw7xXhAQ-77z3gblqsnmqO5bed-f2ggJkvgzUM,2356
+phone_a_friend_mcp_server/server.py,sha256=ppx8QxQvJihcOzJkrJFlh9qyZ0fvI_eGP0TgYUC0Vcw,3394
+phone_a_friend_mcp_server/client/__init__.py,sha256=fsa8DXjz4rzYXmOUAdLdTpTwPSlZ3zobmBGXqnCEaWs,47
+phone_a_friend_mcp_server/tools/__init__.py,sha256=jtuvmcStXzbaM8wuhOKC8M8mBqDjHr-ypZ2ct1Rgi7Q,46
+phone_a_friend_mcp_server/tools/base_tools.py,sha256=DMjFq0E3TO9a9I7QY4wQ_B4-SntdXzSZzrYymFzSmVE,765
+phone_a_friend_mcp_server/tools/fax_tool.py,sha256=vzcGITygR49q9cu7Fw7SYcER7u_bKY6FKfvwBGKrRGs,7573
+phone_a_friend_mcp_server/tools/phone_tool.py,sha256=zvZOU9TgC7PR6nm7rj13PPH0dRnBN9XYk2bf2frIWpE,8356
+phone_a_friend_mcp_server/tools/tool_manager.py,sha256=VVtENC-n3D4GV6Cy3l9--30SJi06mJdyEiG7F_mfP7I,1474
+phone_a_friend_mcp_server-0.1.0.dist-info/METADATA,sha256=jXvQP4I_B2uhleQWo-gIcvWntCEJfeVe0Bz2VxLI_sE,10048
+phone_a_friend_mcp_server-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+phone_a_friend_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=c_08XI-vG07VmUT3mtzyuCQjaus5l1NBl4q00Q3jLug,86
+phone_a_friend_mcp_server-0.1.0.dist-info/licenses/LICENSE,sha256=-8bInetillKZC0qZDT8RWYIOrph3HIU5cr5N4Pg7bBE,1065
+phone_a_friend_mcp_server-0.1.0.dist-info/RECORD,,

phone_a_friend_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

phone_a_friend_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+phone-a-friend-mcp-server = phone_a_friend_mcp_server.__main__:main

phone_a_friend_mcp_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Abhishek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.