captain-search

git clone https://github.com/mnm-matin/captain-search.git
cd captain-search
uv sync
uv run csearch skill install --scope user
uv run csearch web "openai api" --max-results 5

uvx --from captain-search csearch skill install
uvx --from captain-search csearch web "openai api" --max-results 5

# User-level install from this checkout
uv run csearch skill install --scope user

# Project-local install for the current repo
uv run csearch skill install --scope project

# Claude Code-compatible skill directory
uv run csearch skill install --target claude

# Once published to PyPI
uvx --from captain-search csearch skill install

You are installing the Captain Search MCP server. First ask the user which API keys they want to configure: SERPER_API_KEY, BRAVE_API_KEY, TAVILY_API_KEY, PERPLEXITY_API_KEY, PARALLEL_API_KEY, EXA_API_KEY, JINA_API_KEY, MORPH_API_KEY. Then ask which client they want to set up (Cursor, Claude Code, VS Code, Windsurf/Antigravity, OpenCode). Use only the keys they choose and remind them at least one web-search key is required.

Then provide the client-specific setup:
- Cursor: give the Captain Search Cursor deeplink and tell them to set the chosen keys as environment variables, then restart Cursor.
- Claude Code: use `claude mcp add captain-search -- uv run --directory /path/to/captain-search csearch mcp` and pass only the chosen keys with `-e KEY=value`.
- VS Code: use the `code --add-mcp` command with only the chosen env keys (or leave them blank if the user wants to fill later).
- Windsurf/Antigravity: add the MCP server to ~/.codeium/windsurf/mcp_config.json with the chosen env keys.
- OpenCode: add to opencode.jsonc under `mcp` with `type: "local"`, `command: ["uv", "run", "--directory", "/path/to/captain-search", "csearch", "mcp"]`, and an `environment` object with the chosen keys.

claude mcp add captain-search -e SERPER_API_KEY=your-key -- uv run --directory /path/to/captain-search csearch mcp

code --add-mcp '{"name":"captain-search","command":"uv","args":["run","--directory","/path/to/captain-search","csearch","mcp"],"env":{"SERPER_API_KEY":"your-key-here","BRAVE_API_KEY":"","TAVILY_API_KEY":"","PERPLEXITY_API_KEY":"","PARALLEL_API_KEY":"","EXA_API_KEY":"","MORPH_API_KEY":"","JINA_API_KEY":""}}'

{
  "mcp": {
    "servers": {
      "captain-search": {
        "command": "uv",
        "args": ["run", "--directory", "/path/to/captain-search", "csearch", "mcp"],
        "env": {
          "SERPER_API_KEY": "your-key-here",
          "BRAVE_API_KEY": "",
          "TAVILY_API_KEY": "",
          "PERPLEXITY_API_KEY": "",
          "PARALLEL_API_KEY": "",
          "EXA_API_KEY": "",
          "MORPH_API_KEY": "",
          "JINA_API_KEY": ""
        }
      }
    }
  }
}

{
  "mcpServers": {
    "captain-search": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/captain-search", "csearch", "mcp"],
      "env": {
        "SERPER_API_KEY": "your-key-here",
        "BRAVE_API_KEY": "",
        "TAVILY_API_KEY": "",
        "PERPLEXITY_API_KEY": "",
        "PARALLEL_API_KEY": "",
        "EXA_API_KEY": "",
        "MORPH_API_KEY": "",
        "JINA_API_KEY": ""
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "captain_search": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/captain-search", "csearch", "mcp"],
      "enabled": true,
      "environment": {
        "SERPER_API_KEY": "your-key-here",
        "BRAVE_API_KEY": "",
        "TAVILY_API_KEY": "",
        "PERPLEXITY_API_KEY": "",
        "PARALLEL_API_KEY": "",
        "EXA_API_KEY": "",
        "MORPH_API_KEY": "",
        "JINA_API_KEY": ""
      }
    }
  }
}

git clone https://github.com/mnm-matin/captain-search.git
cd captain-search
uv sync
uv run csearch skill install --scope user

uvx --from . csearch --help
uvx --from . csearch web "openai api"

source .venv/bin/activate
captain-search --help
csearch --help

.venv/bin/captain-search --help
.venv/bin/csearch --help

uv tool install .

# One-off runs
uvx --from captain-search csearch --help
uvx --from captain-search csearch web "openai api"

# Persistent install
uv tool install captain-search

# Bare invocation shows help
csearch
csearch version
csearch skill install --scope user

# Explicit MCP server startup
csearch mcp
csearch mcp --transport http --port 8000

# Direct CLI commands
csearch web "openai api" --max-results 5
csearch web "openai api" --all
csearch code "search_web" --repo mnm-matin/captain-search --format json
csearch fetch https://example.com --format json

# No-activation ephemeral runs with uvx
uvx --from . csearch web "openai api"

# Once published to PyPI
uvx --from captain-search csearch web "openai api"

# No-activation form if you want uv to launch the project env for you
uv run csearch web "openai api"

# Module form also works
uv run python -m captain_search web "openai api"

# HTTP mode
captain-search mcp --transport http --port 8000

# SSE mode  
captain-search mcp --transport sse --port 8000

export MCP_AUTH_TOKEN="your-secret-token"
captain-search mcp --transport http --port 8000

providers:
  serper:
    weight: 50
    enabled: true
  brave:
    weight: 30
    enabled: true

docker build -t captain-search .

docker run -p 8000:8000 \
  -e SERPER_API_KEY=your_key \
  -e MCP_AUTH_TOKEN=your_secret \
  captain-search mcp --transport http --port 8000

git clone https://github.com/mnm-matin/captain-search.git
cd captain-search
uv pip install -e ".[dev]"
pytest

RUN_E2E=1 uv run --extra dev python -m pytest -q tests/test_providers.py
LIVE_PROVIDER_CACHE_TTL_SECONDS=900 RUN_E2E=1 uv run --extra dev python -m pytest -q tests/test_providers.py
LIVE_PROVIDER_FORCE_REFRESH=1 RUN_E2E=1 uv run --extra dev python -m pytest -q tests/test_providers.py