juso-search

An MCP server (stdio) that exposes the Juso search extension's agent-bridge search capabilities to MCP clients (Claude Desktop, Cursor, Cline, Claude Code, …). It mirrors the CLI agent-skill juso_search subcommands over MCP JSON-RPC 2.0, with a short-lived browser launch per call (Chromium-family or Firefox) that the extension claims and completes through its Agent Bridge.

• Transport: stdio. JSON-RPC flows over stdin/stdout; diagnostics go to stderr (stdout stays clean — only newline-delimited JSON-RPC).
• Config: environment variables via the client's MCP env block. No CLI flags besides --help / --version (prints the package version).
• Dual era: accepts both the legacy initialize handshake and the modern server/discover (2026-07-28 protocol). Tested at the wire level.
• Vendored bridge: juso_search/juso_bridge.py is byte-identical to public/agent-skill/scripts/juso_bridge.py (the plan's drift lock). Never edit it by hand — regenerate from the source.

Install

Published on PyPI. Requires Python 3.10+ and mcp>=2.0,<3 (installed automatically as a dependency).

pip install juso-search

From this repository (development):

python -m venv mcp-server/.venv
mcp-server/.venv/Scripts/pip install -e mcp-server/

Verify:

mcp-server/.venv/Scripts/juso-search --help

Environment variables

* Either JUSO_EXTENSION_ID or JUSO_BRIDGE_URL must be set. Chrome can derive the bridge URL from the id, so only the id is needed; Firefox needs the full bridge URL and the id is optional. JUSO_BROWSER_PATH is always required — the server refuses to start without it (exit code 2 and a stderr message) rather than guessing. (Browser auto-discovery is a CLI-skill convenience only; the MCP server always needs an explicit executable because a wrong guess is a silent failure that is hard to diagnose over stdio.)

Client configuration

Each client injects these variables differently. Pick your client:

Claude Desktop (claude_desktop_config.json)

Claude Desktop does not expand ${VAR}, so write literal values:

JUSO_BROWSER_PATH by OS — Windows: C:\Program Files\Google\Chrome\Application\chrome.exe (or C:\Program Files\Mozilla Firefox\firefox.exe) · macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome (or /Applications/Firefox.app/Contents/MacOS/firefox) · Linux: /usr/bin/google-chrome (or /usr/bin/firefox).

{
  "mcpServers": {
    "juso": {
      "command": "juso-search",
      "args": [],
      "env": {
        "JUSO_EXTENSION_ID": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "JUSO_BROWSER_PATH": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
        "JUSO_TIMEOUT": "40"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "juso": {
      "command": "juso-search",
      "args": [],
      "env": {
        "JUSO_EXTENSION_ID": "${env:JUSO_EXTENSION_ID}",
        "JUSO_BROWSER_PATH": "${env:JUSO_BROWSER_PATH}",
        "JUSO_BROWSER_PROFILE": "${env:JUSO_BROWSER_PROFILE}",
        "JUSO_TIMEOUT": "${env:JUSO_TIMEOUT}"
      }
    }
  }
}

Cline (cline_mcp_settings.json)

JUSO_BROWSER_PATH by OS — macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome (or /Applications/Firefox.app/Contents/MacOS/firefox) · Linux: /usr/bin/google-chrome (or /usr/bin/firefox). The example below uses the Windows path.

{
  "mcpServers": {
    "juso": {
      "command": "juso-search",
      "args": [],
      "env": {
        "JUSO_EXTENSION_ID": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "JUSO_BROWSER_PATH": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
        "JUSO_BROWSER_PROFILE": "",
        "JUSO_TIMEOUT": "40"
      }
    }
  }
}

Claude Code (.mcp.json)

Claude Code expands ${VAR} from the shell environment, with :-default fallback:

{
  "mcpServers": {
    "juso": {
      "command": "juso-search",
      "args": [],
      "env": {
        "JUSO_EXTENSION_ID": "${JUSO_EXTENSION_ID}",
        "JUSO_BROWSER_PATH": "${JUSO_BROWSER_PATH}",
        "JUSO_BROWSER_PROFILE": "${JUSO_BROWSER_PROFILE:-}",
        "JUSO_TIMEOUT": "${JUSO_TIMEOUT:-40}"
      }
    }
  }
}

Tools

All tools are annotated readOnlyHint + openWorldHint. Tool results carry structuredContent plus a text serialization; engine-search error replies (consent wall, challenge, timeout) and search-site / search-aggregate error replies (unknown id, disabled engine-search sub-switch, rerank unconfigured) surface as successful results carrying an error field — only genuine bridge failures (e.g. Chrome not found, bridge not enabled) come back as isError.

The search tools return leads, not evidence: titles, snippets, and AI summaries may be truncated, stale, or inaccurate. Agents should open result URLs with their own page-fetch capability and verify specifics on the source page.

Prerequisites (in the extension)

1. Find your extension id: open chrome://extensions (enable Developer mode), copy the 32-char id from the Juso card — or use about:addons on Firefox for the email-style/{GUID} id, and export the skill from the Options page to get the full moz-extension:// bridge URL (set it as JUSO_BRIDGE_URL instead of the id).
2. Enable Agent Bridge in the extension's Options. Without it every call fails with extension_did_not_claim.
3. To use engine-search, also enable its sub-switch in Options.

Development / tests

python -m pytest mcp-server/tests        # or: npm run test:mcp

The suite covers config parsing/exit codes, tools/list schema and wire fields, tools/call dispatch and error shapes, the dual-era handshake over real subprocesses, and stdout cleanliness (only JSON-RPC on stdout).