futuresearch 0.6.0__tar.gz

futuresearch-0.6.0/.claude/skills/deploy-mcp/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: deploy-mcp
+description: Deploy the FutureSearch MCP server to staging or production on GKE. Use when the user wants to deploy, redeploy, roll back, scale replicas, or check deployment status. Triggers on deploy, redeploy, staging, production, rollout, scale, replicas.
+---
+
+# Deploying the MCP Server
+
+## Quick Deploy
+
+### Staging (from main)
+
+```bash
+gh workflow run "Deploy MCP Server" -f branch=main -f deploy_staging=true
+```
+
+### Production (from main)
+
+```bash
+gh workflow run "Deploy MCP Server" -f branch=main -f deploy_production=true
+```
+
+### Both environments
+
+```bash
+gh workflow run "Deploy MCP Server" -f branch=main -f deploy_staging=true -f deploy_production=true
+```
+
+### From a feature branch
+
+```bash
+gh workflow run "Deploy MCP Server" -f branch=feat/my-branch -f deploy_staging=true
+```
+
+## Monitoring a Deploy
+
+```bash
+# Watch the workflow run
+gh run list --workflow="Deploy MCP Server" --limit 3
+gh run watch <run-id>
+
+# Check pod rollout
+kubectl rollout status deploy/futuresearch-mcp-staging -n futuresearch-mcp-staging --timeout=5m
+
+# Verify pods are running
+kubectl get pods -n futuresearch-mcp-staging -o wide
+```
+
+## How It Works
+
+The GitHub Actions workflow (`.github/workflows/deploy-mcp.yaml`) does:
+
+1. **Checks** — ruff lint + pytest on the target branch
+2. **Build & push** — Docker image to GAR, tagged with short SHA (+ `latest` on main)
+3. **Deploy** — Helm upgrade with layered values:
+   - `values.yaml` — base config
+   - `values.staging.yaml` — staging overrides (MCP_SERVER_URL, REDIS_DB, replicaCount, host)
+   - `values.secrets.staging.yaml` — SOPS-decrypted secrets (Supabase, API keys)
+
+The deploy uses `--atomic` so it auto-rolls back on failure.
+
+## Scaling Replicas
+
+### Via Helm values (persistent)
+
+Edit `futuresearch-mcp/deploy/chart/values.staging.yaml`:
+```yaml
+replicaCount: 2  # Change this
+```
+Commit, push, and redeploy.
+
+### Via kubectl (temporary, resets on next deploy)
+
+```bash
+# Staging
+kubectl scale deploy futuresearch-mcp-staging -n futuresearch-mcp-staging --replicas=3
+
+# Take offline
+kubectl scale deploy futuresearch-mcp-staging -n futuresearch-mcp-staging --replicas=0
+```
+
+## Environments
+
+| Environment | Namespace | Host | Redis DB |
+|---|---|---|---|
+| Staging | `futuresearch-mcp-staging` | `mcp-staging.everyrow.io` | 14 |
+| Production | `futuresearch-mcp` | `mcp.everyrow.io` | (default in values.yaml) |
+
+Both environments hit the **same production FutureSearch API** — there is no staging API.
+
+## Updating Secrets
+
+```bash
+# View current secrets
+sops -d futuresearch-mcp/deploy/chart/secrets.staging.enc.yaml
+
+# Update a value
+sops --set '["secrets"]["data"]["KEY_NAME"] "new-value"' futuresearch-mcp/deploy/chart/secrets.staging.enc.yaml
+```
+
+Commit the encrypted file and redeploy.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `.github/workflows/deploy-mcp.yaml` | CI/CD workflow (checks → build → deploy) |
+| `futuresearch-mcp/deploy/chart/values.yaml` | Base Helm values |
+| `futuresearch-mcp/deploy/chart/values.staging.yaml` | Staging overrides |
+| `futuresearch-mcp/deploy/chart/secrets.enc.yaml` | Production secrets (SOPS) |
+| `futuresearch-mcp/deploy/chart/secrets.staging.enc.yaml` | Staging secrets (SOPS) |
+| `futuresearch-mcp/deploy/Dockerfile` | Server container image |
+
+## Gotchas
+
+- **Branch protection on main**: Can't push directly — create a PR and merge first, then deploy from main.
+- **SOPS decryption requires GCP IAM**: Run `gcloud auth application-default login` if decryption fails.
+- **Concurrent deploys**: Workflow uses `cancel-in-progress: false` — if a deploy is running, the next one queues.
+- **Atomic rollback**: `--atomic` means a failed deploy auto-reverts to the previous release. Check `helm history` if this happens.

