phone-a-friend-mcp-server 0.1.0__tar.gz → 0.1.2__tar.gz

phone_a_friend_mcp_server-0.1.2/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: phone-a-friend-mcp-server
+Version: 0.1.2
+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
+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
+
+## 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 API access (choose one method):
+
+**Option A: Environment Variables**
+```bash
+export OPENROUTER_API_KEY="your-openrouter-key"
+# OR
+export OPENAI_API_KEY="your-openai-key"
+# OR
+export ANTHROPIC_API_KEY="your-anthropic-key"
+# OR
+export GOOGLE_API_KEY="your-google-key"
+```
+
+**Option B: CLI Arguments**
+```bash
+phone-a-friend-mcp-server --api-key "your-api-key" --provider openai
+```
+
+## Usage 💡
+
+### Command Line Options
+```bash
+
+# Custom base URL (if needed)
+phone-a-friend-mcp-server --base-url "https://custom-api.example.com"
+
+# Temperature control (0.0 = deterministic, 2.0 = very creative)
+phone-a-friend-mcp-server --temperature 0.4
+
+# Combined example
+phone-a-friend-mcp-server --api-key "sk-..." --provider openai --model "o3" -v
+```
+
+### Environment Variables (Optional)
+```bash
+
+# Optional model overrides
+export PHONE_A_FRIEND_MODEL="your-preferred-model"
+export PHONE_A_FRIEND_PROVIDER="your-preferred-provider"
+export PHONE_A_FRIEND_BASE_URL="https://custom-api.example.com"
+
+# Temperature control (0.0-2.0, where 0.0 = deterministic, 2.0 = very creative)
+export PHONE_A_FRIEND_TEMPERATURE=0.4
+```
+
+## Model Selection 🤖
+
+Default reasoning models to be selected:
+- **OpenAI**: o3
+- **Anthropic**: Claude 4 Opus
+- **Google**: Gemini 2.5 Pro Preview 05-06 (automatically set temperature to 0.0)
+- **OpenRouter**: For other models like Deepseek or Qwen
+
+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 external AI for critical thinking and complex reasoning. Makes API calls to get responses.
+
+### fax_a_friend
+📠 Generate master prompt file for manual AI consultation. Creates file for copy-paste workflow.
+
+**Parameters (both tools):**
+- `all_related_context` (required): All context related to the problem
+- `any_additional_context` (optional): Additional helpful context
+- `task` (required): Specific task or question for the AI
+
+
+## Use Cases 🎯
+
+1. In-depth Reasoning for Vibe Coding
+2. For complex algorithms, data structures, or mathematical computations
+3. Frontend Development with React, Vue, CSS, or modern frontend frameworks
+
+## 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": [
+        "--refresh",
+        "phone-a-friend-mcp-server",
+      ],
+      "env": {
+        "OPENROUTER_API_KEY": "your-openrouter-api-key",
+        "PHONE_A_FRIEND_MODEL": "anthropic/claude-4-opus",
+        "PHONE_A_FRIEND_TEMPERATURE": "0.4"
+      }
+    }
+  }
+}
+```
+
+### 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",
+        "PHONE_A_FRIEND_TEMPERATURE": "0.4"
+      }
+    }
+  }
+}
+```
+
+## License 📄
+
+MIT License - see LICENSE file for details.

phone_a_friend_mcp_server-0.1.2/README.md

