idea-vault-gateway 0.1.0

Local MCP gateway to Gemini (grounded search) and Perplexity Sonar.

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)

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

From source (works today)

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)

# 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:

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

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:

   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):

   uv build && uv publish
   

4. Compute the tarball SHA:

   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):

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