contextportal 0.1.0__tar.gz

contextportal-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: contextportal
+Version: 0.1.0
+Summary: The authenticated fetch layer for AI agents.
+Author: NavadeepDj
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/NavadeepDj/ContextPortal
+Project-URL: Repository, https://github.com/NavadeepDj/ContextPortal
+Project-URL: Issues, https://github.com/NavadeepDj/ContextPortal/issues
+Keywords: mcp,ai-agents,retrieval,browser-automation,context-proxy,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: redis[hiredis]>=5.0.0
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: playwright>=1.62.0
+Requires-Dist: readability-lxml>=0.8.4.1
+Requires-Dist: markdownify>=1.2.3
+Requires-Dist: mcp[cli]>=2.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+# 🔑 ContextPortal
+
+> **Give your AI agent access to authenticated web pages — without giving it your credentials.**
+
+Your AI agent can fetch any public webpage. But the moment it hits a login wall — Jira, Confluence, internal wikis, enterprise dashboards — it's stuck.
+
+ContextPortal sits between your AI agent and the web. When the agent needs a protected page, ContextPortal uses *your* existing browser session to grab it, strips out all the noise, and hands back clean Markdown. The agent gets context. It never gets your cookies.
+
+> 🍪 *Agent: "Can I have your cookies?"*  
+> 🚫 *ContextPortal: "No. Here's the page."*
+
+## Install
+
+```bash
+uv tool install contextportal
+```
+
+## Setup
+
+```bash
+# Log into your private sites (once)
+contextportal login
+
+# Test it
+contextportal fetch https://your-protected-site.com/docs
+```
+
+## Connect to your AI Agent
+
+```json
+{
+  "mcpServers": {
+    "context-portal": {
+      "command": "contextportal",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Works with **Cursor**, **Claude Desktop**, **Antigravity**, **VS Code**, and any MCP-compatible client.
+
+## Learn More
+
+- 📖 [Full Documentation](https://github.com/NavadeepDj/ContextPortal)
+- 🔐 [Security Model](https://github.com/NavadeepDj/ContextPortal/blob/main/docs/security-and-automation-philosophy.md)
+- 🗺️ [Product Roadmap](https://github.com/NavadeepDj/ContextPortal/blob/main/PRODUCT_ROADMAP.md)

contextportal-0.1.0/README.md

@@ -0,0 +1,47 @@
+# 🔑 ContextPortal
+
+> **Give your AI agent access to authenticated web pages — without giving it your credentials.**
+
+Your AI agent can fetch any public webpage. But the moment it hits a login wall — Jira, Confluence, internal wikis, enterprise dashboards — it's stuck.
+
+ContextPortal sits between your AI agent and the web. When the agent needs a protected page, ContextPortal uses *your* existing browser session to grab it, strips out all the noise, and hands back clean Markdown. The agent gets context. It never gets your cookies.
+
+> 🍪 *Agent: "Can I have your cookies?"*  
+> 🚫 *ContextPortal: "No. Here's the page."*
+
+## Install
+
+```bash
+uv tool install contextportal
+```
+
+## Setup
+
+```bash
+# Log into your private sites (once)
+contextportal login
+
+# Test it
+contextportal fetch https://your-protected-site.com/docs
+```
+
+## Connect to your AI Agent
+
+```json
+{
+  "mcpServers": {
+    "context-portal": {
+      "command": "contextportal",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Works with **Cursor**, **Claude Desktop**, **Antigravity**, **VS Code**, and any MCP-compatible client.
+
+## Learn More
+
+- 📖 [Full Documentation](https://github.com/NavadeepDj/ContextPortal)
+- 🔐 [Security Model](https://github.com/NavadeepDj/ContextPortal/blob/main/docs/security-and-automation-philosophy.md)
+- 🗺️ [Product Roadmap](https://github.com/NavadeepDj/ContextPortal/blob/main/PRODUCT_ROADMAP.md)

contextportal-0.1.0/app/__init__.py

@@ -0,0 +1 @@
+"""ContextPortal backend application package."""

contextportal-0.1.0/app/cli.py

@@ -0,0 +1,121 @@
+import argparse
+import sys
+import asyncio
+from typing import Optional
+
+def run_mcp() -> None:
+    """Run the ContextPortal MCP server."""
+    from app.mcp.server import main as mcp_main
+    mcp_main()
+
+def run_login(start_url: Optional[str] = None) -> None:
+    """Launch persistent browser for manual login and session seeding."""
+    from playwright.sync_api import sync_playwright
+    import time
+    from pathlib import Path
+    
+    # Use global profile directory so sessions persist no matter where the CLI is run
+    profile_dir = Path.home() / ".contextportal" / "playwright_profile"
+    print(f"Using persistent profile at: {profile_dir}")
+    print("A browser window will now open.")
+    print("1. Navigate to the websites you want your AI agent to access.")
+    print("2. Log in manually (solve captchas, use SSO, etc.).")
+    print("3. Close the browser window when you are finished.")
+    print("\nLaunching browser...\n")
+    
+    with sync_playwright() as p:
+        # We launch headful (headless=False) so the user can interact
+        browser_context = p.chromium.launch_persistent_context(
+            user_data_dir=str(profile_dir),
+            headless=False,
+            channel="chrome",  # ADR-003: Transparent automation
+            args=["--disable-blink-features=AutomationControlled"]
+        )
+        
+        page = browser_context.pages[0] if browser_context.pages else browser_context.new_page()
+        
+        if start_url:
+            print(f"Navigating to {start_url}...")
+            page.goto(start_url)
+        else:
+            page.goto("about:blank")
+            
+        print("\nWaiting for you to close the browser window...")
+        print("Your session will be saved automatically.")
+        
+        # Keep process alive until user closes the context/browser
+        try:
+            while browser_context.pages:
+                time.sleep(1)
+        except Exception:
+            pass
+            
+    print("\nBrowser closed. Session saved successfully!")
+    print("You can now ask your AI agent to fetch authenticated resources.")
+
+def run_fetch(url: str) -> None:
+    """Fetch a URL directly from the CLI (useful for testing without an agent)."""
+    from app.core.retriever import get_context
+    
+    print(f"Fetching context for: {url}\n")
+    
+    async def _do_fetch():
+        result = await get_context(url)
+        if not result:
+            print("Error: Could not retrieve content.")
+            sys.exit(1)
+            
+        print("="*80)
+        print(f"Title: {result.title}")
+        print(f"Retrieval Method: {result.retrieval_method} (Authenticated: {result.authenticated})")
+        print("="*80)
+        print(result.content)
+        
+    asyncio.run(_do_fetch())
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="ContextPortal — The authenticated fetch layer for AI agents."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    
+    # MCP Server Command
+    subparsers.add_parser(
+        "mcp", 
+        help="Start the Model Context Protocol (MCP) server over STDIO."
+    )
+    
+    # Login Command
+    login_parser = subparsers.add_parser(
+        "login", 
+        help="Open a browser to manually authenticate and save your session."
+    )
+    login_parser.add_argument(
+        "--url", 
+        type=str, 
+        help="Optional starting URL to open for login (e.g., https://github.com/login)."
+    )
+    
+    # Fetch Command
+    fetch_parser = subparsers.add_parser(
+        "fetch", 
+        help="Test retrieval of a URL directly from the CLI."
+    )
+    fetch_parser.add_argument(
+        "url", 
+        type=str, 
+        help="The URL to fetch."
+    )
+    
+    args = parser.parse_args()
+    
+    if args.command == "mcp":
+        run_mcp()
+    elif args.command == "login":
+        run_login(args.url)
+    elif args.command == "fetch":
+        run_fetch(args.url)
+
+if __name__ == "__main__":
+    main()
+

contextportal-0.1.0/app/config.py

@@ -0,0 +1,9 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    app_name: str = "ContextPortal"
+    redis_url: str = "redis://localhost:6379"
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+settings = Settings()

contextportal-0.1.0/app/core/__init__.py

@@ -0,0 +1 @@
+# Core package

contextportal-0.1.0/app/core/retriever.py

@@ -0,0 +1,234 @@
+import asyncio
+import time
+import httpx
+from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeoutError
+from bs4 import BeautifulSoup
+from readability import Document
+import markdownify
+from pydantic import BaseModel
+from typing import Optional, Tuple
+
+class ContextResult(BaseModel):
+    url: str
+    title: Optional[str] = None
+    content: str
+    content_type: str = "text/markdown"
+    retrieval_method: str
+    authenticated: bool
+
+async def extract_markdown(html: str) -> Tuple[str, str]:
+    """Extracts main content from HTML and converts it to Markdown. Returns (markdown, title)."""
+    doc = Document(html)
+    title = doc.title()
+    main_html = doc.summary()
+    soup = BeautifulSoup(main_html, "lxml")
+    md_content = markdownify.markdownify(
+        str(soup), 
+        heading_style="ATX", 
+        strip=['script', 'style']
+    )
+    md_content = "\n".join([line for line in md_content.splitlines() if line.strip() or line == ""])
+    return md_content.strip(), title
+
+USER_AGENT = "ContextPortal/0.1.0 (+https://github.com/NavadeepDj/ContextPortal)"
+
+async def fetch_public(url: str) -> ContextResult | None:
+    """Attempts to fetch the URL normally. Returns ContextResult if successful and not blocked, else None."""
+    headers = {"User-Agent": USER_AGENT}
+    try:
+        async with httpx.AsyncClient(headers=headers, follow_redirects=True, timeout=10.0) as client:
+            response = await client.get(url)
+            
+            if response.status_code in (401, 403):
+                print("Public fetch hit 401/403.")
+                return None
+                
+            response.raise_for_status()
+            
+            final_url = str(response.url).lower()
+            if "login" in final_url or "signin" in final_url or "auth" in final_url:
+                print(f"Public fetch redirected to auth page: {final_url}")
+                return None
+            
+            content_type = response.headers.get("content-type", "")
+            if "text/html" not in content_type:
+                return ContextResult(
+                    url=final_url,
+                    title=None,
+                    content=response.text,
+                    content_type=content_type,
+                    retrieval_method="http",
+                    authenticated=False
+                )
+                
+            md, title = await extract_markdown(response.text)
+            
+            if len(md.strip()) < 100:
+                print("Public fetch returned virtually empty content (likely an SPA shell).")
+                return None
+                
+            return ContextResult(
+                url=final_url,
+                title=title,
+                content=md,
+                content_type="text/markdown",
+                retrieval_method="http",
+                authenticated=False
+            )
+    except Exception as e:
+        print(f"Public fetch failed: {e}")
+        return None
+
+def _is_on_target_content(page, target_url: str) -> bool:
+    """Check if the page has navigated to (or near) the target URL's domain/path."""
+    from urllib.parse import urlparse
+    current = urlparse(page.url)
+    target = urlparse(target_url)
+    # Consider it "on target" if the domain matches the target domain
+    # and the URL no longer looks like a login/auth/access page.
+    current_url_lower = page.url.lower()
+    auth_indicators = ['login', 'signin', 'sign-in', 'auth', '/access']
+    is_auth_page = any(indicator in current_url_lower for indicator in auth_indicators)
+    return current.netloc == target.netloc and not is_auth_page
+
+
+def _fetch_authenticated_sync(url: str) -> ContextResult:
+    """
+    Sync function that runs Playwright in a thread.
+    Uses sync_api to avoid the Windows asyncio subprocess bug.
+    
+    Handles OAuth popup flows (e.g. Google Sign-In) by polling the
+    main page's URL rather than watching for DOM changes on the page,
+    since OAuth opens new windows that we can't inspect.
+    """
+    # Use a deterministic global directory for the user profile so it persists across different CWDs
+    from pathlib import Path
+    user_data_dir = str(Path.home() / ".contextportal" / "playwright_profile")
+    
+    with sync_playwright() as p:
+        browser_context = p.chromium.launch_persistent_context(
+            user_data_dir,
+            headless=False,
+            channel="chrome",
+            viewport={"width": 1280, "height": 800}
+        )
+        
+        page = browser_context.new_page()
+        
+        try:
+            print(f"Navigating to {url}...")
+            page.goto(url, wait_until="domcontentloaded")
+            
+            try:
+                page.wait_for_load_state("networkidle", timeout=5000)
+            except PlaywrightTimeoutError:
+                pass
+            
+            # Detect if we landed on a login/auth page
+            current_url_lower = page.url.lower()
+            auth_indicators = ['login', 'signin', 'sign-in', 'auth', '/access']
+            has_password_field = page.evaluate(
+                '() => !!document.querySelector(\'input[type="password"]\')'
+            )
+            is_login_page = has_password_field or any(
+                indicator in current_url_lower for indicator in auth_indicators
+            )
+            
+            if is_login_page:
+                print("Authentication required. Please log in using the opened browser window.")
+                print("This supports OAuth popups (Google, SSO, etc.) — complete login in any window that opens.")
+                print("Waiting for you to complete login (up to 5 minutes)...")
+                
+                # Poll-based approach: check every 2 seconds if the main page
+                # has navigated back to the target domain after auth completion.
+                # This works with OAuth popups, SSO redirects, and multi-step flows
+                # where the auth happens in a separate window.
+                login_timeout_seconds = 300
+                poll_interval_seconds = 2
+                elapsed = 0
+                login_succeeded = False
+                
+                while elapsed < login_timeout_seconds:
+                    time.sleep(poll_interval_seconds)
+                    elapsed += poll_interval_seconds
+                    
+                    if _is_on_target_content(page, url):
+                        print("Login detected! Page has returned to target domain.")
+                        login_succeeded = True
+                        break
+                
+                if not login_succeeded:
+                    # One final attempt: navigate back to the target URL.
+                    # The browser context may now have valid session cookies
+                    # even if the page itself didn't redirect back.
+                    print("Login wait period ended. Attempting to navigate to the target resource...")
+                    page.goto(url, wait_until="domcontentloaded")
+                    try:
+                        page.wait_for_load_state("networkidle", timeout=10000)
+                    except PlaywrightTimeoutError:
+                        pass
+                    
+                    if not _is_on_target_content(page, url):
+                        raise RuntimeError(
+                            "Authentication timed out. Could not access the target resource. "
+                            "Please try again and complete the login within 5 minutes."
+                        )
+                
+                # Wait for the page to fully settle after auth redirect
+                try:
+                    page.wait_for_load_state("networkidle", timeout=10000)
+                except PlaywrightTimeoutError:
+                    pass
+                
+                # If we're on target domain but not the exact target URL, navigate there
+                if url not in page.url:
+                    print(f"Redirecting to target resource: {url}")
+                    page.goto(url, wait_until="domcontentloaded")
+                    try:
+                        page.wait_for_load_state("networkidle", timeout=10000)
+                    except PlaywrightTimeoutError:
+                        pass
+                    
+            print("Extracting content...")
+            html_content = page.content()
+            final_url = page.url
+            
+            # Extract markdown synchronously here since we're in a thread
+            doc = Document(html_content)
+            title = doc.title()
+            main_html = doc.summary()
+            soup = BeautifulSoup(main_html, "lxml")
+            md_content = markdownify.markdownify(
+                str(soup), 
+                heading_style="ATX", 
+                strip=['script', 'style']
+            )
+            md_content = "\n".join([line for line in md_content.splitlines() if line.strip() or line == ""])
+            
+            return ContextResult(
+                url=final_url,
+                title=title,
+                content=md_content.strip(),
+                content_type="text/markdown",
+                retrieval_method="browser",
+                authenticated=True
+            )
+            
+        finally:
+            browser_context.close()
+
+async def fetch_authenticated(url: str) -> ContextResult:
+    """Runs Playwright in a background thread to avoid Windows asyncio issues."""
+    return await asyncio.to_thread(_fetch_authenticated_sync, url)
+
+async def get_context(url: str) -> ContextResult:
+    """Main entrypoint: tries public fetch, falls back to authenticated fetch."""
+    print(f"Attempting normal public fetch for: {url}")
+    public_result = await fetch_public(url)
+    
+    if public_result:
+        print("Successfully retrieved publicly.")
+        return public_result
+        
+    print("Public fetch failed or requires authentication. Falling back to authorized session...")
+    return await fetch_authenticated(url)

contextportal-0.1.0/app/core/security.py

@@ -0,0 +1,41 @@
+import ipaddress
+from urllib.parse import urlparse
+
+def validate_url_policy(url: str) -> None:
+    """
+    Validates that a URL is safe to fetch.
+    Rejects non-HTTP(S) schemes, localhost, and private/internal IP ranges.
+    Raises ValueError if the URL violates the policy.
+    """
+    if not url:
+        raise ValueError("URL cannot be empty")
+
+    parsed = urlparse(url)
+    
+    # 1. Scheme Validation
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"Invalid scheme '{parsed.scheme}'. Only http and https are allowed.")
+        
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError("Invalid URL: missing hostname")
+
+    # 2. Block explicitly named localhosts
+    if hostname.lower() in ("localhost", "localhost.localdomain"):
+        raise ValueError("Access to localhost is forbidden by security policy")
+
+    # 3. IP Address Validation (block private/loopback/link-local)
+    try:
+        # Check if the hostname is directly an IP address
+        # Strip brackets for IPv6 compatibility if present
+        clean_hostname = hostname.strip("[]")
+        ip = ipaddress.ip_address(clean_hostname)
+        if ip.is_loopback or ip.is_private or ip.is_link_local or ip.is_multicast or ip.is_unspecified:
+            raise ValueError(f"Access to internal/private IP ({hostname}) is forbidden by security policy")
+    except ValueError as e:
+        # Not an IP address string.
+        # Note: If a custom exception is raised from ipaddress parsing, we catch it.
+        # We re-raise our own ValueError if we blocked it inside the try block.
+        if "forbidden by security policy" in str(e):
+            raise
+

contextportal-0.1.0/app/main.py

@@ -0,0 +1,32 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import PlainTextResponse
+from pydantic import HttpUrl
+
+from app.config import settings
+from app.redis import check_redis_connection
+from app.core.retriever import get_context
+
+app = FastAPI(title=settings.app_name)
+
+@app.get("/health")
+async def health_check():
+    redis_connected = await check_redis_connection()
+    return {
+        "status": "ok",
+        "redis": "connected" if redis_connected else "disconnected"
+    }
+
+@app.get("/c", response_class=PlainTextResponse)
+async def fetch_context(url: HttpUrl):
+    """
+    MVP Endpoint: Agent requests a URL. 
+    ContextPortal retrieves it (publicly or via authorized browser session)
+    and returns clean Markdown.
+    """
+    try:
+        result = await get_context(str(url))
+        if not result:
+            raise HTTPException(status_code=404, detail="Content could not be retrieved")
+        return result.content
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

contextportal-0.1.0/app/mcp/server.py

@@ -0,0 +1,50 @@
+import asyncio
+from mcp.server.mcpserver import MCPServer
+import mcp.types as types
+from app.core.security import validate_url_policy
+from app.core.retriever import get_context
+
+# Initialize the MCP Server
+mcp = MCPServer("ContextPortal")
+
+@mcp.tool()
+async def fetch_context(url: str) -> str:
+    """Fetch context from a given URL.
+    Can retrieve content from authenticated/protected enterprise portals using the user's secure browser session.
+    """
+    if not url:
+        raise ValueError("url is required")
+        
+    try:
+        # Enforce security policy before any retrieval
+        validate_url_policy(url)
+    except ValueError as e:
+        # Return a formatted error message so the agent understands why it was blocked.
+        # Returning a string prefixed with 'Error:' is a common pattern for LLMs
+        # when we can't directly override the is_error flag in the high-level API.
+        return f"Error: {str(e)}"
+        
+    # Delegate entirely to the retrieval orchestrator
+    try:
+        result = await get_context(url)
+        if not result:
+            return "Error: Could not retrieve content from the URL. The page might be empty, heavily obfuscated, or the auth session may have expired."
+            
+        formatted_response = (
+            f"# {result.title or 'Untitled Document'}\n"
+            f"**Source URL**: {result.url}\n"
+            f"**Retrieval Method**: {result.retrieval_method} (Authenticated: {result.authenticated})\n"
+            f"---\n\n"
+            f"{result.content}"
+        )
+        return formatted_response
+    except Exception as e:
+        return f"Error retrieving context: {str(e)}"
+
+def main():
+    """Run the MCP server over STDIO transport."""
+    # MCPServer provides a synchronous run method that handles asyncio internally
+    mcp.run()
+
+if __name__ == "__main__":
+    main()

contextportal-0.1.0/app/redis.py

@@ -0,0 +1,11 @@
+import redis.asyncio as redis
+from app.config import settings
+
+redis_client = redis.from_url(settings.redis_url, decode_responses=True)
+
+async def check_redis_connection() -> bool:
+    try:
+        await redis_client.ping()
+        return True
+    except redis.ConnectionError:
+        return False

contextportal-0.1.0/contextportal.egg-info/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: contextportal
+Version: 0.1.0
+Summary: The authenticated fetch layer for AI agents.
+Author: NavadeepDj
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/NavadeepDj/ContextPortal
+Project-URL: Repository, https://github.com/NavadeepDj/ContextPortal
+Project-URL: Issues, https://github.com/NavadeepDj/ContextPortal/issues
+Keywords: mcp,ai-agents,retrieval,browser-automation,context-proxy,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: redis[hiredis]>=5.0.0
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: playwright>=1.62.0
+Requires-Dist: readability-lxml>=0.8.4.1
+Requires-Dist: markdownify>=1.2.3
+Requires-Dist: mcp[cli]>=2.1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+# 🔑 ContextPortal
+
+> **Give your AI agent access to authenticated web pages — without giving it your credentials.**
+
+Your AI agent can fetch any public webpage. But the moment it hits a login wall — Jira, Confluence, internal wikis, enterprise dashboards — it's stuck.
+
+ContextPortal sits between your AI agent and the web. When the agent needs a protected page, ContextPortal uses *your* existing browser session to grab it, strips out all the noise, and hands back clean Markdown. The agent gets context. It never gets your cookies.
+
+> 🍪 *Agent: "Can I have your cookies?"*  
+> 🚫 *ContextPortal: "No. Here's the page."*
+
+## Install
+
+```bash
+uv tool install contextportal
+```
+
+## Setup
+
+```bash
+# Log into your private sites (once)
+contextportal login
+
+# Test it
+contextportal fetch https://your-protected-site.com/docs
+```
+
+## Connect to your AI Agent
+
+```json
+{
+  "mcpServers": {
+    "context-portal": {
+      "command": "contextportal",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Works with **Cursor**, **Claude Desktop**, **Antigravity**, **VS Code**, and any MCP-compatible client.
+
+## Learn More
+
+- 📖 [Full Documentation](https://github.com/NavadeepDj/ContextPortal)
+- 🔐 [Security Model](https://github.com/NavadeepDj/ContextPortal/blob/main/docs/security-and-automation-philosophy.md)
+- 🗺️ [Product Roadmap](https://github.com/NavadeepDj/ContextPortal/blob/main/PRODUCT_ROADMAP.md)

contextportal-0.1.0/contextportal.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+README.md
+pyproject.toml
+app/__init__.py
+app/cli.py
+app/config.py
+app/main.py
+app/redis.py
+app/core/__init__.py
+app/core/retriever.py
+app/core/security.py
+app/mcp/__init__.py
+app/mcp/server.py
+contextportal.egg-info/PKG-INFO
+contextportal.egg-info/SOURCES.txt
+contextportal.egg-info/dependency_links.txt
+contextportal.egg-info/entry_points.txt
+contextportal.egg-info/requires.txt
+contextportal.egg-info/top_level.txt
+tests/test_api.py
+tests/test_health.py
+tests/test_mcp.py
+tests/test_retriever.py
+tests/test_security.py

contextportal-0.1.0/contextportal.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

contextportal-0.1.0/contextportal.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+contextportal = app.cli:main

contextportal-0.1.0/contextportal.egg-info/requires.txt

@@ -0,0 +1,17 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+redis[hiredis]>=5.0.0
+pydantic-settings>=2.4.0
+httpx>=0.27.0
+playwright>=1.62.0
+readability-lxml>=0.8.4.1
+markdownify>=1.2.3
+mcp[cli]>=2.1.1
+
+[dev]
+pytest>=8.0.0
+pytest-asyncio>=0.24.0
+pytest-cov>=5.0.0
+ruff>=0.6.0
+mypy>=1.11.0
+twine>=5.0.0

contextportal-0.1.0/contextportal.egg-info/top_level.txt

@@ -0,0 +1 @@
+app

contextportal-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "contextportal"
+version = "0.1.0"
+description = "The authenticated fetch layer for AI agents."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [
+    { name = "NavadeepDj" }
+]
+keywords = [
+    "mcp",
+    "ai-agents",
+    "retrieval",
+    "browser-automation",
+    "context-proxy",
+    "security"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "redis[hiredis]>=5.0.0",
+    "pydantic-settings>=2.4.0",
+    "httpx>=0.27.0",
+    "playwright>=1.62.0",
+    "readability-lxml>=0.8.4.1",
+    "markdownify>=1.2.3",
+    "mcp[cli]>=2.1.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/NavadeepDj/ContextPortal"
+Repository = "https://github.com/NavadeepDj/ContextPortal"
+Issues = "https://github.com/NavadeepDj/ContextPortal/issues"
+
+[project.scripts]
+contextportal = "app.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["app", "app.*"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.6.0",
+    "mypy>=1.11.0",
+    "twine>=5.0.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

contextportal-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

contextportal-0.1.0/tests/test_api.py

@@ -0,0 +1,44 @@
+import pytest
+from unittest.mock import patch
+from httpx import AsyncClient, ASGITransport
+from app.main import app
+from app.core.retriever import ContextResult
+
+
+@pytest.mark.asyncio
+@patch("app.main.get_context")
+async def test_fetch_context_endpoint_success(mock_get_context):
+    mock_get_context.return_value = ContextResult(
+        url="https://example.com/article",
+        title="Extracted Article Content",
+        content="# Extracted Article Content\n\nThis is sample markdown.",
+        retrieval_method="http",
+        authenticated=False,
+    )
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        response = await ac.get("/c?url=https://example.com/article")
+
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("text/plain")
+    assert response.text == "# Extracted Article Content\n\nThis is sample markdown."
+    mock_get_context.assert_called_once_with("https://example.com/article")
+
+
+@pytest.mark.asyncio
+async def test_fetch_context_endpoint_invalid_url():
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        response = await ac.get("/c?url=not-a-valid-url")
+
+    assert response.status_code == 422
+
+
+@pytest.mark.asyncio
+@patch("app.main.get_context")
+async def test_fetch_context_endpoint_error(mock_get_context):
+    mock_get_context.side_effect = Exception("Retrieval failed")
+
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        response = await ac.get("/c?url=https://example.com/fails")
+
+    assert response.status_code == 500
+    assert response.json()["detail"] == "Retrieval failed"

contextportal-0.1.0/tests/test_health.py

@@ -0,0 +1,12 @@
+import pytest
+from httpx import AsyncClient, ASGITransport
+from app.main import app
+
+@pytest.mark.asyncio
+async def test_health_check_redis_disconnected():
+    # Because we're not running redis in this basic unit test, it will probably report disconnected
+    # but the endpoint should still return 200 OK.
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        response = await ac.get("/health")
+    assert response.status_code == 200
+    assert response.json()["status"] == "ok"

contextportal-0.1.0/tests/test_mcp.py

@@ -0,0 +1,80 @@
+import pytest
+import asyncio
+from unittest.mock import patch
+from mcp.server.models import InitializationOptions
+from mcp.shared.memory import create_client_server_memory_streams
+from mcp.client.session import ClientSession
+from app.mcp.server import mcp
+
+from unittest.mock import patch, AsyncMock
+from app.core.retriever import ContextResult
+
+@pytest.fixture
+def mock_get_context():
+    with patch("app.mcp.server.get_context", new_callable=AsyncMock) as mock:
+        mock.return_value = ContextResult(
+            url="https://example.com/redirected",
+            title="Example Title",
+            content="# Mocked Content",
+            retrieval_method="http",
+            authenticated=False
+        )
+        yield mock
+
+@pytest.mark.asyncio
+async def test_mcp_fetch_context(mock_get_context):
+    # 1. Create in-memory streams for client and server communication
+    async with create_client_server_memory_streams() as (client_streams, server_streams):
+        # 2. Get the low-level Server instance from the MCPServer wrapper
+        server = mcp._lowlevel_server
+        
+        init_options = InitializationOptions(
+            server_name="ContextPortal",
+            server_version="0.1.0",
+            capabilities=server.get_capabilities(
+                notification_options=None,
+                experimental_capabilities={}
+            )
+        )
+        
+        # 3. Start the server run loop in a background task
+        server_task = asyncio.create_task(
+            server.run(server_streams[0], server_streams[1], init_options)
+        )
+        
+        try:
+            # 4. Create and initialize the client session
+            async with ClientSession(client_streams[0], client_streams[1]) as session:
+                await session.initialize()
+                
+                # 5. List tools and verify our tool is registered
+                tools_response = await session.list_tools()
+                assert len(tools_response.tools) == 1
+                assert tools_response.tools[0].name == "fetch_context"
+                
+                # 6. Call the tool and verify it delegates to get_context
+                result = await session.call_tool("fetch_context", {"url": "https://example.com"})
+                assert not result.is_error
+                assert len(result.content) == 1
+                assert result.content[0].type == "text"
+                assert "# Example Title" in result.content[0].text
+                assert "**Source URL**: https://example.com/redirected" in result.content[0].text
+                assert "**Retrieval Method**: http" in result.content[0].text
+                assert "# Mocked Content" in result.content[0].text
+                
+                mock_get_context.assert_called_once_with("https://example.com")
+                
+                # 7. Verify security policy enforcement over MCP
+                result_local = await session.call_tool("fetch_context", {"url": "http://localhost:8000"})
+                # We return the error as a readable string to the LLM
+                assert "Error: Access to localhost is forbidden by security policy" in result_local.content[0].text
+                
+                result_file = await session.call_tool("fetch_context", {"url": "file:///etc/passwd"})
+                assert "Error: Invalid scheme" in result_file.content[0].text
+        finally:
+            # Clean up the background server task
+            server_task.cancel()
+            try:
+                await server_task
+            except asyncio.CancelledError:
+                pass

contextportal-0.1.0/tests/test_retriever.py

@@ -0,0 +1,229 @@
+import pytest
+from unittest.mock import patch, MagicMock, PropertyMock
+from app.core.retriever import extract_markdown, fetch_public, get_context, fetch_authenticated, ContextResult
+
+
+@pytest.mark.asyncio
+async def test_extract_markdown():
+    html = """
+    <html>
+        <head><title>Test Document</title></head>
+        <body>
+            <script>console.log('Malicious or tracker script');</script>
+            <h1>Main Title</h1>
+            <p>This is a paragraph with <strong>bold</strong> text.</p>
+            <style>body { color: red; }</style>
+        </body>
+    </html>
+    """
+    md, title = await extract_markdown(html)
+    assert "# Main Title" in md
+    assert "This is a paragraph with **bold** text." in md
+    assert "Malicious or tracker script" not in md
+    assert "color: red;" not in md
+
+
+@pytest.mark.asyncio
+@patch("httpx.AsyncClient.get")
+async def test_fetch_public_success(mock_get):
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.url = "https://example.com/article"
+    mock_response.headers = {"content-type": "text/html; charset=utf-8"}
+    mock_response.text = "<html><body><h1>Sample Article</h1><p>Here is a detailed article with plenty of content to pass the minimum character count check.</p></body></html>"
+    mock_get.return_value = mock_response
+
+    result = await fetch_public("https://example.com/article")
+    assert result is not None
+    assert result.retrieval_method == "http"
+    assert "# Sample Article" in result.content
+
+
+@pytest.mark.asyncio
+@patch("httpx.AsyncClient.get")
+async def test_fetch_public_unauthorized_status(mock_get):
+    mock_response = MagicMock()
+    mock_response.status_code = 401
+    mock_get.return_value = mock_response
+
+    result = await fetch_public("https://example.com/protected")
+    assert result is None
+
+
+@pytest.mark.asyncio
+@patch("httpx.AsyncClient.get")
+async def test_fetch_public_forbidden_status(mock_get):
+    mock_response = MagicMock()
+    mock_response.status_code = 403
+    mock_get.return_value = mock_response
+
+    result = await fetch_public("https://example.com/forbidden")
+    assert result is None
+
+
+@pytest.mark.asyncio
+@patch("httpx.AsyncClient.get")
+async def test_fetch_public_auth_redirect(mock_get):
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.url = "https://example.com/login?redirect=/protected"
+    mock_response.headers = {"content-type": "text/html"}
+    mock_response.text = "<html><body><h1>Login</h1></body></html>"
+    mock_get.return_value = mock_response
+
+    result = await fetch_public("https://example.com/protected")
+    assert result is None
+
+
+@pytest.mark.asyncio
+@patch("httpx.AsyncClient.get")
+async def test_fetch_public_empty_spa_shell(mock_get):
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.url = "https://example.com/app"
+    mock_response.headers = {"content-type": "text/html"}
+    mock_response.text = "<html><body><div id='root'></div></body></html>"
+    mock_get.return_value = mock_response
+
+    result = await fetch_public("https://example.com/app")
+    assert result is None
+
+
+@pytest.mark.asyncio
+@patch("httpx.AsyncClient.get")
+async def test_fetch_public_non_html(mock_get):
+    mock_response = MagicMock()
+    mock_response.status_code = 200
+    mock_response.url = "https://example.com/data.json"
+    mock_response.headers = {"content-type": "application/json"}
+    mock_response.text = '{"status": "ok", "message": "hello"}'
+    mock_get.return_value = mock_response
+
+    result = await fetch_public("https://example.com/data.json")
+    assert result.content == '{"status": "ok", "message": "hello"}'
+
+
+@pytest.mark.asyncio
+@patch("httpx.AsyncClient.get")
+async def test_fetch_public_exception(mock_get):
+    mock_get.side_effect = Exception("Connection timed out")
+
+    result = await fetch_public("https://unreachable.example.com")
+    assert result is None
+
+
+@pytest.mark.asyncio
+@patch("app.core.retriever.fetch_public")
+@patch("app.core.retriever.fetch_authenticated")
+async def test_get_context_public_branch(mock_fetch_auth, mock_fetch_public):
+    from app.core.retriever import ContextResult
+    mock_fetch_public.return_value = ContextResult(url="https://example.com", title=None, content="# Public Markdown", retrieval_method="http", authenticated=False)
+
+    result = await get_context("https://example.com")
+    assert result.content == "# Public Markdown"
+    mock_fetch_public.assert_called_once_with("https://example.com")
+    mock_fetch_auth.assert_not_called()
+
+
+@pytest.mark.asyncio
+@patch("app.core.retriever.fetch_public")
+@patch("app.core.retriever.fetch_authenticated")
+async def test_get_context_fallback_to_authenticated(mock_fetch_auth, mock_fetch_public):
+    mock_fetch_public.return_value = None
+    mock_fetch_auth.return_value = ContextResult(url="https://example.com/protected", title=None, content="# Authenticated Context", retrieval_method="browser", authenticated=True)
+
+    result = await get_context("https://example.com/protected")
+    assert result.content == "# Authenticated Context"
+    mock_fetch_public.assert_called_once_with("https://example.com/protected")
+    mock_fetch_auth.assert_called_once_with("https://example.com/protected")
+
+
+@pytest.mark.asyncio
+@patch("app.core.retriever._fetch_authenticated_sync")
+async def test_fetch_authenticated_thread_delegation(mock_sync_fetch):
+    mock_sync_fetch.return_value = ContextResult(url="https://example.com/protected", title=None, content="# Auth Markdown", retrieval_method="browser", authenticated=True)
+    result = await fetch_authenticated("https://example.com/protected")
+    assert result.content == "# Auth Markdown"
+    mock_sync_fetch.assert_called_once_with("https://example.com/protected")
+
+
+@patch("app.core.retriever.sync_playwright")
+def test_fetch_authenticated_sync_already_authenticated(mock_sync_playwright):
+    from app.core.retriever import _fetch_authenticated_sync
+
+    mock_p = MagicMock()
+    mock_browser_context = MagicMock()
+    mock_page = MagicMock()
+
+    mock_sync_playwright.return_value.__enter__.return_value = mock_p
+    mock_p.chromium.launch_persistent_context.return_value = mock_browser_context
+    mock_browser_context.new_page.return_value = mock_page
+
+    # Not a login page — URL is the target domain, no auth indicators
+    mock_page.url = "https://example.com/dashboard"
+    mock_page.evaluate.return_value = False
+    mock_page.content.return_value = "<html><body><h1>Dashboard</h1><p>Authorized user info</p></body></html>"
+
+    result = _fetch_authenticated_sync("https://example.com/dashboard")
+
+    assert "# Dashboard" in result.content
+    assert "Authorized user info" in result.content
+    mock_browser_context.close.assert_called_once()
+
+
+@patch("app.core.retriever.time")
+@patch("app.core.retriever.sync_playwright")
+def test_fetch_authenticated_sync_with_login_flow(mock_sync_playwright, mock_time):
+    from app.core.retriever import _fetch_authenticated_sync
+
+    mock_p = MagicMock()
+    mock_browser_context = MagicMock()
+    mock_page = MagicMock()
+
+    mock_sync_playwright.return_value.__enter__.return_value = mock_p
+    mock_p.chromium.launch_persistent_context.return_value = mock_browser_context
+    mock_browser_context.new_page.return_value = mock_page
+
+    # Initially lands on a login/auth page
+    mock_page.evaluate.return_value = True
+    mock_page.content.return_value = "<html><body><h1>Protected Course</h1><p>Welcome student!</p></body></html>"
+
+    # Simulate: first poll still on auth page, second poll back on target
+    mock_page.url = "https://app.joinhandshake.com/access?auth=true"
+    url_sequence = [
+        "https://app.joinhandshake.com/access?auth=true",  # 1st poll — still on auth
+        "https://project-dynamo.learn.joinhandshake.com/introduction",  # 2nd poll — landed!
+    ]
+    type(mock_page).url = PropertyMock(side_effect=url_sequence + ["https://project-dynamo.learn.joinhandshake.com/introduction"] * 10)
+
+    result = _fetch_authenticated_sync("https://project-dynamo.learn.joinhandshake.com/introduction")
+
+    assert "# Protected Course" in result.content
+    assert "Welcome student!" in result.content
+    mock_browser_context.close.assert_called_once()
+
+
+@patch("app.core.retriever.time")
+@patch("app.core.retriever.sync_playwright")
+def test_fetch_authenticated_sync_timeout_raises_error(mock_sync_playwright, mock_time):
+    from app.core.retriever import _fetch_authenticated_sync
+
+    mock_p = MagicMock()
+    mock_browser_context = MagicMock()
+    mock_page = MagicMock()
+
+    mock_sync_playwright.return_value.__enter__.return_value = mock_p
+    mock_p.chromium.launch_persistent_context.return_value = mock_browser_context
+    mock_browser_context.new_page.return_value = mock_page
+
+    # Stuck on auth page forever
+    mock_page.evaluate.return_value = True
+    mock_page.url = "https://app.joinhandshake.com/access?auth=true"
+
+    with pytest.raises(RuntimeError, match="Authentication timed out"):
+        _fetch_authenticated_sync("https://project-dynamo.learn.joinhandshake.com/introduction")
+
+    mock_browser_context.close.assert_called_once()
+
+
+

contextportal-0.1.0/tests/test_security.py

@@ -0,0 +1,49 @@
+import pytest
+from app.core.security import validate_url_policy
+
+def test_validate_url_policy_allowed():
+    # Public URLs should pass
+    validate_url_policy("https://example.com")
+    validate_url_policy("http://public-api.com/data")
+    validate_url_policy("https://project-dynamo.learn.joinhandshake.com/introduction")
+
+def test_validate_url_policy_rejected_schemes():
+    # Only http and https are allowed
+    with pytest.raises(ValueError, match="Invalid scheme"):
+        validate_url_policy("file:///etc/passwd")
+    
+    with pytest.raises(ValueError, match="Invalid scheme"):
+        validate_url_policy("javascript:alert(1)")
+        
+    with pytest.raises(ValueError, match="Invalid scheme"):
+        validate_url_policy("data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==")
+        
+    with pytest.raises(ValueError, match="Invalid scheme"):
+        validate_url_policy("ftp://example.com/file")
+
+def test_validate_url_policy_rejected_localhost():
+    # Localhost strings are blocked
+    with pytest.raises(ValueError, match="forbidden by security policy"):
+        validate_url_policy("http://localhost:8000/api")
+        
+    with pytest.raises(ValueError, match="forbidden by security policy"):
+        validate_url_policy("https://localhost.localdomain")
+        
+    # Localhost loopback IPs are blocked
+    with pytest.raises(ValueError, match="forbidden by security policy"):
+        validate_url_policy("https://127.0.0.1")
+        
+    with pytest.raises(ValueError, match="forbidden by security policy"):
+        validate_url_policy("http://[::1]/")
+
+def test_validate_url_policy_rejected_private_ips():
+    # RFC 1918 private networks are blocked
+    with pytest.raises(ValueError, match="forbidden by security policy"):
+        validate_url_policy("http://192.168.1.1/admin")
+        
+    with pytest.raises(ValueError, match="forbidden by security policy"):
+        validate_url_policy("http://10.0.0.5")
+        
+    with pytest.raises(ValueError, match="forbidden by security policy"):
+        validate_url_policy("https://172.16.0.100")
+