Metadata-Version: 2.4
Name: idea-vault-gateway
Version: 0.1.0
Summary: Local MCP gateway to Gemini (grounded search) and Perplexity Sonar.
Author: Tomasz Turczynski
License: MIT
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# idea-vault-gateway

Local MCP server that proxies tool calls to Gemini (with `google_search` grounding) and Perplexity Sonar. Designed to bypass the Bash-tool timeout that affects long-running research scripts in Claude Code.

## Install

### Via Homebrew (recommended once published)

```bash
brew tap turek/idea-vault-gateway
brew install idea-vault-gateway
```

### From source (works today)

```bash
uv tool install git+https://github.com/turek/idea-vault-mcp
```

Drops `idea-vault-gateway` onto your `$PATH` via `~/.local/bin`. Run `uv tool update-shell` once if the binary isn't found.

## Setup (3 commands)

```bash
# 1. Save your API keys (interactive prompt; writes ~/.config/idea-vault-gateway/.env, mode 0600)
idea-vault-gateway init

# 2. Register with Claude Code
claude mcp add idea-vault-gateway idea-vault-gateway mcp --scope user

# 3. Restart Claude Code, then verify
#    /mcp   → should list `idea-vault-gateway` with two tools
```

That's it. No JSON editing, no manual config files.

### Power-user alternative: keys in the MCP config

If you'd rather skip the `.env` file (e.g. for CI, or to keep config in a single place), pass keys via the registration command:

```bash
claude mcp add idea-vault-gateway idea-vault-gateway mcp --scope user \
  --env GEMINI_API_KEY=... \
  --env PERPLEXITY_API_KEY=...
```

Env vars in the MCP config take precedence over the `.env` file. Optional knobs: `GEMINI_MODEL` (default `gemini-2.5-pro`), `PERPLEXITY_MODEL` (default `sonar-pro`).

## Tools

- `gemini_research(prompt, model?)` — Gemini with grounded search; retries on 429/503, falls back to `gemini-2.5-flash`.
- `perplexity_research(prompt, model?, deep?)` — Perplexity Sonar; `deep=true` switches to `sonar-deep-research`.

## Develop locally

```bash
uv venv && uv pip install -e .
idea-vault-gateway mcp
```

## Releasing (maintainer notes)

Distribution is via a personal Homebrew tap at `turek/homebrew-idea-vault-gateway`. The formula source lives in this repo at `homebrew/Formula/idea-vault-gateway.rb` for reference, but Homebrew reads it from the tap repo.

Per-release flow:

1. **Bump version** in `pyproject.toml` and `src/idea_vault_gateway/__init__.py`. Commit.
2. **Tag and push:**
   ```bash
   git tag v0.1.0 && git push origin v0.1.0
   ```
   GitHub auto-creates the tarball at `https://github.com/turek/idea-vault-mcp/archive/refs/tags/v0.1.0.tar.gz`. No manual tarballing.
3. **Publish to PyPI** (one-time setup: `uv` reads `UV_PUBLISH_TOKEN` or `~/.pypirc`):
   ```bash
   uv build && uv publish
   ```
4. **Compute the tarball SHA:**
   ```bash
   curl -sL https://github.com/turek/idea-vault-mcp/archive/refs/tags/v0.1.0.tar.gz | shasum -a 256
   ```
5. **Update the tap repo** (`turek/homebrew-idea-vault-gateway`): bump `version`, `url`, and `sha256` in `Formula/idea-vault-gateway.rb`. Commit, push.
6. Users get the new version on their next `brew update && brew upgrade idea-vault-gateway`.

First-time tap repo setup (do this once):

```bash
gh repo create turek/homebrew-idea-vault-gateway --public --clone
cd homebrew-idea-vault-gateway
mkdir Formula
cp ../idea-vault-mcp/homebrew/Formula/idea-vault-gateway.rb Formula/
# fill in the real sha256 from step 4 above
git add . && git commit -m "Add idea-vault-gateway formula" && git push
```
