Skip to main content

MagicalGirlWebOracle 🎀

MagicalGirlWebOracle icon

CI PyPI Docker Hub License: MIT Python 3.12

English · 简体中文 · 日本語

MagicalGirlWebOracle is a self-hosted web search, deep research, and page fetching router for AI agents, exposed through a single Model Context Protocol endpoint. It selects providers, accounts, and keys automatically — the agent just asks.

The hard rule is simple: use free quotas only, and never create a bill. ALLOW_PAID_OVERAGE=false is the default and the only supported value.

Highlights

  • One endpoint, many backends — You.com MCP, SearXNG, Exa, Tavily, Jina Reader, Crawl4AI, and Firecrawl behind one MCP/CLI interface.
  • Free-tier aware routing — scores quality, cost, remaining quota, health, and latency; expensive free credits are reserved for harder questions.
  • Self-hosted fallback — SearXNG + Crawl4AI keep search and fetching working even when every cloud quota is exhausted.
  • Chinese internet search — Chinese queries are routed to a SearXNG engine matrix (Baidu, Bing, Quark, Sogou, Bilibili, 360, …).
  • Evidence first — research responses contain real source URLs and excerpts, never fabricated citations.
  • Multi-account / multi-key ledger — optional per-account quota pools, encrypted credentials, official balance snapshots, and key rotation.
  • Fluent UI admin dashboard — light/dark themes, English / Simplified Chinese / Traditional Chinese / Japanese, quota and call inspection.
  • Auditable but private — query text is hashed by default; no telemetry and no outbound calls except the providers you configure.

How it works

Agent (Claude Code / Codex / any MCP client)
   │  MCP (stdio or streamable HTTP) / CLI
   ▼
Oracle
   ├── SearchRouter ── score candidates → concurrent calls → dedup/merge → rerank
   │      providers: you_mcp / searxng / exa / tavily
   ├── FetchRouter  ── light_http → jina_reader → crawl4ai → firecrawl
   ├── Quota ledger ── SQLite: reservations, settlement, windows, per-key usage
   ├── HealthTracker ─ healthy → degraded → unavailable → cooldown recovery
   └── Dedup         ─ URL canonicalization + cross-provider agreement

Dashboard

Light Dark
Dashboard light Dashboard dark

Quick start

git clone https://github.com/LingMoe404/MagicalGirlWebOracle.git
cd MagicalGirlWebOracle
cp .env.example .env

Edit .env:

  • Set MCP_AUTH_TOKEN to a long random value if other machines will connect.
  • Add the provider keys you have (EXA_API_KEY, TAVILY_API_KEY, FIRECRAWL_API_KEY, JINA_API_KEY, YDC_API_KEY); every key is optional.
  • Set SEARXNG_URL / CRAWL4AI_URL if you run those services.
  • MCP_BIND_IP defaults to 127.0.0.1. Set it to 0.0.0.0 (or a VPN/LAN address) only when you intentionally expose the service.
docker compose up -d --build
curl -fsS http://127.0.0.1:28288/healthz

MCP endpoint: http://127.0.0.1:28288/mcp.

The one-command script builds the image, auto-detects SearXNG/Crawl4AI, generates a token on first run, starts the service, and runs diagnostics:

bash deploy.sh

Docker Hub image

ORACLE_IMAGE=lingmoe404/magicalgirl-web-oracle:0.1.0 \
  docker compose up -d --no-build

PyPI (local stdio)

pip install magicalgirl-web-oracle
# create .env in the working directory, or export the variables directly
python -m magicalgirl_web_oracle.mcp_server.server

Connect an MCP client

Local stdio:

{
  "mcpServers": {
    "magicalgirl-web-oracle": {
      "command": "python",
      "args": ["-m", "magicalgirl_web_oracle.mcp_server.server"]
    }
  }
}

Shared HTTP:

