phone-a-friend-mcp-server 0.1.2__tar.gz → 0.3.0rc1__tar.gz

{phone_a_friend_mcp_server-0.1.2 → phone_a_friend_mcp_server-0.3.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phone-a-friend-mcp-server
-Version: 0.1.2
+Version: 0.3.0rc1
 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
@@ -17,6 +17,7 @@ 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: pathspec>=0.12.1
 Requires-Dist: pydantic-ai-slim[anthropic,google,openai]>=0.2.14
 Requires-Dist: pydantic>=2.11.5
 Requires-Dist: pyyaml>=6.0.0
@@ -46,7 +47,7 @@ This enables AI systems to leverage other AI models as "consultants" for complex
 ## Architecture 🏗️
 
 ```
-Primary AI → Phone-a-Friend MCP → OpenRouter → External AI (GPT-4, Claude, etc.) → Processed Response → Primary AI
+Primary AI → Phone-a-Friend MCP → OpenRouter → External AI (O3, Claude, etc.) → Processed Response → Primary AI
 ```
 
 **Sequential Workflow:**
@@ -63,87 +64,105 @@ Primary AI → Phone-a-Friend MCP → OpenRouter → External AI (GPT-4, Claude,
 - Critical decision-making with high stakes
 - Problems requiring multiple perspectives
 
-## Installation 🚀
+## Quick Start ⚡
 
-1. Clone the repository:
-```bash
-git clone https://github.com/abhishekbhakat/phone-a-friend-mcp-server.git
-cd phone-a-friend-mcp-server
-```
+Configure your MCP client (e.g., Claude Desktop) using the JSON block below—no cloning or manual installation required.
+The `uv` runner will automatically download and execute the server package if it isn't present.
 
-2. Install dependencies:
-```bash
-uv pip install -e .
+Add the following JSON configuration to your MCP client and replace `<YOUR_API_KEY>` with your key:
+
+```json
+{
+  "mcpServers": {
+    "phone-a-friend": {
+      "command": "uvx",
+      "args": [
+        "phone-a-friend-mcp-server",
+        "--provider", "openai",
+        "--api-key", "<YOUR_API_KEY>"
+      ]
+    }
+  }
+}
 ```
+> That's it! You can now use the `phone_a_friend` tool in any compatible client. For more options, see the Advanced Configuration section.
 
-3. Configure API access (choose one method):
+## Available Tools 🛠️
 
-**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"
-```
+### phone_a_friend
+📞 Consult external AI for critical thinking and complex reasoning. Makes API calls to get responses.
 
-**Option B: CLI Arguments**
-```bash
-phone-a-friend-mcp-server --api-key "your-api-key" --provider openai
-```
+### fax_a_friend
+📠 Generate master prompt file for manual AI consultation. Creates file for copy-paste workflow.
 
-## Usage 💡
+**Parameters**
 
-### Command Line Options
-```bash
+*phone_a_friend*
 
-# Custom base URL (if needed)
-phone-a-friend-mcp-server --base-url "https://custom-api.example.com"
+- `all_related_context` (required): General, non-code context such as constraints, tracebacks, or high-level requirements.
+- `file_list` (required): Array of file paths or glob patterns. **Just pass the paths** – the server automatically reads those files (skips anything in `.gitignore` or non-text/binary) and builds the full code context for the external AI.
+- `task` (required): A clear, specific description of what you want the external AI to do.
 
-# Temperature control (0.0 = deterministic, 2.0 = very creative)
-phone-a-friend-mcp-server --temperature 0.4
+*fax_a_friend*
 
-# Combined example
-phone-a-friend-mcp-server --api-key "sk-..." --provider openai --model "o3" -v
-```
+- `all_related_context` (required): Same as above.
+- `file_list` (required): Same as above.
+- `task` (required): Same as above.
+- `output_directory` (required): Directory where the generated `fax_a_friend.md` master prompt file will be saved.
 
-### Environment Variables (Optional)
-```bash
+## Advanced Configuration 🔧
 
-# 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"
+This section covers all configuration options, including environment variables, CLI flags, and model selection.
 
-# Temperature control (0.0-2.0, where 0.0 = deterministic, 2.0 = very creative)
-export PHONE_A_FRIEND_TEMPERATURE=0.4
+### Providers and API Keys
+
+The server can be configured via CLI flags or environment variables.
+
+| Provider | CLI Flag | Environment Variable |
+| :--- | :--- | :--- |
+| OpenAI | `--provider openai` | `OPENAI_API_KEY` |
+| OpenRouter | `--provider openrouter` | `OPENROUTER_API_KEY` |
+| Anthropic | `--provider anthropic` | `ANTHROPIC_API_KEY` |
+| Google | `--provider google` | `GOOGLE_API_KEY` |
+
+**CLI Example:**
+```bash
+phone-a-friend-mcp-server --provider openai --api-key "sk-..."
 ```
 
-## Model Selection 🤖
+**Environment Variable Example:**
+```bash
+export OPENAI_API_KEY="sk-..."
+phone-a-friend-mcp-server
+```
 
-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
+### Model Selection
 
-You can override the auto-selection by setting `PHONE_A_FRIEND_MODEL` environment variable or using the `--model` CLI option.
+You can override the default model for each provider.
 
-## Available Tools 🛠️
+| Provider | Default Model |
+| :--- | :--- |
+| **OpenAI** | `o3` |
+| **Anthropic** | `Claude 4 Opus` |
+| **Google** | `Gemini 2.5 Pro Preview 05-06` |
+| **OpenRouter**| `anthropic/claude-4-opus` |
 
-### phone_a_friend
-📞 Consult external AI for critical thinking and complex reasoning. Makes API calls to get responses.
+**Override with CLI:**
+```bash
+phone-a-friend-mcp-server --model "o3"
+```
 
-### fax_a_friend
-📠 Generate master prompt file for manual AI consultation. Creates file for copy-paste workflow.
+**Override with Environment Variable:**
+```bash
+export PHONE_A_FRIEND_MODEL="o3"
+```
 
-**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
+### Additional Options
 
+| Feature | CLI Flag | Environment Variable | Default |
+| :--- | :--- | :--- | :--- |
+| **Temperature** | `--temperature 0.5` | `PHONE_A_FRIEND_TEMPERATURE` | `0.4` |
+| **Base URL** | `--base-url ...` | `PHONE_A_FRIEND_BASE_URL` | Provider default |
 
 ## Use Cases 🎯
 
@@ -151,55 +170,6 @@ You can override the auto-selection by setting `PHONE_A_FRIEND_MODEL` environmen
 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.3.0rc1/README.md

@@ -0,0 +1,150 @@
+# 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 (O3, 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
+
+## Quick Start ⚡
+
+Configure your MCP client (e.g., Claude Desktop) using the JSON block below—no cloning or manual installation required.
+The `uv` runner will automatically download and execute the server package if it isn't present.
+
+Add the following JSON configuration to your MCP client and replace `<YOUR_API_KEY>` with your key:
+
+```json
+{
+  "mcpServers": {
+    "phone-a-friend": {
+      "command": "uvx",
+      "args": [
+        "phone-a-friend-mcp-server",
+        "--provider", "openai",
+        "--api-key", "<YOUR_API_KEY>"
+      ]
+    }
+  }
+}
+```
+> That's it! You can now use the `phone_a_friend` tool in any compatible client. For more options, see the Advanced Configuration section.
+
+## 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**
+
+*phone_a_friend*
+
+- `all_related_context` (required): General, non-code context such as constraints, tracebacks, or high-level requirements.
+- `file_list` (required): Array of file paths or glob patterns. **Just pass the paths** – the server automatically reads those files (skips anything in `.gitignore` or non-text/binary) and builds the full code context for the external AI.
+- `task` (required): A clear, specific description of what you want the external AI to do.
+
+*fax_a_friend*
+
+- `all_related_context` (required): Same as above.
+- `file_list` (required): Same as above.
+- `task` (required): Same as above.
+- `output_directory` (required): Directory where the generated `fax_a_friend.md` master prompt file will be saved.
+
+## Advanced Configuration 🔧
+
+This section covers all configuration options, including environment variables, CLI flags, and model selection.
+
+### Providers and API Keys
+
+The server can be configured via CLI flags or environment variables.
+
+| Provider | CLI Flag | Environment Variable |
+| :--- | :--- | :--- |
+| OpenAI | `--provider openai` | `OPENAI_API_KEY` |
+| OpenRouter | `--provider openrouter` | `OPENROUTER_API_KEY` |
+| Anthropic | `--provider anthropic` | `ANTHROPIC_API_KEY` |
+| Google | `--provider google` | `GOOGLE_API_KEY` |
+
+**CLI Example:**
+```bash
+phone-a-friend-mcp-server --provider openai --api-key "sk-..."
+```
+
+**Environment Variable Example:**
+```bash
+export OPENAI_API_KEY="sk-..."
+phone-a-friend-mcp-server
+```
+
+### Model Selection
+
+You can override the default model for each provider.
+
+| Provider | Default Model |
+| :--- | :--- |
+| **OpenAI** | `o3` |
+| **Anthropic** | `Claude 4 Opus` |
+| **Google** | `Gemini 2.5 Pro Preview 05-06` |
+| **OpenRouter**| `anthropic/claude-4-opus` |
+
+**Override with CLI:**
+```bash
+phone-a-friend-mcp-server --model "o3"
+```
+
+**Override with Environment Variable:**
+```bash
+export PHONE_A_FRIEND_MODEL="o3"
+```
+
+### Additional Options
+
+| Feature | CLI Flag | Environment Variable | Default |
+| :--- | :--- | :--- | :--- |
+| **Temperature** | `--temperature 0.5` | `PHONE_A_FRIEND_TEMPERATURE` | `0.4` |
+| **Base URL** | `--base-url ...` | `PHONE_A_FRIEND_BASE_URL` | Provider default |
+
+## 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
+
+## License 📄
+
+MIT License - see LICENSE file for details.

{phone_a_friend_mcp_server-0.1.2 → phone_a_friend_mcp_server-0.3.0rc1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "phone-a-friend-mcp-server"
-version = "0.1.2"
+version = "0.3.0rc1"
 description = "MCP Server for Phone-a-Friend assistance"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -15,6 +15,7 @@ dependencies = [
     "pydantic-ai-slim[openai,anthropic,google]>=0.2.14",
     "click>=8.2.1",
     "pyyaml>=6.0.0",
+    "pathspec>=0.12.1",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",

{phone_a_friend_mcp_server-0.1.2 → phone_a_friend_mcp_server-0.3.0rc1}/src/phone_a_friend_mcp_server/config.py

@@ -74,6 +74,7 @@ class PhoneAFriendConfig:
         """Get default temperature for specific models that benefit from it."""
         default_temperatures = {
             "gemini-2.5-pro-preview-06-05": 0.0,
+            "gemini-2.5-pro": 0.0,
         }
 
         return default_temperatures.get(self.model)

{phone_a_friend_mcp_server-0.1.2 → phone_a_friend_mcp_server-0.3.0rc1}/src/phone_a_friend_mcp_server/tools/fax_tool.py

@@ -4,6 +4,7 @@ from typing import Any
 import aiofiles
 
 from phone_a_friend_mcp_server.tools.base_tools import BaseTool
+from phone_a_friend_mcp_server.utils.context_builder import build_code_context
 
 
 class FaxAFriendTool(BaseTool):
@@ -35,9 +36,10 @@ 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.
+Replies must be exhaustively detailed. Do **NOT** include files ignored by .gitignore (e.g., *.pyc).
 
 Hard restrictions:
-  • Generated prompt includes *only* the two context blocks you send.
+  • Generated prompt includes *only* the context you provide.
   • No memory, no internet, no tools.
   • You must spell out every fact it should rely on.
 
@@ -83,22 +85,18 @@ replacing <file="…"> blocks as needed. Commentary goes outside those tags."""
                 "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."
+                        "General context for the friend AI. Include known constraints "
+                        "(Python version, allowed deps, etc.), failing test output, tracebacks, "
+                        "or code snippets for reference. For complete files, use file_list instead."
                     ),
                 },
-                "any_additional_context": {
-                    "type": "string",
+                "file_list": {
+                    "type": "array",
+                    "items": {"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."
+                        "Optional but recommended. A list of file paths or glob patterns to be included in the code context. "
+                        "The tool will automatically read these files, filter them against .gitignore, and build the context. "
+                        "Better and faster than including complete files in all_related_context."
                     ),
                 },
                 "task": {
@@ -127,24 +125,21 @@ replacing <file="…"> blocks as needed. Commentary goes outside those tags."""
 
     async def run(self, **kwargs) -> dict[str, Any]:
         all_related_context = kwargs.get("all_related_context", "")
-        any_additional_context = kwargs.get("any_additional_context", "")
+        file_list = kwargs.get("file_list", [])
         task = kwargs.get("task", "")
         output_directory = kwargs.get("output_directory", "")
 
-        # Create master prompt using the same logic as phone_a_friend
-        master_prompt = self._create_master_prompt(all_related_context, any_additional_context, task)
+        code_context = build_code_context(file_list)
+        master_prompt = self._create_master_prompt(all_related_context, code_context, task)
 
         try:
-            # Validate and prepare output directory
             output_dir = self._prepare_output_directory(output_directory)
 
-            # Create full file path
             file_path = os.path.join(output_dir, "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 {
@@ -153,15 +148,15 @@ replacing <file="…"> blocks as needed. Commentary goes outside those tags."""
                 "file_name": "fax_a_friend.md",
                 "output_directory": output_dir,
                 "prompt_length": len(master_prompt),
-                "context_length": len(all_related_context + any_additional_context),
+                "context_length": len(master_prompt),
                 "task": task,
                 "instructions": self._get_manual_workflow_instructions(abs_path),
             }
 
         except Exception as e:
-            return {"status": "failed", "error": str(e), "output_directory": output_directory, "context_length": len(all_related_context + any_additional_context), "task": task}
+            return {"status": "failed", "error": str(e), "output_directory": output_directory, "context_length": len(master_prompt), "task": task}
 
-    def _create_master_prompt(self, all_related_context: str, any_additional_context: str, task: str) -> str:
+    def _create_master_prompt(self, all_related_context: str, code_context: str, task: str) -> str:
         """Create a comprehensive prompt identical to PhoneAFriendTool's version."""
 
         prompt_parts = [
@@ -171,23 +166,19 @@ replacing <file="…"> blocks as needed. Commentary goes outside those tags."""
             "=== TASK ===",
             task,
             "",
-            "=== ALL RELATED CONTEXT ===",
+            "=== GENERAL CONTEXT ===",
             all_related_context,
+            "",
+            "=== CODE CONTEXT ===",
+            code_context,
         ]
 
-        if any_additional_context.strip():
-            prompt_parts.extend(
-                [
-                    "",
-                    "=== ADDITIONAL CONTEXT ===",
-                    any_additional_context,
-                ]
-            )
-
         prompt_parts.extend(
             [
                 "",
                 "=== INSTRUCTIONS ===",
+                "- Provide exhaustive, step-by-step reasoning.",
+                "- Never include files matching .gitignore patterns.",
                 "- 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).',
@@ -204,17 +195,14 @@ replacing <file="…"> blocks as needed. Commentary goes outside those tags."""
         if not output_directory:
             raise ValueError("output_directory parameter is required")
 
-        # Expand user path (~) and resolve relative paths
         expanded_path = os.path.expanduser(output_directory)
         resolved_path = os.path.abspath(expanded_path)
 
-        # Create directory if it doesn't exist
         try:
             os.makedirs(resolved_path, exist_ok=True)
         except OSError as e:
             raise ValueError(f"Cannot create directory '{resolved_path}': {e}")
 
-        # Check if directory is writable
         if not os.access(resolved_path, os.W_OK):
             raise ValueError(f"Directory '{resolved_path}' is not writable")