Skip to content

Latest commit

 

History

History
252 lines (188 loc) · 5.52 KB

quickstart-codegg.md

File metadata and controls

252 lines (188 loc) · 5.52 KB

Quickstart: Using eggsearch with CodeGG

This guide walks through installing eggsearch, configuring it, and using it from an MCP-compatible client such as CodeGG.

Prerequisites

  • Rust 1.89 or later installed when building from source
  • An MCP-compatible client (CodeGG, Claude Code, or any client supporting MCP over stdio or Streamable HTTP)

Installation

curl -fsSL https://github.com/eggstack/eggsearch/releases/latest/download/install.sh | bash

On Windows PowerShell:

irm https://github.com/eggstack/eggsearch/releases/latest/download/install.ps1 | iex

For a source installation:

cargo install eggsearch --locked

Or build from source:

git clone https://github.com/eggstack/eggsearch.git
cd eggsearch
cargo build --release

The binary is written to target/release/eggsearch.

Configuration

The config file is optional. eggsearch uses platform-specific locations: $XDG_CONFIG_HOME/eggsearch/config.toml on Linux (usually ~/.config/eggsearch/config.toml), ~/Library/Application Support/eggsearch/config.toml on macOS, and %APPDATA%\eggsearch\config.toml on Windows. It uses built-in defaults when no config file exists.

If you add a [search] table, include all of its required fields. Partial [search] tables are rejected. See Configuration for the full reference.

A minimal config:

[search]
mode = "live"
default_max_results = 10
max_results_cap = 50
max_query_chars = 512
timeout_ms = 8000
default_providers = ["duckduckgo", "brave", "yahoo"]

[search.providers]
duckduckgo = true
brave = true
startpage = true
yahoo = true

[fetch]
enabled = true

For coding work with GitHub integration:

[search]
mode = "live"
default_max_results = 10
max_results_cap = 50
max_query_chars = 512
timeout_ms = 8000
default_providers = ["duckduckgo", "brave"]

[search.providers]
duckduckgo = true
brave = true

[search.api.github_code]
enabled = true
api_key_env = "GITHUB_TOKEN"

[search.api.github_issues]
enabled = true
api_key_env = "GITHUB_TOKEN"

[search.api.github_releases]
enabled = true
api_key_env = "GITHUB_TOKEN"

[fetch]
enabled = true

Set the GITHUB_TOKEN environment variable before starting the server.

Running the MCP Server

Start the server on stdio transport:

eggsearch mcp stdio

Or set a custom config path:

eggsearch --config /path/to/config.toml mcp stdio

The server reads MCP JSON-RPC messages from stdin and writes responses to stdout.

For a persistent local endpoint instead, run:

eggsearch mcp serve --bind 127.0.0.1:11320 --path /mcp

Check http://127.0.0.1:11320/healthz before connecting. This mode is foreground-only and loopback-only; the installer does not register it as a service.

Client Configuration

Configure your MCP client to launch eggsearch as a child process over stdio, or declare the explicit local HTTP endpoint if the client supports Streamable HTTP. The exact configuration depends on your client.

CodeGG

In your CodeGG MCP server configuration:

{
  "mcpServers": {
    "eggsearch": {
      "command": "eggsearch",
      "args": ["mcp", "stdio"]
    }
  }
}

An HTTP-capable client can use the persistent endpoint explicitly:

{
  "mcpServers": {
    "eggsearch-http": {
      "url": "http://127.0.0.1:11320/mcp"
    }
  }
}

Claude Code

{
  "mcpServers": {
    "eggsearch": {
      "command": "eggsearch",
      "args": ["mcp", "stdio"]
    }
  }
}

For a custom config path, set the environment variable:

{
  "mcpServers": {
    "eggsearch": {
      "command": "eggsearch",
      "args": ["mcp", "stdio"],
      "env": {
        "EGGSEARCH_CONFIG": "/path/to/config.toml"
      }
    }
  }
}

Example Workflow

A typical research flow uses three tools:

1. Search

web_search({
  "query": "rust async runtime comparison",
  "intent": "research",
  "max_results": 10
})

Returns a list of source cards with next_actions and suggested_fetches. Follow sanitized next_actions without another discovery round trip; ignore unknown tool names. Keep the immediate palette small (web_search, repo_search, optionally web_fetch) and load specialists only when needed. See Progressive Disclosure.

2. Fetch

web_fetch({
  "url": "https://tokio.rs/blog/2020-04-preparing-for-tokio-0-3",
  "extract_mode": "markdown",
  "max_chars": 12000
})

Returns extracted text from the selected URL.

3. Batch Fetch

batch_fetch({
  "items": [
    "https://docs.rs/axum/latest/axum/",
    "https://docs.rs/actix-web/latest/actix_web/"
  ]
})

Fetches multiple URLs in bounded parallel.

Discovering Capabilities

Hosts may inspect provider_status during bootstrap; agents call it only when provider availability itself is relevant or troubleshooting is required. It is diagnostic, not a normal first research step:

provider_status({})

This returns provider health, server capabilities, tool capabilities, and workflow recipes.

Next Steps

  • MCP Integration Guide -- harness-developer reference (progressive disclosure, trust boundary, workflows); this quickstart is the end-user path into that guide
  • Configuration -- full config reference with all options and defaults
  • Provider Setup -- how to enable and configure individual providers
  • Tool Matrix -- compact reference for all 10 MCP tools
  • Agent Workflows -- recommended tool call sequences and recipes