Open-WebSearch

Open-WebSearch is a tool for web searching and content scraping that does not require API keys. It provides multiple entry points depending on your use case:

• MCP Server: Best for integration with MCP clients like Claude Desktop, Cherry Studio, or Cursor.
• CLI: Best for one-off local commands, shell scripts, and terminal usage.
• Local Daemon: A persistent local HTTP service for reusable access. It provides endpoints for status, GET /health, POST /search, and POST /fetch-*.
• Skill: An agent-guidance layer used to help agents discover, enable, and use the tool within an agentic workflow.

To ensure consistency across MCP, CLI, and local HTTP adapters, all services should use a shared error shape. A canonical error must include the following fields:

• code: Error identifier.
• message: Human-readable error message.
• retryable: Boolean indicating if the operation can be retried.
• hint: Guidance for the user.
• details: Additional context or error data.

The Local HTTP Adapter provides a localhost-based HTTP interface for the open-websearch daemon. It is designed for local automation, debugging, and probing from CLI or skill flows.

Key architectural principles:

• Runtime Model: The adapter sits on top of the same shared runtime used by the MCP (Model Context Protocol) adapter. A single runtime container supports two protocol 'front doors': MCP and local HTTP.
• Binding Model: By default, the adapter binds to 127.0.0.1 on a configurable port. It is intended for local use only and not for public exposure.
• Response Model: All routes use a consistent JSON envelope containing status, data, error, and hint fields, ensuring compatibility between the HTTP API and the CLI.

The open-websearch skill follows a specific hierarchy of decision rules to provide information efficiently:

1. Direct URL Fetch: If a specific public URL is provided, fetch it directly instead of searching.
2. Focused Search: For current information, discovery, or comparisons, start with a single focused search.
3. Deep Reading: If a search snippet is insufficient, use fetchWebContent on the promising URL.
4. Repository Retrieval: If the target is a GitHub repository, use fetchGithubReadme instead of generic page fetching.

Engine Selection Heuristics:

• General English: Prefers startpage.
• Broad Web: Uses bing as a secondary option.
• Chinese-language/China-hosted: Uses baidu, csdn, or juejin.
• Multi-engine: Only used for cross-checking when a single pass is insufficient.

All API responses follow a consistent envelope structure.

Success Response:

{
  "status": "ok",
  "data": { ... },
  "error": null,
  "hint": null
}

Error Response:

{
  "status": "error",
  "data": null,
  "error": {
    "code": "error_code",
    "message": "Human readable error"
  },
  "hint": "Suggestion for resolution"
}

Open-WebSearch supports searching across multiple engines and extracting content from specific sources:

Search Engines:

• bing
• baidu
• csdn
• duckduckgo
• exa
• brave
• juejin
• startpage
• sogou

Content Extraction (Fetch):

• csdn: Extracts full text from CSDN blog posts.
• github: Extracts README files.
• General: Supports general HTTP(S) web pages and Markdown content extraction.

When building skills, plugins, or automated integrations, use the --json flag to ensure you receive machine-readable, stable output. Do not rely on the default human-readable format for programmatic consumption.

Output Envelope

All JSON responses follow a common envelope structure:

Success Envelope:

{
  "status": "ok",
  "data": { ... },
  "error": null,
  "hint": null
}

Error Envelope:

{
  "status": "error",
  "data": null,
  "error": {
    "code": "string",
    "message": "string",
    "retryable": boolean,
    "details": {}
  },
  "hint": "string"
}

Exit Codes

• 0: Command succeeded.
• 1: Command failed with a structured error or validation failure.
• 130: Shell-level interruption (e.g., SIGINT).

Note: open-websearch serve exits with 0 only after a clean shutdown via SIGINT or SIGTERM.

The open-websearch daemon provides a local HTTP API for scripts, tooling, and plugin integrations. By default, it binds to 127.0.0.1 and is not accessible from the public internet.

To start the daemon using the default configuration:

npm run serve

To start the daemon on a specific port:

node build/index.js serve --port 3211

To check the daemon status via the CLI:

npm run status -- --json
# Or specify a custom base URL:
npm run status -- --base-url http://127.0.0.1:3211 --json

Note: When calling localhost directly via curl, you may need to bypass shell proxy settings using the --noproxy '*' flag.

Before making changes, ensure the project's type integrity is maintained by running the TypeScript compiler in no-emit mode. This checks for type errors without generating output files.

npx tsc --noEmit