Metadata-Version: 2.4
Name: vv-pilot-mcp
Version: 0.4.7
Summary: MCP server for QA database access and k8s logs
License: MIT
Requires-Python: >=3.11
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: pexpect>=4.9.0
Description-Content-Type: text/markdown

# vv-pilot-mcp

MCP server for accessing QA databases, k8s logs, and Kafka via Amazon Q / Copilot.

## Installation

### Option 1: uvx (no install required)

Add to your MCP config (`~/.aws/amazonq/mcp.json` or `.amazonq/mcp.json` in your workspace):

```json
{
  "mcpServers": {
    "qa-server": {
      "command": "uvx",
      "args": ["vv-pilot-mcp"],
      "timeout": 60000,
      "disabled": false
    }
  }
}
```

This auto-downloads and runs the server on demand. Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) installed.

### Option 2: pipx (global install)

```bash
pipx install vv-pilot-mcp
```

Then add to your MCP config:

```json
{
  "mcpServers": {
    "qa-server": {
      "command": "vv-pilot-mcp",
      "timeout": 60000,
      "disabled": false
    }
  }
}
```

To update later:

```bash
pipx upgrade vv-pilot-mcp
```

## First-Time Setup

On first use, the server will prompt you for:

1. **SSH password** — your jump host password
2. **DB jump host** — SSH alias for the DB jump host (e.g. `qa-psql-1.qa-new`)
3. **Vault forward host** — SSH alias for the vault tunnel (e.g. `vault-np-forward-new`)

All values are saved securely to `~/.config/qa-mcp/.env` (chmod 600) and reused automatically on subsequent sessions.

## Usage

### Database

1. Open Amazon Q chat and say: **"Connect to QA database"**
2. The server will:
   - SSH to the DB jump host (opens browser for OIDC approval on first session)
   - Start the vault forward tunnel
   - Open the Vault UI in your browser
3. Copy the vault token from your profile and paste it in chat
4. You're connected! Now ask things like:
   - "List all schemas"
   - "Find the latest visit from retrobranch1"
   - "Update discharge date for visit id 1234"

### Kafka

1. Say: **"Connect to Kafka"**
2. The server will SSH to the Kafka jump host and launch the kafka-utils container
3. Set your client (e.g. "Set client to retrobranch1")
4. Now ask things like:
   - "List all visit topics"
   - "Check connector status for retrobranch1-qa-retrobranch1iodine1-visit"
   - "Consume 5 messages from retrobranch1-qa-visit"
   - "List consumer groups"
   - "Restart the visit connector"

## Available Tools

### Database

| Tool | Description |
|------|-------------|
| `set_password` | Set SSH password (saved for future sessions) |
| `set_config` | Set any config value (saved for future sessions) |
| `connect_db_jump_host` | SSH to DB jump host |
| `start_vault_forward` | Start vault tunnel |
| `open_vault_ui` | Open vault UI in browser |
| `set_vault_token` | Set vault token from browser |
| `connect_database` | Get credentials and connect via psql |
| `query` | Run SQL query |
| `list_schemas` | List database schemas |
| `list_tables` | List tables in a schema |
| `describe_table` | Describe table columns |

### Kubernetes

| Tool | Description |
|------|-------------|
| `k8s_connect` | SSH to k8s jump host |
| `k8s_sso_login` | Run AWS SSO login |
| `k8s_sso_confirm` | Confirm SSO after browser approval |
| `k8s_pods` | List pods |
| `k8s_logs` | Get pod logs |
| `k8s_describe` | Describe a k8s resource |

### Kafka

| Tool | Description |
|------|-------------|
| `kafka_connect` | SSH to Kafka host and launch kafka-utils container |
| `kafka_set_client` | Set CLIENT env var (e.g. retrobranch1, imc1) |
| `kafka_exec` | Run any raw command in the container |
| `kafka_list_topics` | List topics (with optional grep filter) |
| `kafka_consume` | Consume messages from a topic (avro, bounded) |
| `kafka_produce` | Produce a message to a topic (may fail due to ACLs) |
| `kafka_consumer_groups` | List/describe/delete/reset consumer groups |
| `kafka_connector` | List/status/pause/resume/restart/delete connectors |

### General

| Tool | Description |
|------|-------------|
| `connection_status` | Check connection state |
| `disconnect` | Tear down all sessions |

## Configuration

All config is stored in `~/.config/qa-mcp/.env`:

```bash
QA_SSH_PASSWORD=<your-password>
QA_DB_JUMP_HOST=qa-psql-1.qa-new
QA_VAULT_JUMP_HOST=vault-np-forward-new
QA_VAULT_URL=https://localhost:18200
QA_VAULT_OIDC_ACCOUNT=you@iodinesoftware.com
QA_DEFAULT_CLUSTER=qa-cluster-1
QA_DEFAULT_DB=iodine
QA_DEFAULT_USER_TYPE=dba
```

You can also set these as environment variables to override the file.

## Prerequisites

- SSH config with aliases for your jump hosts
- Access to the QA environment (OIDC)
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (for Option 1) or [pipx](https://pipx.pypa.io/stable/installation/) (for Option 2)

## Development

```bash
git clone git@github.com:vijayveeramani/vv-pilot-mcp.git
cd vv-pilot-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Release Workflow

1. Bump version in `pyproject.toml`
2. Commit, tag, and push:
   ```bash
   git add -A && git commit -m "v0.x.0: description"
   git tag v0.x.0
   git push origin main --tags
   ```
3. Build and publish to PyPI:
   ```bash
   rm -rf dist/
   python -m build
   twine upload dist/*
   ```
