docs(readme): rewrite to lead with user value and free-tier MCP#85
Conversation
Restructures the root README so the first screen targets developers evaluating You.com for their agent rather than contributors. Leads with a copy-paste MCP config for the free tier, then per-client setup, packages, and three use-case snippets. Bun/monorepo content moves to links to AGENTS.md and CONTRIBUTING.md.
|
Droid encountered an error —— View job Droid is reviewing code and running a security check… |
|
Droid finished @brainsparker's task —— View job Droid review complete. Summary: The README rewrite successfully restructures the document from contributor-focused to user-focused, with accurate package references and consistent code snippets verified against source. One bug: both |
![factory-droid[bot]](https://avatars.githubusercontent.com/in/358017?s=60&v=4){kind=small}
| claude mcp add you -- npx @youdotcom-oss/mcp -e YDC_PROFILE=free | ||
|
|
||
| # Authenticated | ||
| claude mcp add you -- npx @youdotcom-oss/mcp -e YDC_API_KEY=<your-key> |
There was a problem hiding this comment.
[P1] claude mcp add -e flag placed after -- separator
The -e flag must come before the server name, not after the -- separator. After --, it becomes an argument to npx rather than an environment variable setting for claude mcp add. The official CLI help shows: claude mcp add -e API_KEY=xxx my-server -- npx my-mcp-server. Users who copy these commands will register the MCP server without the YDC_PROFILE or YDC_API_KEY environment variables, so the free-tier command will fail (no key, no profile) and the authenticated command will run without credentials.
| claude mcp add you -- npx @youdotcom-oss/mcp -e YDC_PROFILE=free | |
| # Authenticated | |
| claude mcp add you -- npx @youdotcom-oss/mcp -e YDC_API_KEY=<your-key> | |
| claude mcp add -e YDC_PROFILE=free you -- npx @youdotcom-oss/mcp | |
| # Authenticated | |
| claude mcp add -e YDC_API_KEY=<your-key> you -- npx @youdotcom-oss/mcp |
The -e flag must precede the -- separator; otherwise it is forwarded to npx as an argument instead of stored as an env var on the MCP server.
|
Droid finished @brainsparker's task —— View job Droid review complete. Summary: The README rewrite is clean and accurate. The previous P1 ( |
|
|
||
| - **Real web index** — backed by You.com's production search infrastructure, not a scraper. | ||
| - **Free tier, no signup** — `?profile=free` exposes `you-search` to any MCP client with zero auth. | ||
| - **Listed in the official Anthropic MCP registry** as [`io.github.youdotcom-oss/mcp`](https://github.com/modelcontextprotocol/registry). |
There was a problem hiding this comment.
would this be better as https://registry.modelcontextprotocol.io/ or https://registry.modelcontextprotocol.io/?q=io.github.youdotcom-oss%2Fmcp ?
There was a problem hiding this comment.
Good call — switched to the filtered registry listing in a057b1a. Also dropped "Anthropic" from the description since the registry is run by the MCP project itself.
tyler5673
left a comment
tyler5673
left a comment
There was a problem hiding this comment.
looks good! one comment
…l.io Tyler's PR feedback: the registry.modelcontextprotocol.io site is the actual registry surface; the github.com/modelcontextprotocol/registry repo is just the server source. Link directly to the filtered listing for io.github.youdotcom-oss/mcp. Also drop "Anthropic" from the description — the MCP registry is run by the MCP project, not Anthropic specifically.
|
Droid encountered an error —— View job Droid is reviewing code and running a security check… |
Mirror the fix from a057b1a: point the Links-section "MCP registry listing" entry at the filtered registry.modelcontextprotocol.io view instead of the registry server repo, so both references to the listing resolve to the same place.
|
Droid finished @brainsparker's task —— View job Droid review complete. Summary: One factual inconsistency found: the Quick Start section claims you-finance is unlocked by setting YDC_API_KEY, but the Packages section and source code confirm it requires an explicit ?tools=you-finance parameter or YDC_ALLOWED_TOOLS env var. Otherwise the README rewrite is accurate and well-structured. |
| - `ydc tools` | ||
| - `ydc schema <tool> [input|output]` | ||
| - `ydc <tool> <json>` | ||
| Every snippet below works against the free tier. To unlock `you-research`, `you-contents`, and `you-finance`, drop the `YDC_PROFILE` line and set `YDC_API_KEY` to a key from [you.com/platform/api-keys](https://you.com/platform/api-keys). |
There was a problem hiding this comment.
[P1] Quick start overpromises you-finance as unlocked by API key
Line 31 says setting YDC_API_KEY unlocks you-research, you-contents, and you-finance, but line 145 states that you-finance "is available on request via ?tools=you-finance" and the authenticated default only exposes you-search, you-research, and you-contents. A user who sets only YDC_API_KEY will not see you-finance listed, contradicting the quick-start promise. The quick-start sentence should match the packages-section description.
| Every snippet below works against the free tier. To unlock `you-research`, `you-contents`, and `you-finance`, drop the `YDC_PROFILE` line and set `YDC_API_KEY` to a key from [you.com/platform/api-keys](https://you.com/platform/api-keys). | |
| Every snippet below works against the free tier. To unlock `you-research` and `you-contents`, drop the `YDC_PROFILE` line and set `YDC_API_KEY` to a key from [you.com/platform/api-keys](https://you.com/platform/api-keys). For `you-finance`, pass `?tools=you-finance` or set `YDC_ALLOWED_TOOLS=you-finance`. |
The quick-start blurb listed you-finance as unlocked by YDC_API_KEY, but the authenticated default only exposes you-search, you-research, and you-contents. you-finance requires an explicit ?tools=you-finance query param or YDC_ALLOWED_TOOLS=you-finance, matching the packages section further down.
|
Droid finished @brainsparker's task —— View job Droid review complete. Summary: One factual inaccuracy remains: the Quick start and Packages sections imply |
| - `ydc tools` | ||
| - `ydc schema <tool> [input|output]` | ||
| - `ydc <tool> <json>` | ||
| Every snippet below works against the free tier. To unlock `you-research` and `you-contents`, drop the `YDC_PROFILE` line and set `YDC_API_KEY` to a key from [you.com/platform/api-keys](https://you.com/platform/api-keys). `you-finance` is opt-in — pass `?tools=you-finance` on the URL or set `YDC_ALLOWED_TOOLS=you-finance`. |
There was a problem hiding this comment.
[P1] ?tools=you-finance scopes to finance-only, losing default tools
The Quick start says "you-finance is opt-in — pass ?tools=you-finance on the URL or set YDC_ALLOWED_TOOLS=you-finance", implying these add you-finance to the defaults. In reality, ?tools= scopes (replaces) the visible tool set — a user who sets YDC_ALLOWED_TOOLS=you-finance will only see you-finance and lose you-search, you-research, and you-contents. The mcp package's own README confirms this with explicit examples: "Finance only: https://api.you.com/mcp?tools=you-finance" vs "Search plus finance: https://api.you.com/mcp?tools=you-search,you-finance". The same misconception appears at line 145. The guidance should show comma-separated lists including desired defaults.
| Every snippet below works against the free tier. To unlock `you-research` and `you-contents`, drop the `YDC_PROFILE` line and set `YDC_API_KEY` to a key from [you.com/platform/api-keys](https://you.com/platform/api-keys). `you-finance` is opt-in — pass `?tools=you-finance` on the URL or set `YDC_ALLOWED_TOOLS=you-finance`. | |
| Every snippet below works against the free tier. To unlock `you-research` and `you-contents`, drop the `YDC_PROFILE` line and set `YDC_API_KEY` to a key from [you.com/platform/api-keys](https://you.com/platform/api-keys). `you-finance` is opt-in — `?tools=` scopes the visible tool set, so include every tool you need, e.g. `?tools=you-search,you-finance` or `YDC_ALLOWED_TOOLS=you-search,you-finance`. |
3 participants
Rationale
The previous README sold the repo to contributors (Bun setup, monorepo commands, quality checks) before it sold the toolkit to anyone evaluating whether to use You.com in their agent stack. Two strong distribution plays were buried: the free-tier remote MCP server at
https://api.you.com/mcp?profile=free(no API key, no signup) and the official Anthropic MCP registry listing asio.github.youdotcom-oss/mcp. This rewrite restructures the README so the first screen is a copy-paste MCP config for the free tier, followed by per-client setup, packages, and three use-case snippets. Bun/monorepo content moves to links toAGENTS.mdandCONTRIBUTING.md.What changed
mcp,ai-sdk-plugin,langchain,cli) and links to their READMEs.AGENTS.mdandCONTRIBUTING.mdinstead of inlining Bun commands.Notes on accuracy
packages/— only the four exist; noteams-anthropic, noapi, noplugins/dir.you-searchonly) matchespackages/mcp/README.mdandpackages/mcp/src/stdio-bridge.ts.packages/mcp/server.jsonand is published from.github/workflows/publish-mcp.yml.Opened as draft for a review pass before marking ready.
Generated by Claude Code