{"_id":"@brainsparker/you-aware","name":"@brainsparker/you-aware","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@brainsparker/you-aware","version":"0.1.0","description":"Context-aware web search MCP for agent harnesses — reads your project's AGENTS.md, compiles project context into agent-shaped queries, and searches through the You.com Search API.","license":"MIT","author":{"name":"Brian Sparker","email":"brianjsparker@gmail.com"},"repository":{"type":"git","url":"git+https://github.com/brainsparker/MCP-Profiles.git"},"homepage":"https://github.com/brainsparker/MCP-Profiles#readme","bugs":{"url":"https://github.com/brainsparker/MCP-Profiles/issues"},"type":"module","bin":{"you-aware":"dist/index.js"},"main":"./dist/lib.js","types":"./dist/lib.d.ts","exports":{".":{"types":"./dist/lib.d.ts","import":"./dist/lib.js"},"./package.json":"./package.json"},"engines":{"node":">=18"},"scripts":{"build":"tsup","prepublishOnly":"npm run typecheck && npm test && npm run build","dev":"tsx watch src/index.ts","start":"node dist/index.js","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","eval":"tsx src/eval/run.ts","inspect":"npm run build && npx @modelcontextprotocol/inspector node dist/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^22.10.0","tsup":"^8.3.5","tsx":"^4.19.2","typescript":"^5.7.2","vitest":"^2.1.8"},"gitHead":"61c75257e8ca5bb6ffaeac98a3aa530df1316761","_id":"@brainsparker/you-aware@0.1.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-4OJD/3qge93N1oIB33XRVcfIWoc08fJl9JtsdNRsK92ltVsMpjtP1P6uqvbm115iUDLFO3RSOjEqKfjyDqsnMw==","shasum":"01a983358b7c06bdaba576b2395bc62d867677e2","tarball":"https://registry.npmjs.org/@brainsparker/you-aware/-/you-aware-0.1.0.tgz","fileCount":26,"unpackedSize":293593,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCM2D7F4m/I+uKiQp9DRf98P84V9Rqs2hSpryHBlvcmagIgXIQey/w7qudpYHweO5d7Dsk5AdT5YL8xyV8rvCE9nIc="}]},"_npmUser":{"name":"brainsparker","email":"brianjsparker@gmail.com"},"directories":{},"maintainers":[{"name":"brainsparker","email":"brianjsparker@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/you-aware_0.1.0_1786634850453_0.60036638296047"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-13T15:27:30.246Z","0.1.0":"2026-08-13T15:27:30.620Z","modified":"2026-08-13T15:27:30.897Z"},"maintainers":[{"name":"brainsparker","email":"brianjsparker@gmail.com"}],"description":"Context-aware web search MCP for agent harnesses — reads your project's AGENTS.md, compiles project context into agent-shaped queries, and searches through the You.com Search API.","homepage":"https://github.com/brainsparker/MCP-Profiles#readme","repository":{"type":"git","url":"git+https://github.com/brainsparker/MCP-Profiles.git"},"author":{"name":"Brian Sparker","email":"brianjsparker@gmail.com"},"bugs":{"url":"https://github.com/brainsparker/MCP-Profiles/issues"},"license":"MIT","readme":"# you-aware\n\n**Context-aware web search for AI agents — search that already knows what you're working on.**\n\n`you-aware` is an opinionated, installable [MCP](https://modelcontextprotocol.io) server that makes web search context-aware when the caller is an AI agent. It reads the context the developer has already written — the project's `AGENTS.md` (or `CLAUDE.md`, or Cursor/Cline/Windsurf rules) — and compiles it into the lexical, operator-heavy query language production agents actually speak, delivered through the You.com Search API. Every response carries a trace of exactly what ran, and an ablation [eval harness](./eval) ships in the repo so the claim is testable, not vibes: `npm run eval` compares plain passthrough against compiled queries on your own goldset.\n\nYour agent's harness already knows your trusted sources, your prior decisions, and your stack. The search API call should reflect all of it. With `you-aware`, it does — without configuring a second memory system.\n\n```\n\"best way to handle date parsing in this project\"\n        │\n        ▼  reads AGENTS.md · merges model-supplied context · compiles\ntypescript date parsing \"date-fns\" -moment        + trusted/blocked/freshness params\n        │\n        ▼\nranked You.com results + an inspectable trace of exactly what ran\n```\n\n## Install\n\nThe server is a single `npx`-runnable stdio binary — add it to any MCP client. In your `opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"you-aware\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@brainsparker/you-aware\"],\n      \"enabled\": true,\n      \"timeout\": 60000,\n      \"environment\": { \"YOU_AWARE_HARNESS\": \"opencode\" }\n    }\n  }\n}\n```\n\nIn Claude Code:\n\n```bash\nclaude mcp add you-aware -- npx -y @brainsparker/you-aware\n```\n\nThe same `npx` command works in any MCP client. Full config examples (including the keyed variants) are in [examples/client-config/](./examples/client-config):\n\n| Client | Config file | Example | Context file read |\n|---|---|---|---|\n| OpenCode | `opencode.json` | [opencode.json](./examples/client-config/opencode.json) | `AGENTS.md` |\n| Claude Code | `claude mcp add you-aware -- npx -y @brainsparker/you-aware` | — | `AGENTS.md` / `CLAUDE.md` |\n| Claude Desktop | `claude_desktop_config.json` | [claude-desktop.json](./examples/client-config/claude-desktop.json) | `AGENTS.md` / `CLAUDE.md` |\n| Codex CLI | `~/.codex/config.toml` | [codex-cli.toml](./examples/client-config/codex-cli.toml) | `AGENTS.md` |\n| Cursor | `.cursor/mcp.json` | [cursor.json](./examples/client-config/cursor.json) | `.cursor/rules/*.mdc`, `.cursorrules` |\n| Gemini CLI | `.gemini/settings.json` | [gemini-cli.json](./examples/client-config/gemini-cli.json) | `GEMINI.md` |\n| Cline | `cline_mcp_settings.json` | [cline.json](./examples/client-config/cline.json) | `.clinerules` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` | [windsurf.json](./examples/client-config/windsurf.json) | `.windsurfrules` |\n| VS Code / Copilot & anything else | varies | [generic-mcpservers.json](./examples/client-config/generic-mcpservers.json) | `.github/copilot-instructions.md`, `AGENTS.md` |\n\n\"Context file read\" is what the server falls back to for that client's native convention — `AGENTS.md` (then `CLAUDE.md`) always wins when present, so one `AGENTS.md` serves every client identically. Full discovery order in [docs/context-conventions.md](./docs/context-conventions.md).\n\nOne config block (or one command). No account creation. No memory setup. First retrieval works immediately because your project's `AGENTS.md` (or `CLAUDE.md`) is already in place. Without a key, searches run through You.com's hosted free tier (the same keyless tier the official You.com MCP uses — search-only, roughly 100 queries/day, context compiled into the query). Setting `YDC_API_KEY` — the same You.com Search API key you may already have, from [you.com/platform](https://you.com/platform) — switches to the direct Search API with higher limits and the native context parameters. Add it to the `environment` block:\n\n```json\n\"YDC_API_KEY\": \"{env:YDC_API_KEY}\"\n```\n\n(An `{env:…}` reference that's unset in your shell substitutes to an empty string — the server treats it as absent and stays on the free tier. Clients that use the `mcpServers` config shape call this block `\"env\"` and don't substitute `{env:…}` — put the key itself there. The generous `timeout` covers `npx`'s first-run package download.)\n\n**Data handling, plainly:** the search call itself carries your query and populated parameters to You.com — that's the product. Everything else stays local: raw context/rules files, conversation history, file paths, and the per-project memory never leave your machine, and file content becomes search context only when you author an explicit `## Project Context` section. Telemetry (queries, parameters, result URLs, outcome signals) is on by default but **ships nowhere out of the box** — it spools to a capped, owner-readable local file, and is only transmitted if you explicitly configure `YOU_AWARE_TELEMETRY_URL`. Turn it off entirely with `YOU_AWARE_TELEMETRY=off`. Full details, including exactly which three source files can emit bytes, in [docs/data-handling.md](./docs/data-handling.md). If you want a fixed dependency, pin the version: `npx -y @brainsparker/you-aware@0.1`.\n\n### Companion skill\n\n[`skills/you-aware/`](./skills/you-aware) is an [Agent Skill](https://agentskills.io) that teaches an agent both halves of the loop — when and how to call `search`, and how to keep the `AGENTS.md` sections current. Install it by copying the folder into your client's skills directory — project-level `.opencode/skills/`, `.claude/skills/`, or `.agents/skills/`, or their global equivalents (`~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/`):\n\n```bash\ncp -r node_modules/@brainsparker/you-aware/skills/you-aware .opencode/skills/\n```\n\n(or copy it straight from this repo). The skill body loads only when relevant — its at-rest cost is one description line.\n\n## What it does\n\nThe server exposes two tools. **`search`** takes a `query` plus the four context-aware parameters of the You.com Search API (the durable contract, documented in [spec/search-parameters.md](./spec/search-parameters.md)); **`report_outcome`** closes the loop, feeding the [per-project retrieval memory](#retrieval-memory-the-write-back-loop) with the result URLs the agent actually used.\n\n| Parameter | Type | Retrieval mechanic |\n|---|---|---|\n| `trusted_sources` | `string[]` | per-domain boost at rank time |\n| `blocked_sources` | `string[]` | per-domain filter / hard demotion |\n| `project_context` | `string` (≤ 4 KB) | context-conditioned ranking + lexical vocabulary injection |\n| `freshness` | `\"fresh\" \\| \"stable\" \\| \"any\"` | recency window tuning |\n\nAll parameters are optional. With everything omitted you get exactly today's Search API behavior — no regression.\n\n### Parameter population: deterministic file-read + model merge\n\n1. At call time, the server reads your project's context file — `AGENTS.md` first, then `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, and Cursor/Cline/Windsurf rules files — walking up from the project root (the nearest directory wins; within a directory, `AGENTS.md` wins).\n2. It parses [the section conventions this server defines](./docs/context-conventions.md) — `## Trusted Sources`, `## Blocked Sources`, `## Decisions`, `## Project Context`, `## Freshness` — into ground-truth parameter values, whatever file they live in. No structured config required, and no section is: a file with just `## Trusted Sources` already improves ranking. File content becomes free-text search context only from an explicit `## Project Context` section (an opt-in head fallback exists: `YOU_AWARE_CONTEXT_FALLBACK=head`).\n3. The calling model may *also* populate the same parameters from its working context.\n4. The final API call uses whichever source produces the higher-quality parameter, with the deterministic file-read as the safety net: source lists are unioned, and a model-supplied `project_context` (which can fold in conversation-level context the file can't see) overrides the file-derived one.\n5. Both populated values are logged for ongoing quality measurement.\n\nOpt out of file reading entirely with `YOU_AWARE_READ_CONTEXT=off` (model-population only).\n\n### Retrieval memory (the write-back loop)\n\nReading context makes the first search good; remembering outcomes makes every search after it better. After the agent uses results, it calls `report_outcome` with the URLs it actually cited (every result set carries a one-line reminder, and the [companion skill](#companion-skill) reinforces it). The server keeps per-project domain stats locally — the store never leaves the machine; cited domains appear in telemetry like any other parameter — and puts them to work twice:\n\n- **Soft rank boost:** domains cited in 2+ sessions get a `preferred` tier between your explicit trusted sources and the rest, visible in the trace as `memory_boost`. Memory never touches the query or the native parameters — it is rank-only, reversible, and inspectable.\n- **Context-file suggestions:** past 3 citations across 2+ sessions, responses carry a concrete `context_suggestions` edit (\"add `- react.dev` to `## Trusted Sources` — cited 4 times across 3 sessions\") for the agent to apply. The server never edits your context file itself; a declined suggestion is never repeated, an applied one is detected and goes quiet.\n\nCited URLs are validated against what search actually returned this session, so a confused agent can't pump arbitrary domains into memory. Opt out with `YOU_AWARE_MEMORY=off`. The store lives under `~/.you-aware/projects/`, keyed by a local hash of the project path ([data handling](./docs/data-handling.md)).\n\n### Query compilation\n\nContext delivers the most value compiled into the query shape the workload actually has — lexical, operator-heavy:\n\n- `project_context` → vocabulary injection: stack disambiguation terms, topically relevant library names, and version numbers appended as quoted terms\n- **Decisions ledger** → negative vocabulary: rejected options become exclusion terms (a project that rejected `moment.js` gets `-moment` on date-library queries — and never on queries that mention moment themselves)\n- `trusted_sources` → always recall-preserving boost: the native boost parameter in `auto`/`native`, the client-side rank partition in `operators` — never a positive `site:` whitelist (an answer that lives off your trusted domains must still be findable)\n- `blocked_sources` → `-site:` negation operators or the filter parameter\n- `freshness` → date operators or the freshness parameter\n\nAlready-lexical queries (quotes, `site:`, `-term`) pass through untouched — the agent shaped them deliberately.\n\n**Multi-hop queries** get a structured `decomposition_request` back instead of results: the harness's frontier model is the rewriter (it produces sub-queries at zero marginal cost), never a server-side rewriter you pay for.\n\n### The trace\n\nEvery response includes an inspectable trace of the NL-to-lexical transformation — developers debug agents constantly, and if you can't see what `you-aware` did, you won't trust it:\n\n```\ntrace:\n  query_received: \"best way to handle date parsing in this project\"\n  query_compiled: \"typescript date parsing \\\"date-fns\\\" -moment\"\n  trusted_sources_boost: [react.dev, tanstack.com]\n  blocked_sources_applied: [w3schools.com]\n  memory_boost: [blog.example.com]\n  decisions_applied: [\"moment.js rejected → -moment\"]\n  project_context_chars: 1284\n  freshness: \"stable\"\n  pre_rank_top_3: [...]\n  post_rank_top_3: [...]\n  tier: \"keyed\"\n```\n\n## Configuration\n\nCLI flag > environment variable > default.\n\n| Flag | Env | Default | Purpose |\n|---|---|---|---|\n| `--api-key` | `YDC_API_KEY` (or `YOU_API_KEY`) | — | You.com Search API key; without one, the keyless hosted free tier is used |\n| `--hosted-mcp-url` | `YOU_AWARE_HOSTED_MCP_URL` | `https://api.you.com/mcp` | hosted MCP endpoint backing the keyless free tier |\n| `--project-root` | `YOU_AWARE_PROJECT_ROOT` | cwd | where to look for the context file (`AGENTS.md`, `CLAUDE.md`, rules files, …) |\n| `--harness` | `YOU_AWARE_HARNESS` | `unknown` | harness identifier stamped on Tier 2 telemetry events |\n| `--no-context-read` | `YOU_AWARE_READ_CONTEXT=off` | on | disable the deterministic file-read |\n| `--context-fallback head` | `YOU_AWARE_CONTEXT_FALLBACK=head` | off | opt in: without a `## Project Context` section, send the top 4 KB of the context file as `project_context` |\n| `--no-memory` | `YOU_AWARE_MEMORY=off` | on | disable per-project retrieval memory (boosts, suggestions, `report_outcome`) |\n| `--data-dir` | `YOU_AWARE_DATA_DIR` | telemetry dir | where the local (Tier 1) per-project memory store lives |\n| `--no-telemetry` | `YOU_AWARE_TELEMETRY=off` | on | opt out of Tier 2 telemetry |\n| `--telemetry-url` | `YOU_AWARE_TELEMETRY_URL` | — | remote Tier 2 sink (events always spool locally while telemetry is on) |\n| `--telemetry-dir` | `YOU_AWARE_TELEMETRY_DIR` | `~/.you-aware` | where the local Tier 2 JSONL spool lives |\n| `--compile-mode` | `YOU_AWARE_COMPILE_MODE` | `auto` | `auto` (native params + query vocabulary) · `operators` (portable `-site:`/`after:` compilation) · `native` (native params; query side keeps keywordization + ledger exclusions). Forced to `operators` on the keyless free tier, which has no native params |\n| `--fresh-window-days` | `YOU_AWARE_FRESH_WINDOW_DAYS` | `180` | recency window compiled from `freshness: fresh` in operators mode |\n| `--count` | `YOU_AWARE_COUNT` | `10` | results requested per call |\n| `--base-url` | `YOU_API_BASE_URL` | `https://api.ydc-index.io` | Search API endpoint |\n\nA sample `AGENTS.md` showing all section conventions is in [examples/AGENTS.md](./examples/AGENTS.md); client configs in [examples/client-config/](./examples/client-config).\n\n## Evaluation\n\nThe ablation-controlled eval harness (control passthrough vs. compiled lexical vs. compiled + decomposition) lives in [`eval/`](./eval), with uniform-weight UDCG@K as the primary metric (agents consume all K results — position-discounted metrics mis-measure the workload), plus citation precision/recall@10 and calls-per-task. See [eval/README.md](./eval/README.md).\n\n```bash\nYDC_API_KEY=… npm run eval -- --goldset eval/goldset.sample.jsonl --arm all\n```\n\nWithout `YDC_API_KEY`, the eval runs against the keyless hosted free tier — fine for smoke-testing the sample goldset, but its ~100 queries/day limit will truncate a real run.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck   # tsc --noEmit\nnpm test            # vitest (unit + e2e against an in-memory MCP client)\nnpm run build       # tsup → dist/\nnpm run inspect     # MCP Inspector against the built server\n```\n\n## Status & roadmap\n\n**v1 (this repo):** standalone stdio MCP; four parameters via deterministic file-read + model merge, plus query compilation; decisions-ledger compilation; inspectable trace; per-project retrieval memory with outcome reporting, rank boosts, and context-file suggestions; two-tier data posture with local-first telemetry; ablation eval harness; companion Agent Skill.\n\n## Who's behind this\n\nBuilt by [Brian Sparker](https://github.com/brainsparker) at [You.com](https://you.com) and published under his own `@brainsparker` npm scope, MIT-licensed. The interesting parts — context parsing, query compilation, the memory loop — are a thin deterministic layer you can read in an afternoon; the search itself runs on the You.com Search API (`SearchClient` in [`src/youcom.ts`](./src/youcom.ts) is the seam if you want to point the compiler somewhere else).\n\n**Later:** Cursor-rules / Cline-memory adapters and hosted variant (v2 GA) · `prior_decisions` native parameter, `workflow_stage`, smart context-file slicing, session anti-loop mechanic GA (v2.1) · multiple retrieval profiles, budget parameters, enterprise source policy (v2.2+).\n\n## License\n\nMIT © Brian Sparker\n","readmeFilename":"README.md","_rev":"1-bdce0103aa70d323eb21433036dee2fe"}