@@ -0,0 +1,181 @@
+# 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
+
+## 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 API access (choose one method):
+
+**Option A: Environment Variables**
+```bash
+export OPENROUTER_API_KEY="your-openrouter-key"
+# OR
+export OPENAI_API_KEY="your-openai-key"
+# OR
+export ANTHROPIC_API_KEY="your-anthropic-key"
+# OR
+export GOOGLE_API_KEY="your-google-key"
+```
+
+**Option B: CLI Arguments**
+```bash
+phone-a-friend-mcp-server --api-key "your-api-key" --provider openai
+```
+
+## Usage 💡
+
+### Command Line Options
+```bash
+
+# Custom base URL (if needed)
+phone-a-friend-mcp-server --base-url "https://custom-api.example.com"
+
+# Temperature control (0.0 = deterministic, 2.0 = very creative)
+phone-a-friend-mcp-server --temperature 0.4
+
+# Combined example
+phone-a-friend-mcp-server --api-key "sk-..." --provider openai --model "o3" -v
+```
+
+### Environment Variables (Optional)
+```bash
+
+# Optional model overrides
+export PHONE_A_FRIEND_MODEL="your-preferred-model"
+export PHONE_A_FRIEND_PROVIDER="your-preferred-provider"
+export PHONE_A_FRIEND_BASE_URL="https://custom-api.example.com"
+
+# Temperature control (0.0-2.0, where 0.0 = deterministic, 2.0 = very creative)
+export PHONE_A_FRIEND_TEMPERATURE=0.4
+```
+
+## Model Selection 🤖
+
+Default reasoning models to be selected:
+- **OpenAI**: o3
+- **Anthropic**: Claude 4 Opus
+- **Google**: Gemini 2.5 Pro Preview 05-06 (automatically set temperature to 0.0)
+- **OpenRouter**: For other models like Deepseek or Qwen
+
+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 external AI for critical thinking and complex reasoning. Makes API calls to get responses.
+
+### fax_a_friend
+📠 Generate master prompt file for manual AI consultation. Creates file for copy-paste workflow.
+
+**Parameters (both tools):**
+- `all_related_context` (required): All context related to the problem
+- `any_additional_context` (optional): Additional helpful context
+- `task` (required): Specific task or question for the AI
+
+
+## Use Cases 🎯
+
+1. In-depth Reasoning for Vibe Coding
+2. For complex algorithms, data structures, or mathematical computations
+3. Frontend Development with React, Vue, CSS, or modern frontend frameworks
+
+## 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": [
+        "--refresh",
+        "phone-a-friend-mcp-server",
+      ],
+      "env": {
+        "OPENROUTER_API_KEY": "your-openrouter-api-key",
+        "PHONE_A_FRIEND_MODEL": "anthropic/claude-4-opus",
+        "PHONE_A_FRIEND_TEMPERATURE": "0.4"
+      }
+    }
+  }
+}
+```
+
+### 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",
+        "PHONE_A_FRIEND_TEMPERATURE": "0.4"
+      }
+    }
+  }
+}
+```
+
+## License 📄
+
+MIT License - see LICENSE file for details.