futuresearch-0.6.0/.claude/skills/run-mcp-local/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: run-mcp-local
+description: Run the FutureSearch HTTP MCP server locally with Docker Compose and optionally expose it via Cloudflare tunnel. Use when starting/stopping the local MCP server, debugging startup issues, connecting Claude.ai or Claude Desktop to a local instance, or checking server logs. Triggers on mcp local, mcp server, run mcp, mcp docker, mcp tunnel, cloudflare tunnel, mcp logs.
+---
+
+# Running the FutureSearch MCP Server Locally
+
+Two-container stack: **mcp-server** (FastAPI on :8000) and **redis** (on :6379), orchestrated by `futuresearch-mcp/deploy/docker-compose.yaml` with local overrides.
+
+## Pre-flight Checks
+
+**CRITICAL: Always check for stale processes on port 8000 before starting.**
+
+A leftover `futuresearch-mcp --no-auth` or similar process on the host will shadow the Docker container's port binding. All requests hit the stale process instead of the container — this can look like auth routes are broken, sheets tools are missing, etc.
+
+```bash
+# Check for anything on port 8000
+lsof -i :8000
+
+# Kill if needed
+lsof -ti :8000 | xargs kill -9
+```
+
+Also check Docker is running:
+```bash
+docker info --format '{{.ServerVersion}}' || colima start
+```
+
+## Quick Start
+
+```bash
+cd futuresearch-mcp/deploy
+
+REDIS_PASSWORD=testpass \
+MCP_SERVER_URL=http://localhost:8000 \
+  docker compose \
+    -f docker-compose.yaml \
+    -f docker-compose.local.yaml \
+  up -d --build
+```
+
+Verify: `curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health` should return `200`.
+
+### Optional env vars
+
+Pass these alongside `REDIS_PASSWORD` and `MCP_SERVER_URL`:
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `ENABLE_SHEETS_TOOLS` | `false` | Register Google Sheets tools |
+| `TRUST_PROXY_HEADERS` | `false` | Trust X-Forwarded-For (required behind tunnel) |
+| `EXTRA_ALLOWED_HOSTS` | (empty) | Extra hostnames for DNS rebinding allowlist |
+
+These are templated in `docker-compose.local.yaml` as `${VAR:-default}` — the container must be **recreated** (not just restarted) for env var changes to take effect.
+
+## Secrets
+
+The `.env` file at `futuresearch-mcp/deploy/.env` contains production secrets (Supabase, API keys, upload secret). It is already present and should NOT be committed or overwritten.
+
+`REDIS_PASSWORD` is intentionally NOT in `.env` — always pass it as an env var (`testpass` for local dev).
+
+### Worktrees
+
+The `.env` file is gitignored and won't exist in worktrees. Symlink it:
+
+```bash
+ln -s /Users/rafaelpoyiadzi/Documents/git/futuresearch-python/futuresearch-mcp/deploy/.env \
+      <worktree-path>/futuresearch-mcp/deploy/.env
+```
+
+## Exposing via Cloudflare Tunnel
+
+Required when testing with Claude.ai or Claude Desktop, which can't reach `localhost`.
+
+### Step 1: Kill stale tunnels and processes
+
+```bash
+pkill -f cloudflared 2>/dev/null
+rm -f /tmp/cf-tunnel.log
+lsof -ti :8000 | xargs kill -9 2>/dev/null
+```
+
+### Step 2: Start the tunnel
+
+```bash
+cloudflared tunnel --url http://localhost:8000 2>/tmp/cf-tunnel.log &
+sleep 6
+grep -oE 'https://[a-z0-9-]+\.trycloudflare\.com' /tmp/cf-tunnel.log | head -1
+```
+
+This prints a URL like `https://something-something.trycloudflare.com`.
+
+### Step 3: Start (or restart) the MCP server with the tunnel URL
+
+The server must know its public URL for OAuth redirects to work:
+
+```bash
+cd futuresearch-mcp/deploy
+
+REDIS_PASSWORD=testpass \
+MCP_SERVER_URL=https://something-something.trycloudflare.com \
+TRUST_PROXY_HEADERS=true \
+ENABLE_SHEETS_TOOLS=true \
+  docker compose \
+    -f docker-compose.yaml \
+    -f docker-compose.local.yaml \
+  up -d --build
+```
+
+Key: `MCP_SERVER_URL` must match the tunnel URL exactly, and `TRUST_PROXY_HEADERS=true` is required so the server trusts the forwarded headers from Cloudflare.
+
+### Step 4: Verify OAuth discovery works end-to-end
+
+```bash
+# Through the tunnel (what Claude.ai sees)
+curl -s https://<tunnel-url>/.well-known/oauth-authorization-server | python3 -m json.tool | head -5
+
+# Locally
+curl -s http://localhost:8000/.well-known/oauth-authorization-server | python3 -m json.tool | head -5
+```
+
+Both should return JSON with `issuer`, `authorization_endpoint`, etc. If local returns 404 but tunnel works (or vice versa), check for stale processes on port 8000.
+
+### Step 5: Connect clients
+
+**Claude.ai / Claude Desktop**: Use the tunnel URL as the MCP server URL in the client config.
+
+**Claude Code**: Add a project-scoped MCP server (writes to `.claude/settings.local.json` in the current dir, not the global config):
+
+```bash
+claude mcp add futuresearch --scope project --transport http <TUNNEL_URL>/mcp
+```
+
+Then restart Claude Code. Remove with `claude mcp remove futuresearch --scope project`.
+
+## Logs
+
+```bash
+# All logs
+docker logs deploy-mcp-server-1 -f
+
+# Filter for errors
+docker logs deploy-mcp-server-1 2>&1 | grep -iE "error|warn|401|500"
+
+# Check User-Agent strings (for widget/client detection work)
+docker logs deploy-mcp-server-1 2>&1 | grep "User-Agent"
+```
+
+## Teardown
+
+```bash
+cd futuresearch-mcp/deploy
+
+REDIS_PASSWORD=testpass MCP_SERVER_URL=http://localhost:8000 \
+  docker compose -f docker-compose.yaml -f docker-compose.local.yaml down
+```
+
+Kill the tunnel: `pkill -f cloudflared` or `kill %1` if it was backgrounded.
+
+## No-Auth Mode (without Docker)
+
+Run the server directly with `uv run` — no Docker needed. Useful for quick local testing with the MCP Inspector.
+
+**WARNING:** If you leave this running and later start the Docker stack, the local process will shadow Docker's port 8000. Always kill it first: `lsof -ti :8000 | xargs kill -9`
+
+### Prerequisites
+
+- Redis running on localhost:6379 (e.g. `docker run -d --name test-redis -p 6379:6379 redis:7-alpine`)
+- `FUTURESEARCH_API_KEY` (or legacy `FUTURESEARCH_API_KEY`) in `~/.claude/secrets/remote.env`
+
+### Start the server
+
+```bash
+cd futuresearch-mcp
+ALLOW_NO_AUTH=1 \
+UPLOAD_SECRET=$(python -c "import secrets; print(secrets.token_urlsafe(32))") \
+EXTRA_ALLOWED_HOSTS="host.docker.internal,localhost" \
+  bash scripts/run-no-auth.sh
+```
+
+### Connect with MCP Inspector
+
+1. Start the Inspector: `npx @modelcontextprotocol/inspector`
+2. Open the URL it prints (includes `MCP_PROXY_AUTH_TOKEN`)
+3. Settings:
+   - Transport: **Streamable HTTP**
+   - Mode: **Via Proxy**
+   - URL: `http://localhost:8000/mcp`
+   - Leave all OAuth fields **blank**
+4. Click **Connect**
+
+Note: Direct mode won't work (CORS). Auth mode won't work (Inspector v0.21.0 doesn't handle the OAuth flow). Use Via Proxy with no-auth.
+
+### Connect with SDK client
+
+```bash
+uv run python scripts/mcp_call.py list
+uv run python scripts/mcp_call.py call futuresearch_balance
+uv run python scripts/mcp_call.py call futuresearch_agent '{"params": {"task": "...", "data": [...]}}'
+```
+
+Note: `mcp_call.py` only works against `--no-auth` servers. It doesn't do OAuth, so authenticated servers will show a subset of tools or fail.
+
+## Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| `required variable REDIS_PASSWORD is missing` | Pass `REDIS_PASSWORD=testpass` as env var |
+| `required variable MCP_SERVER_URL is missing` | Pass `MCP_SERVER_URL=http://localhost:8000` (or tunnel URL) |
+| OAuth 401 when connecting via tunnel | `MCP_SERVER_URL` doesn't match the tunnel URL, or `TRUST_PROXY_HEADERS=true` is missing |
+| OAuth discovery returns 404 | **Check `lsof -i :8000`** — a stale local process is likely shadowing Docker. Kill it and restart containers with `down`/`up` (not just `restart`) |
+| Port 8000 already in use | `lsof -ti :8000 | xargs kill -9` then restart |
+| Redis connection refused | Check redis container is healthy: `docker ps | grep redis` |
+| cloudflared output is empty | It writes to stderr: use `2>/tmp/cf-tunnel.log` redirect |
+| Container doesn't pick up code changes | Add `--build` to the `docker compose up` command |
+| Container doesn't pick up env var changes | Must recreate: `docker compose ... down && docker compose ... up -d` |
+| `.env` not found in worktree | Symlink from main repo: `ln -s <main>/futuresearch-mcp/deploy/.env <worktree>/futuresearch-mcp/deploy/.env` |
+| Sheets tools not showing in tool list | Pass `ENABLE_SHEETS_TOOLS=true` and recreate the container |
+| `mcp_call.py` shows fewer tools than expected | It connects without auth — authenticated servers may filter tools |
+| Docker daemon not running | `colima start` (may need `colima stop && colima start` if socket is stale) |
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `futuresearch-mcp/deploy/docker-compose.yaml` | Base compose (server + redis) |
+| `futuresearch-mcp/deploy/docker-compose.local.yaml` | Local overrides (ports, env passthrough) |
+| `futuresearch-mcp/deploy/.env` | Production secrets (DO NOT commit changes) |
+| `futuresearch-mcp/deploy/Dockerfile` | Server container build |

futuresearch-0.6.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "futuresearch",
+  "owner": {
+    "name": "FutureSearch"
+  },
+  "metadata": {
+    "description": "futuresearch plugins from FutureSearch"
+  },
+  "plugins": [
+    {
+      "name": "futuresearch",
+      "source": "./",
+      "description": "Give Claude Code a research team. Forecast, score, classify, or research every row of a dataset.",
+      "version": "0.6.0"
+    }
+  ]
+}

