Skip to content

README.md

Latest commit

 

History

History
232 lines (179 loc) · 8.58 KB

README.md

File metadata and controls

232 lines (179 loc) · 8.58 KB
Raw

Degoog Logo

degoog


Lightweight Go sidecar that exposes Degoog to LLMs via the Model Context Protocol. Speaks modern MCP Streamable HTTP at /mcp, runs in a tiny scratch container, and gives any MCP-capable client two tools:

  • search - fast meta-search, returns model-readable plain-text results plus structured URLs, snippets, engine timings, cap metadata, and source overlap.
  • scrape - fetches URLs concurrently, returns clean Markdown plus one structured row per requested URL, including explicit error rows for failures.

Still in beta. Not intended for production use yet.


Join our discord community

Run

Listens on 4443 by default. Modern MCP endpoint at /mcp, healthcheck at /healthz. Config via DEGOOG_MCP_* env vars:

Variable Default Notes
DEGOOG_MCP_BIND_HOST (empty) Optional bind host. Use 127.0.0.1 for local-only deployments.
DEGOOG_MCP_PORT 4443 HTTP listen port.
DEGOOG_MCP_DEGOOG_URL http://degoog:4444 Where the Degoog aggregator lives. Default assumes shared compose.
DEGOOG_MCP_DEGOOG_API_KEY (empty) Optional Bearer token sent to Degoog as an Authorization header.
DEGOOG_MCP_AUTH_TOKEN (empty) Optional inbound bearer token clients must present on /mcp. Empty = /mcp is open. /healthz is always open.
DEGOOG_MCP_TIMEOUT 15s Per-request timeout for both Degoog calls and scraped URLs.
DEGOOG_MCP_MAX_RESULTS 0 Cap on merged search results (top-scored kept). 0 = no cap. Trims context for small-window models. Overridable per call.
DEGOOG_MCP_ENGINES (empty) Comma-separated engine ids to restrict every search to (e.g. brave,duckduckgo). Empty = instance defaults. Overridable per call.
DEGOOG_MCP_SEARCH_TEXT none Visible search text. full returns breakdown + result rows + scrape guidance. results returns only titles, URLs, snippets, and scrape guidance. breakdown returns query/cap/source metadata, visible-text/structuredContent explanation, and scrape guidance. none emits no visible search text and relies on structuredContent; structuredContent.summary still includes follow-up guidance.
DEGOOG_MCP_MAX_LENGTH 12000 Max scraped-markdown length before head+tail truncation.
DEGOOG_MCP_MAX_URLS 8 Max URLs accepted by one scrape tool call.
DEGOOG_MCP_SCRAPE_CONCURRENCY 4 Max concurrent URL fetches inside one scrape call.
DEGOOG_MCP_MAX_RESPONSE_BYTES 2097152 Max downloaded bytes per scraped response before readability.
DEGOOG_MCP_CACHE_EXPIRY 30m Scrape cache TTL.
DEGOOG_MCP_CACHE_SIZE_MB 64 Scrape cache hard memory cap.
DEGOOG_MCP_DISABLE_SCRAPE false When true, do not register the scrape tool; search remains available and tells agents to answer from snippets/results.
DEGOOG_MCP_LOG_LEVEL info debug / info / warn / error.
DEGOOG_MCP_USER_AGENT a believable Chrome UA Used by the scraper when fetching pages.

The scraper accepts only http and https URLs, resolves DNS before dialing, blocks private and local IP ranges, and repeats the checks on redirects.

Valid engine ids for DEGOOG_MCP_ENGINES (and the per-call engines argument) come from your instance: GET /api/extensions?type=engine lists them. Running a second Degoog instance with a single engine enabled is no longer necessary; restrict from the MCP side instead.

Docker Compose - standalone 
services:
  degoog-mcp:
    image: ghcr.io/degoog-org/mcp:latest
    ports:
      - "4443:4443"
    environment:
      DEGOOG_MCP_DEGOOG_URL: "http://<your-degoog-host>:4444"
      # Optional: require clients to send Authorization: Bearer <token> to /mcp
      DEGOOG_MCP_AUTH_TOKEN: ""
      DEGOOG_MCP_BIND_HOST: ""
    restart: unless-stopped
Docker Compose - alongside Degoog

Both services on a shared network. The sidecar can reach the aggregator internally at http://degoog:4444.

services:
  degoog:
    image: ghcr.io/degoog-org/degoog:latest
    volumes:
      - ./data:/app/data
    ports:
      - "4444:4444"
    networks: [degoog-net]
    restart: unless-stopped

  degoog-mcp:
    image: ghcr.io/degoog-org/mcp:latest
    depends_on: [degoog]
    ports:
      - "4443:4443"
    networks: [degoog-net]
    restart: unless-stopped

networks:
  degoog-net:
    driver: bridge

Connect a client

Modern Streamable HTTP endpoint: http://localhost:4443/mcp

If your MCP host prefixes tool names with the server name, name the server degoog rather than an environment-specific label. That keeps exposed names short and obvious, e.g. mcp_degoog_search and mcp_degoog_scrape.

Auth

When DEGOOG_MCP_AUTH_TOKEN is set, every request to /mcp must carry Authorization: Bearer <token>. Missing, malformed, or wrong tokens get a 401 with a WWW-Authenticate: Bearer header. /healthz stays open so container health checks keep working. Leave the variable empty to keep /mcp open. For clients that support custom HTTP headers, add the bearer header (examples below).

Claude Desktop / current Claude

Use HTTP transport where your Claude client supports remote MCP servers:

{
  "mcpServers": {
    "degoog": {
      "type": "http",
      "url": "http://localhost:4443/mcp"
    }
  }
}

If you set DEGOOG_MCP_AUTH_TOKEN, add the bearer header:

{
  "mcpServers": {
    "degoog": {
      "type": "http",
      "url": "http://localhost:4443/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

For stdio-only Claude Desktop builds, use mcp-remote as a bridge. Edit claude_desktop_config.json (Settings -> Developer -> Edit Config):

{
  "mcpServers": {
    "degoog": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:4443/mcp"]
    }
  }
}

Restart Claude Desktop.

Claude Code (CLI) 
claude mcp add --transport http degoog http://localhost:4443/mcp
Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "degoog": {
      "url": "http://localhost:4443/mcp"
    }
  }
}
Cursor / Continue / Cline / other clients

Most editors that speak MCP accept a config block like:

{
  "mcpServers": {
    "degoog": {
      "url": "http://localhost:4443/mcp",
      "transport": "http"
    }
  }
}

If you set DEGOOG_MCP_AUTH_TOKEN, add an Authorization: Bearer <token> header where your client supports custom HTTP headers.

For stdio-only clients, wrap with npx mcp-remote http://localhost:4443/mcp the same way Claude Desktop does above.

Tests

With Go installed:

go test -race -count=1 ./...

Without Go, run them in a throwaway container:

docker compose -f docker-compose.test.yml run --rm test


Buy me a coffee