Metadata-Version: 2.4
Name: contextportal
Version: 0.3.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
Requires-Dist: packaging>=23.0
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:** *"I can't read this ticket. It's behind an SSO login wall. Please take 5 screenshots."*  
> 👤 **You:** *"No way. Why am I doing homework for an AI?"*  
> 🔑 **ContextPortal:** *"Say less. Log in once in your browser; your agent retrieves the page forever."*

### 🏛️ The 4 Pillars
- 🛑 **Stop feeding your AI screenshots.** Copy-paste is not an agent architecture.
- 🔁 **Authenticate once. Retrieve context continuously.** Log in once; your agent reads forever.
- 🔐 **Your browser holds the session. Your agent gets the page. Zero cookies leaked.**
- 🎯 **Give your agent a retrieval tool, not a browser to operate.** Clean Markdown, zero DOM fragility.

## Install
## 🔌 Connect ContextPortal to your AI

ContextPortal works through the Model Context Protocol (MCP) and configures supported AI clients automatically.

```text
┌──────────────────────────────────────────────┐
│  Connect your agent                          │
│                                              │
│  $ contextportal setup                       │
│                                              │
│  ✓ MCP server                                │
│  ✓ Browser profile                           │
│  ✓ AI client                                 │
│                                              │
│  Ready.                                      │
└──────────────────────────────────────────────┘
```

Onboarding shouldn't feel like wrestling with JSON files and virtual environments.  
It's three steps: **Install ContextPortal → Connect your agent → Give it the URL.**

---

### Step 1: Install ContextPortal

```bash
uv tool install contextportal
```

## 🪄 Quick Setup (Auto-Config)
---

Configure your AI agent (Claude Desktop, Cursor, Antigravity) with a single command:
### Step 2: Connect your AI agent

```bash
contextportal setup
```

Verify your environment anytime:
That's it! ContextPortal scans your system, detects installed AI agent clients, creates a safety backup, and registers the MCP server automatically.

```bash
contextportal doctor
```
> 🩺 Run `contextportal doctor` anytime to audit your system health and client connections.

## 🔐 Log In (Once)
---

Log into your private sites in your local browser — your session is saved automatically:
### 🤖 Supported AI Clients

ContextPortal provides zero-friction automatic setup for major AI developer tools, plus a standard manual fallback:

| AI Client | Platform | Automatic Setup | Manual Config Path |
| :--- | :--- | :--- | :--- |
| **Cursor** | Win / Mac / Linux | `contextportal setup --client cursor` | `~/.cursor/mcp.json` |
| **Google Antigravity** | Win / Mac / Linux | `contextportal setup --client antigravity` | `~/.gemini/antigravity/mcp_config.json` |
| **Claude Desktop** | Win / Mac / Linux | `contextportal setup --client claude` | `%APPDATA%\Claude\` or `~/Library/Application Support/Claude/` |
| **VS Code (Cline / Roo / Copilot)** | Universal | Built-in MCP settings | `.vscode/mcp.json` or Extension settings |
| **Any Custom MCP Client** | Universal | STDIO transport | Standard JSON payload |

---

### Step 3: Log into your private sites (once)

```bash
contextportal login
```

Test it directly:
A clean browser opens. Log into your private tools — Jira, Confluence, internal wikis, GitHub enterprise, Handshake. Close the window when you're done. Your session stays locally on your machine.

```bash
contextportal fetch https://your-protected-site.com/docs
```
---

## 🔌 Manual MCP Configuration (Optional)
### 🎉 You're ready. Now just give your agent the URL.

In your AI chat (Cursor, Claude, Antigravity, etc.):

> *"Summarize the roadmap at https://internal.company.com/q3-roadmap"*

Your agent calls ContextPortal → ContextPortal retrieves the page through your authenticated session → clean, token-optimized Markdown comes back.

**No screenshots. No copy-pasting. You're done.**

---

### 🛠️ Manual Configuration Fallback (Optional)

If you prefer to configure manually:

```json
{
  "mcpServers": {
    "context-portal": {
      "command": "contextportal",
      "args": ["mcp"]
    }
  }
}
```

Works with **Cursor**, **Claude Desktop**, **Antigravity**, **VS Code**, and any MCP 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)
