[Integration] mateaix/mateclaw — You.com search provider plugin (PluginSearchProvider SPI)

[mouse-value-add]

Source repo

https://github.com/mateaix/mateclaw

Why selected

MateClaw is a pluggable agent runtime ("your second brain") built on Spring Boot 3.5 / Spring AI, ~1.1k stars, Apache-2.0, very active (pushed same day as this issue). Its web_search tool runs on a provider chain (DuckDuckGo / SearXNG keyless fallbacks, Serper / Tavily keyed), and the platform ships a first-class Plugin SDK with a PluginSearchProvider SPI (vip.mate.plugin.api.search) — third-party search providers are drop-in JARs with zero server changes, configurable through the plugin admin UI, and they appear in the search settings provider dropdown automatically. The repo already contains mateclaw-plugin-mem0, an "optional community contribution" memory plugin that is the exact structural template for an optional search plugin (module + manifest + tests + docs section). The platform does NOT have a You.com search option and You.com is not a competing provider for them.

Candidate evaluation summary

Candidate	Stars	Activity	Distribution surface	Verdict
mateaix/mateclaw	1088	pushed today	Plugin SDK with PluginSearchProvider SPI + plugin admin UI config + docs convention	Selected — purpose-built third-party search provider surface, exact template module exists
superdesigndev/treg	1230	active	tool catalog/marketplace, but it's a commercial metered registry — You.com would be a catalog entry on their own billing, not an optional provider; also NOASSERTION license	Rejected
pacifio/cersei	453	Aug 6	Rust SDK impl Tool abstraction, coding-agent focus, web tool exists	Decent but weaker: no plugin registry surface, Rust, smaller community, less natural fit
Kochava-Studios/witsy	2025	Apr 2026 (stale ~5mo)	MCP client desktop app	Rejected: stale + AGPL
whitelonng/mancode	358	active	coding harness	Rejected: AGPL-3.0, <400 stars

Proposed integration type

Provider adapter (plugin): new optional Maven module mateclaw-plugin-you-search implementing the existing PluginSearchProvider SPI — a You.com Search API client (POST https://ydc-index.io/v1/search, X-API-Key auth) exposed as a you provider in MateClaw's web_search provider chain. Follows the mateclaw-plugin-mem0 module structure exactly (manifest mateclaw-plugin.json with config schema, provided-scope deps only, JUnit tests against a local stub HTTP server, docs section in both en/ and zh/).

Distribution surface leveraged

The repo's own plugin system (PluginType.SEARCH + PluginContext.registerSearchProvider) — the integration is a drop-in JAR; no server code changes, no new hard dependencies, default behavior unchanged (plugin unavailable unless installed and configured).

Planned env vars / setup

• Plugin config (via MateClaw plugin admin UI, schema-declared): apiKey (required, secret) → sent as X-API-Key header; baseUrl (optional, defaults to https://ydc-index.io); country (optional); safesearch (optional); timeoutMs (optional, default 15000).
• Key obtained at https://you.com/platform/api-keys.

Expected usage example

Install JAR into MateClaw plugins/ dir → set apiKey in plugin admin UI → the you provider appears in Settings → System → Search Service and joins the web_search provider chain (freshness/language/count mapped to the You.com Search API freshness/language/count params).

Validation plan

• mvn -pl mateclaw-plugin-you-search -am package with Java 21 (project requires Java 21; local JDK was 17, installed Temurin 21 to /tmp for the run).
• Unit tests with a stub HttpServer covering: request shape (query/count/freshness/language), X-API-Key header, response parsing (results.web[] + results.news[] → title/url/snippet/source/date via page_age), non-2xx → exception (platform falls back to next provider), unavailable-when-no-key.
• Confirm default behavior unchanged: new module is additive; nothing in mateclaw-server or existing modules is touched except additive docs sections.

Status: COMPLETE ✅

• Branch: https://github.com/mouse-value-add/mateclaw/tree/feat/youcom-search-plugin (based on upstream default branch dev)
• PR: feat: add optional you.com search integration mateaix/mateclaw#631 — feat: add optional you.com search integration
• Integration type: Provider adapter (plugin) — PluginSearchProvider SPI implementation, provider id you, label "You.com"
• Distribution surface: the repo's own plugin system (registerSearchProvider, plugin admin UI config schema, plugin manifest)
• Setup: build mateclaw-plugin-you-search JAR → drop into plugins/ → set apiKey in plugin admin UI (optional: baseUrl, country, safesearch, timeoutMs)
• Usage: agent asks something needing web_search → platform tries providers in chain order; you participates when available; on failure it throws and the chain falls through to the next provider
• Fallback behavior: no API key → registered but isAvailable()=false, silently skipped; API error/timeout → YouSearchException → chain falls through; default stack unchanged for non-installers
• Tests run: mvn -pl mateclaw-plugin-you-search -am test — 11/11 pass (YouSearchClientTest 6: request shape, auth header, country/safesearch, web+news parsing with snippet fallback, 403, connection-refused; YouSearchPluginTest 5: config→registration, missing key→unavailable, defaults, id clash, query passthrough). Full reactor mvn package -DskipTests also clean.
• Live API validation: not run — no YDC_API_KEY in this environment; endpoint probe of POST https://ydc-index.io/v1/search returned 403 (auth-gated as expected, confirming the endpoint and auth mechanism)

[mouse-value-add]

PR opened: mateaix/mateclaw#631 (branch: https://github.com/mouse-value-add/mateclaw/tree/feat/youcom-search-plugin). Provider adapter plugin via PluginSearchProvider SPI; 11/11 unit tests pass; waiting on maintainer review.

[mouse-value-add]

2026-09-07 run: PR #631 opened 2026-09-07 (plugin module mateclaw-plugin-you-search + tests + docs). No reviews/comments yet; repo active (pushed 2026-09-07). No CI checks configured on the PR. Mergeable, awaiting maintainer review.

Note: consolidated duplicate tracking issue #267 into this one.