{
  "mcpServers": {
    "magicalgirl-web-oracle": {
      "type": "streamable-http",
      "url": "http://<host>:28288/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Omit headers when MCP_AUTH_TOKEN is empty. See examples/mcp/ for copy-paste files.

CLI

magicalgirl-web search "rust async runtime benchmark" --mode high
magicalgirl-web search "小米 SU7 评测"                 # Chinese engine routing
magicalgirl-web research "量子计算主流路线对比"          # evidence pack
magicalgirl-web fetch "https://some-js-heavy-site.com"
magicalgirl-web crawl "https://docs.example.com" --max-pages 20
magicalgirl-web status                                 # health/quota table
magicalgirl-web doctor                                 # connectivity diagnostics

MCP tools

Tool Purpose
web_search(query, mode, max_results, provider_override, bypass_cache) Search with automatic routing. Modes: fast, auto, high, max.
web_research(query, max_results, fetch_top, bypass_cache) Multi-hop research; returns sources, excerpts, and real citations.
fetch_url(url, force_provider, bypass_cache) Fetch one page through the escalation ladder.
crawl_site(url, max_pages, max_depth) Depth-limited crawl; prefers self-hosted Crawl4AI.
search_status() Provider health, quota, scheduling, and cache status.
search_debug(query, provider, max_results) Force one provider for comparison.

Configuration

Configuration lives in .env plus config/providers.yaml and config/router_policy.yaml. All provider keys are optional; a missing key just removes that provider from routing.

See docs/configuration.md for every environment variable, defaults, cache/scheduling options, and the YAML files.

Multi-account dashboard

The optional dashboard manages multiple provider accounts and keys, encrypted with a Fernet master key, and shows official balance snapshots, alerts, call traces, cache counters, and scheduling decisions.

# .env: ORACLE_ADMIN_TOKEN, ORACLE_VAULT_KEY, ORACLE_ACCOUNTS_FILE
docker compose --profile admin up -d

Open https://127.0.0.1:28443/admin/ and sign in with ORACLE_ADMIN_TOKEN. See docs/multi-key-setup.md for the account model, key management, backups, and security notes.

Security and privacy

  • The HTTP server binds to 127.0.0.1 by default; expose it only on a trusted network or VPN and set MCP_AUTH_TOKEN.
  • The admin token is independent from the MCP token; empty disables the UI.
  • Provider keys live in .env, environment variables, or Fernet ciphertext in the local ledger. They are never returned by APIs or written to logs.
  • Query text is not stored unless STORE_QUERY_TEXT=true; the default is a salted hash.
  • 402 / payment-required responses are classified as quota exhaustion. There is no code path that enables paid overage.
  • The service has no telemetry and makes no network requests except to the providers and self-hosted services you configure.

Read SECURITY.md before exposing the service beyond a single machine.

Deployment and operations

See docs/deployment.md for Docker Compose, the optional HTTPS admin listener, SearXNG/Crawl4AI setup, VPN/reverse-proxy guidance, backups, upgrades, and troubleshooting.

Limitations and responsible use

  • This is a 0.1.x beta; interfaces may change before 1.0.
  • Free-tier quotas and provider APIs can change without notice. Use the service in accordance with each provider's terms. The project cannot guarantee that any provider remains free.
  • The container currently runs as root; the bundled admin listener uses a self-signed certificate by default.
  • “Oracle” in the project name is descriptive. This project is not affiliated with Oracle Corporation or with any search provider.

Development

python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest

cd frontend
npm ci
npm run build   # writes the admin bundle into src/.../admin/static/

The default test suite is fully mocked and needs no keys or network access.

License

MIT — see LICENSE. The icon artwork in assets/icon/ is original work by LingMoe404 and is distributed under the same license. Third-party notices are in THIRD_PARTY_NOTICES.md.

Metadata

Release files for magicalgirl-web-oracle 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for magicalgirl-web-oracle 0.1.0
File Size Uploaded Provenance Actions
magicalgirl_web_oracle-0.1.0.tar.gz 928.9 kB With provenance Details for magicalgirl_web_oracle-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for magicalgirl-web-oracle 0.1.0
File Interpreter ABI Platform Actions
magicalgirl_web_oracle-0.1.0-py3-none-any.whl Python 3 none any Details for magicalgirl_web_oracle-0.1.0-py3-none-any.whl

Total release size: 1.8 MB

Release files / magicalgirl_web_oracle-0.1.0.tar.gz

Download URL magicalgirl_web_oracle-0.1.0.tar.gz
Size 928.9 kB
Tags Source
SHA-256 checksum
How to use checksums
da38137ff8ed6b183e731c9faf9338f88f878ba813ced1c7798e4ac7c4df83a1
BLAKE2b-256 checksum
How to use checksums
07819dcb325a8eb2bd6bee9d9233069049049c4e702f639c3d786cbb53ff141f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / magicalgirl_web_oracle-0.1.0-py3-none-any.whl

Download URL magicalgirl_web_oracle-0.1.0-py3-none-any.whl
Size 879.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b2474655e5b0fde3b44ff093be3512effd1b7b351c78ac1d9cafc9d41045e9c4
BLAKE2b-256 checksum
How to use checksums
976aee9e3941d080dc8b94a9267bcccbae796caab3c969aed833f3d0512a934f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for magicalgirl-web-oracle 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for magicalgirl_web_oracle-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page