feat: add optional you.com search helper

[mouse-value-add]

Why\nThis MCP server already helps agents extract structured data from specific pages, but there is no built-in way to discover those pages first. This adds a small optional web-search helper so an agent can find candidate URLs, then hand those URLs back to the existing extraction flow. I kept this optional and left the default behavior unchanged.\n\n## What changed\n- added an optional MCP tool backed by the You.com Search API\n- only advertise the tool when is configured\n- documented setup for the additional env var and a basic usage example\n\n## Setup\n- stays required for \n- enables \n\n## Usage example\n\n\n## Validation\n-

agentql-mcp@1.0.1 lint
eslint src\n-
agentql-mcp@1.0.1 build
tsc && node -e "require('fs').chmodSync('dist/index.js', '755')"\n\n## Fallback / error handling\n- if is missing, is not registered\n- if the You.com request fails, the tool returns a clear error without affecting \n\nTracking issue: https://github.com/youdotcom-oss/integration-tracking/issues/82\n\nHappy to adjust the tool shape if you'd prefer a different name or result format.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3c5e288b-1252-43cc-8e04-9c9065f833e6

📥 Commits

Reviewing files that changed from the base of the PR and between 32eb17f and b4eedda.

⛔ Files ignored due to path filters (1)

• dist/index.js is excluded by !**/dist/**

📒 Files selected for processing (1)

• src/index.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/index.ts

---

📝 Walkthrough

Walkthrough

This pull request adds an optional You.com-based web search tool (search-web) to the AgentQL MCP server. The implementation adds You.com response types, loads and validates YDC_API_KEY, conditionally advertises search-web in the tool list, and handles search-web calls by querying the You.com search endpoint and returning normalized web and news results. README examples and MCP configuration snippets are updated to include YDC_API_KEY and show the new validation flow.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant MCPServer
  participant YDCIndexAPI
  Client->>MCPServer: ListToolsRequest
  MCPServer->>MCPServer: buildToolList()
  MCPServer-->>Client: tools (includes search-web if YDC_API_KEY set)
  Client->>MCPServer: CallToolRequest(search-web, query, count)
  MCPServer->>MCPServer: validate query, YDC_API_KEY
  MCPServer->>YDCIndexAPI: searchWeb(query, count)
  YDCIndexAPI-->>MCPServer: JSON search results
  MCPServer-->>Client: normalized { web, news } response

Loading

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: an optional You.com search helper.
Description check	✅ Passed	The description is on-topic and matches the PR’s optional You.com search helper and documentation updates.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/index.ts`:
- Around line 170-174: The query parsing in src/index.ts is validating after
coercion, so String(undefined) becomes a truthy "undefined" and bypasses the
missing-query error. In the request handling logic near the query/count
extraction, first read the raw query value from request.params.arguments, check
that it is present before converting it to a string, and only then proceed with
the existing count handling and error throw in the same block.
- Around line 104-108: The You.com fetch call in the request path currently has
no timeout, so a hung network request can block the MCP server. Update the fetch
invocation in the code around the endpoint request to pass an AbortSignal
created with AbortSignal.timeout(30_000), and make sure the surrounding request
handling in the same flow correctly propagates or handles the resulting abort
error.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5a2bb5ad-a3e2-4e1e-b7bb-bcf25c511b45

📥 Commits

Reviewing files that changed from the base of the PR and between db954ac and 32eb17f.

⛔ Files ignored due to path filters (2)

• dist/index.js is excluded by !**/dist/**
• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (2)

• README.md
• src/index.ts