# GBS Tools MongoDB Plan – What Actually Works

**Date**: 2026-03-17  
**Goal**: Get GBS tools working on EC2 (UPC Query Agent) with no more back-and-forth.

---

## The Situation

| Approach | Works locally? | Works on EC2? | Why |
|----------|----------------|---------------|-----|
| **PyMongo** | Yes | No | Python’s SSL/OpenSSL fails against MongoDB Atlas in that environment (`_ssl.c:3036`). certifi + `tlsAllowInvalidCertificates` have not fixed it. |
| **mongosh** (subprocess) | Yes | Yes | mongosh brings its own SSL stack; it doesn’t use Python’s OpenSSL. |

**Conclusion**: Use mongosh. It works where it matters.

---

## Why PyMongo Fails (and When It Might Be Revisitible)

- The failure happens in Python’s SSL layer during the TLS handshake with Atlas.
- Likely causes: older OpenSSL, missing/incomplete CA certs, or environment-specific restrictions.
- Possible future fixes: newer Python, updated certifi/OpenSSL, or different TLS options. Not worth blocking on now.
- We already have a diagnostic script (`scripts/mongodb_connection_experiment.py`) to test PyMongo vs mongosh. You can run it on EC2 once to capture the exact error for later debugging.

---

## The Plan: mongosh on EC2

**Single path forward:**

1. **Keep** the current mongosh-based `mongodb_utils.py`.
2. **Install mongosh** on EC2 as part of deployment.
3. **Add** `PT_RESEARCH_DATABASE_URI` (and optionally `PT_RESEARCH_TLS_SKIP_VERIFY=1`) to `.env` on EC2.
4. **Document** this in deploy guides and runbooks.

---

## EC2 Setup Checklist

When deploying the MCP server to EC2 (for the UPC Query Agent):

### 1. Install mongosh

**Amazon Linux 2 / Amazon Linux 2023 / RHEL:**

```bash
# Try package manager first
sudo yum install -y mongodb-mongosh

# If that fails (no repo), add MongoDB repo then retry:
# See install_mongosh.py or scripts/install-mongosh.sh for full repo setup
```

**Ubuntu/Debian:**

```bash
sudo apt install -y mongodb-mongosh
```

**Verify:**

```bash
mongosh --version
```

### 2. Environment variables

In `.env` on EC2:

```bash
PT_RESEARCH_DATABASE_URI=mongodb+srv://user:pass@cluster.mongodb.net/dbname
```

If SSL verification still fails:

```bash
PT_RESEARCH_TLS_SKIP_VERIFY=1
```

### 3. Install the MCP package

```bash
pip install point-topic-mcp
# or
uv add point-topic-mcp
```

### 4. Optional: run diagnostic once

```bash
cd /path/to/point-topic-mcp
uv run python scripts/mongodb_connection_experiment.py
```

This prints which methods work (PyMongo vs mongosh) and the exact error if PyMongo fails. Useful for future debugging.

---

## What’s Already in Place

- `mongodb_utils.py` – mongosh-based implementation.
- `gbs_tools.py` – uses `mongodb_utils`.
- `point-topic-mcp-install-mongosh` – CLI to install mongosh (can use on EC2).
- `scripts/install-mongosh.sh` – same, for shell scripts / CI.

**You don’t need to change any of this.** Just install mongosh on EC2 and configure `.env`.

---

## Done When

1. mongosh is installed on the EC2 instance where the UPC Query Agent runs.
2. `PT_RESEARCH_DATABASE_URI` (and `PT_RESEARCH_TLS_SKIP_VERIFY=1` if needed) is in `.env`.
3. GBS tools (`list_operators`, `get_gbs_status`, `add_statistic`, `create_source`) work when called from the UPC Query Agent.

---

## If You Need to Add mongosh to a Deploy Script

If you have an EC2/bootstrap script, add:

```bash
# GBS tools require mongosh for MongoDB Atlas connectivity
sudo yum install -y mongodb-mongosh   # Amazon Linux / RHEL
# OR
sudo apt install -y mongodb-mongosh  # Ubuntu/Debian
```

One line; no Python changes required.