futuresearch-0.6.0/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "futuresearch",
+  "description": "Give Claude Code a research team. Forecast, score, classify, or research every row of a dataset.",
+  "version": "0.6.0",
+  "author": {
+    "name": "FutureSearch"
+  },
+  "repository": "https://github.com/futuresearch/everyrow-sdk",
+  "mcpServers": {
+    "futuresearch": {
+      "command": "uvx",
+      "args": ["futuresearch-mcp"],
+      "env": {
+        "FUTURESEARCH_API_KEY": "${FUTURESEARCH_API_KEY}"
+      }
+    }
+  }
+}

futuresearch-0.6.0/.dockerignore

@@ -0,0 +1,17 @@
+# Deny everything by default, allowlist what the Dockerfile needs
+*
+
+# Root workspace files
+!pyproject.toml
+!uv.lock
+!README.md
+
+# SDK package
+!src/
+!src/**
+
+# MCP server package
+!everyrow-mcp/pyproject.toml
+!everyrow-mcp/README.md
+!everyrow-mcp/src/
+!everyrow-mcp/src/**

futuresearch-0.6.0/.env.example

@@ -0,0 +1,12 @@
+# FutureSearch API Configuration
+# Required: Your API key for authenticating with the FutureSearch API
+FUTURESEARCH_API_KEY=
+
+# Optional: API base URL (defaults to https://futuresearch.ai/api/v0/)
+# FUTURESEARCH_API_URL=https://futuresearch.ai/api/v0/
+# Optional: App base URL (defaults to https://futuresearch.ai/)
+# FUTURESEARCH_APP_URL=https://futuresearch.ai/
+
+# Legacy env vars (still supported for backwards compatibility):
+# EVERYROW_API_KEY=
+# EVERYROW_API_URL=

futuresearch-0.6.0/.gitattributes

@@ -0,0 +1,10 @@
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.svg filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.csv filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text

futuresearch-0.6.0/.github/workflows/ci.yaml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/futuresearch/**"
+      - "tests/**"
+      - "examples/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/ci.yaml"
+      - "futuresearch-mcp/**"
+
+  pull_request:
+    paths:
+      - "src/futuresearch/**"
+      - "tests/**"
+      - "examples/**"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "futuresearch-mcp/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: python
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Check formatting
+        run: uv run ruff format --check
+
+      - name: Run ruff
+        run: uv run ruff check
+
+      - name: Run tests
+        run: uv run pytest tests
+
+      - name: Run basedpyright
+        run: uv run basedpyright
+
+  mcp-checks:
+    name: futuresearch-mcp
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install redis-server
+        run: sudo apt-get update && sudo apt-get install -y redis-server
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --directory futuresearch-mcp
+
+      - name: Check formatting
+        run: uv run --directory futuresearch-mcp ruff format --check
+
+      - name: Run ruff
+        run: uv run --directory futuresearch-mcp ruff check
+
+      - name: Run tests
+        run: uv run --directory futuresearch-mcp pytest tests

futuresearch-0.6.0/.github/workflows/claude-code-review.yml

@@ -0,0 +1,72 @@
+name: Claude Code Review
+
+on:
+  # Interactive @claude mentions
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+  issues:
+    types: [opened, assigned]
+
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  # Interactive @claude responses
+  interactive:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history needed for PR checkout
+
+      # When commenting on a PR, checkout the PR branch instead of default branch
+      - name: Checkout PR branch (for PR comments)
+        if: github.event_name == 'issue_comment' && github.event.issue.pull_request
+        run: gh pr checkout ${{ github.event.issue.number }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run Claude Code
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          track_progress: true
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
+
+            IMPORTANT CONTEXT:
+            - You are running in GitHub Actions, not a local dev environment
+            - Focus on static code analysis, not runtime verification
+
+            REVIEW APPROACH:
+            - Use inline comments with code suggestions that authors can accept directly
+            - Focus on actionable feedback, not nitpicks
+            - Check for security issues, correctness, and adherence to existing patterns
+
+            STYLE:
+            - Please try to discard outdated comments from previous runs and keep the discussions in threads
+            - Update the comment message with the summary continuously, instead of adding more and more of these
+              per each review
+
+          claude_args: |
+            --model claude-opus-4-6
+            --allowedTools "Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh issue view:*),Bash(gh pr checks:*),Read,Glob,Grep,Task,WebSearch,WebFetch"