{phone_a_friend_mcp_server-0.1.0 → phone_a_friend_mcp_server-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "phone-a-friend-mcp-server"
-version = "0.1.0"
+version = "0.1.2"
 description = "MCP Server for Phone-a-Friend assistance"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -14,7 +14,7 @@ dependencies = [
     "pydantic>=2.11.5",
     "pydantic-ai-slim[openai,anthropic,google]>=0.2.14",
     "click>=8.2.1",
-    "pyyaml>=6.0.0", # No newer version found in search results
+    "pyyaml>=6.0.0",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -32,16 +32,6 @@ Issues = "https://github.com/abhishekbhakat/phone-a-friend-mcp-server/issues"
 [project.scripts]
 phone-a-friend-mcp-server = "phone_a_friend_mcp_server.__main__:main"
 
-[project.optional-dependencies]
-dev = [
-    "build>=1.2.2.post1",
-    "pre-commit>=4.2.0",
-    "pytest>=8.3.4", # No newer version found in search results
-    "pytest-asyncio>=0.26.0",
-    "pytest-mock>=3.14.1",
-    "ruff>=0.11.12"
-]
-
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -78,3 +68,13 @@ lint.unfixable = []
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"
+
+[dependency-groups]
+dev = [
+    "build>=1.2.2.post1",
+    "pre-commit>=4.2.0",
+    "pytest>=8.4.0",
+    "pytest-asyncio>=1.0.0",
+    "pytest-mock>=3.14.1",
+    "ruff>=0.11.12",
+]

{phone_a_friend_mcp_server-0.1.0 → phone_a_friend_mcp_server-0.1.2}/src/phone_a_friend_mcp_server/__init__.py

@@ -15,7 +15,8 @@ from phone_a_friend_mcp_server.server import serve
 @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:
+@click.option("--temperature", type=float, help="Temperature for the model (0.0-2.0). Lower values = more deterministic, higher = more creative")
+def main(verbose: int, api_key: str = None, model: str = None, provider: str = None, base_url: str = None, temperature: float = None) -> None:
     """MCP server for Phone-a-Friend AI consultation"""
     logging_level = logging.WARN
     if verbose == 1:
@@ -25,7 +26,6 @@ def main(verbose: int, api_key: str = None, model: str = None, provider: str = N
 
     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")
@@ -37,15 +37,12 @@ def main(verbose: int, api_key: str = None, model: str = None, provider: str = N
     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
+    config_temperature = temperature
     try:
-        config = PhoneAFriendConfig(api_key=config_api_key, model=config_model, provider=config_provider, base_url=config_base_url)
+        config = PhoneAFriendConfig(api_key=config_api_key, model=config_model, provider=config_provider, base_url=config_base_url, temperature=config_temperature)
     except ValueError as e:
         click.echo(f"Configuration error: {e}", err=True)
         sys.exit(1)
-
-    # Start the server
     asyncio.run(serve(config))
 
 

{phone_a_friend_mcp_server-0.1.0 → phone_a_friend_mcp_server-0.1.2}/src/phone_a_friend_mcp_server/config.py

@@ -1,28 +1,30 @@
+import os
+
+
 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:
+    def __init__(self, api_key: str | None = None, model: str | None = None, base_url: str | None = None, provider: str | None = None, temperature: float | 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')
+            provider: Provider type ('openai', 'openrouter', 'anthropic', 'google')
+            temperature: Temperature value for the model (0.0-2.0), overrides defaults
         """
         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
+        self.base_url = base_url
+        self.temperature = self._validate_temperature(temperature)
 
-        # 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"):
@@ -32,12 +34,11 @@ class PhoneAFriendConfig:
         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"}
+        models = {"openai": "o3", "openrouter": "anthropic/claude-4-opus", "anthropic": "claude-4-opus", "google": "gemini-2.5-pro-preview-06-05"}
         if self.provider not in models:
             raise ValueError(f"Unknown provider: {self.provider}. Supported providers: {list(models.keys())}")
         return models[self.provider]
@@ -46,3 +47,41 @@ class PhoneAFriendConfig:
         """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")
+
+    def _validate_temperature(self, temperature: float | None) -> float | None:
+        """Validate temperature value or get from environment variable."""
+        temp_value = temperature
+        if temp_value is None:
+            env_temp = os.environ.get("PHONE_A_FRIEND_TEMPERATURE")
+            if env_temp is not None:
+                try:
+                    temp_value = float(env_temp)
+                except ValueError:
+                    raise ValueError(f"Invalid temperature value in PHONE_A_FRIEND_TEMPERATURE: {env_temp}")
+
+        if temp_value is None:
+            temp_value = self._get_default_temperature_for_model()
+
+        if temp_value is not None:
+            if not isinstance(temp_value, int | float):
+                raise ValueError(f"Temperature must be a number, got {type(temp_value).__name__}")
+            if not (0.0 <= temp_value <= 2.0):
+                raise ValueError(f"Temperature must be between 0.0 and 2.0, got {temp_value}")
+
+        return temp_value
+
+    def _get_default_temperature_for_model(self) -> float | None:
+        """Get default temperature for specific models that benefit from it."""
+        default_temperatures = {
+            "gemini-2.5-pro-preview-06-05": 0.0,
+        }
+
+        return default_temperatures.get(self.model)
+
+    def get_temperature(self) -> float | None:
+        """Get the temperature setting for the current model.
+
+        Returns:
+            Temperature value if set, None otherwise
+        """
+        return self.temperature

{phone_a_friend_mcp_server-0.1.0 → phone_a_friend_mcp_server-0.1.2}/src/phone_a_friend_mcp_server/server.py

@@ -12,6 +12,22 @@ from phone_a_friend_mcp_server.tools.tool_manager import ToolManager
 logger = logging.getLogger(__name__)
 
 
+def _format_tool_result(result: Any) -> str:
+    """Format tool result for display."""
+    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 formatted_result.strip()
+    else:
+        return str(result)
+
+
 async def serve(config: PhoneAFriendConfig) -> None:
     """Start the Phone-a-Friend MCP server.
 
@@ -55,19 +71,8 @@ async def serve(config: PhoneAFriendConfig) -> None:
             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))]
+            formatted_result = _format_tool_result(result)
+            return [TextContent(type="text", text=formatted_result)]
 
         except Exception as e:
             logger.error("Tool execution failed: %s", e)