convez.ai
MCP ServerAutomaçãoIntermediário
brainsparker

MCP Profiles

brainsparker/MCP-Profiles

Identidade reutilizável e agnóstica para agentes — gateway MCP com perfis

Ver no GitHub
InicialPluginScore · de 0 a 100

Gateway MCP que re-expõe ferramentas de agentes de IA com perfis independentes de modelo. Permite usar o mesmo modelo em diferentes agentes com identidades e contextos distintos, funcionando como camada de abstração para roteamento de tools baseado em perfil.

Instalação

$npx convez-ai brainsparker/MCP-Profiles

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
5
Contribuidores
1

Casos de uso

  • Executar o mesmo modelo LLM com diferentes perfis de agente (assistente técnico, redator, analista)
  • Isolar e compartilhar tools entre agentes mantendo contexto diferenciado
  • Implementar controle de acesso a ferramentas por perfil de agente

Veredito

MCP server bem pensado para arquiteturas multi-agente que precisam de isolamento de perfil sem duplicar modelos. Solução técnica elegante mas requer compreensão de Model Context Protocol e design de agentes.

README

A tradução para o português deste README ainda está na fila.

you-aware

Context-aware web search for AI agents — search that already knows what you're working on.

you-aware is an opinionated, installable MCP server that makes web search measurably better when the caller is an AI agent. It delivers the You.com Search API's context-aware parameters into the agent harnesses developers already use by reading the context the developer has already written — the project's AGENTS.md (or CLAUDE.md) — and compiling it into the lexical, operator-heavy query language production agents actually speak.

Your 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.

"best way to handle date parsing in this project"
        │
        ▼  reads AGENTS.md · merges model-supplied context · compiles
typescript date parsing "date-fns" -moment        + trusted/blocked/freshness params
        │
        ▼
ranked You.com results + an inspectable trace of exactly what ran

Install

The server is a single npx-runnable stdio binary — add it to any MCP client. In your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "you-aware": {
      "type": "local",
      "command": ["npx", "-y", "@youdotcom-oss/you-aware"],
      "enabled": true,
      "timeout": 60000,
      "environment": { "YOU_AWARE_HARNESS": "opencode" }
    }
  }
}

In Claude Code:

claude mcp add you-aware -- npx -y @youdotcom-oss/you-aware

Full client config examples (including the keyed variants) are in examples/client-config/.

One 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 — switches to the direct Search API with higher limits and the native context parameters. Add it to the environment block:

"YDC_API_KEY": "{env:YDC_API_KEY}"

(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.)

Data handling, in one sentence: search queries (received and compiled), populated search parameters, returned result URLs, and outcome signals (e.g. near-duplicate rate) flow to You.com under platform terms to improve agentic retrieval (opt out with YOU_AWARE_TELEMETRY=off); your raw AGENTS.md / CLAUDE.md, conversation history, and file paths never leave your machine. Details in docs/data-handling.md.

Companion skill

skills/you-aware/ is an Agent Skill 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/):

cp -r node_modules/@youdotcom-oss/you-aware/skills/you-aware .opencode/skills/

(or copy it straight from this repo). The skill body loads only when relevant — its at-rest cost is one description line.

What it does

The server exposes one tool — search — with a query plus the four context-aware parameters of the You.com Search API (the durable contract, documented in spec/search-parameters.md):

ParameterTypeRetrieval mechanic
trusted_sourcesstring[]per-domain boost at rank time
blocked_sourcesstring[]per-domain filter / hard demotion
project_contextstring (≤ 4 KB)context-conditioned ranking + lexical vocabulary injection
freshness"fresh" | "stable" | "any"recency window tuning

All parameters are optional. With everything omitted you get exactly today's Search API behavior — no regression.

Parameter population (Mechanism C)

  1. At call time, the server reads your project's AGENTS.md — or CLAUDE.md as a fallback — walking up from the project root (the nearest file wins; within a directory, AGENTS.md wins).
  2. It parses the documented section conventions — ## Trusted Sources, ## Blocked Sources, ## Decisions, ## Project Context, ## Freshness — into ground-truth parameter values. No structured config required: any AGENTS.md works (top-of-file content becomes project_context).
  3. The calling model may also populate the same parameters from its working context.
  4. 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.
  5. Both populated values are logged for ongoing quality measurement.

Opt out of file reading entirely with YOU_AWARE_READ_CONTEXT=off (model-population only).

Query compilation

Context delivers the most value compiled into the query shape the workload actually has — lexical, operator-heavy:

  • project_context → vocabulary injection: stack disambiguation terms, topically relevant library names, and version numbers appended as quoted terms
  • 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)
  • trusted_sources → site: constraints when narrowing is wanted (operators mode), or the boost parameter when recall must be preserved (auto, the default)
  • blocked_sources → negation operators or the filter parameter
  • freshness → date operators or the freshness parameter

Already-lexical queries (quotes, site:, -term) pass through untouched — the agent shaped them deliberately.

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.

The trace

Every 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:

trace:
  query_received: "best way to handle date parsing in this project"
  query_compiled: "typescript date parsing \"date-fns\" -moment"
  trusted_sources_boost: [react.dev, tanstack.com]
  blocked_sources_applied: [w3schools.com]
  decisions_applied: ["moment.js rejected → -moment"]
  project_context_chars: 1284
  freshness: "stable"
  pre_rank_top_3: [...]
  post_rank_top_3: [...]
  tier: "keyed"

Configuration

CLI flag > environment variable > default.

FlagEnvDefaultPurpose
--api-keyYDC_API_KEY (or YOU_API_KEY)—You.com Search API key; without one, the keyless hosted free tier is used
--hosted-mcp-urlYOU_AWARE_HOSTED_MCP_URLhttps://api.you.com/mcphosted MCP endpoint backing the keyless free tier
--project-rootYOU_AWARE_PROJECT_ROOTcwdwhere to look for AGENTS.md / CLAUDE.md
--harnessYOU_AWARE_HARNESSunknownharness identifier stamped on Tier 2 telemetry events
--no-context-readYOU_AWARE_READ_CONTEXT=offondisable the deterministic file-read
--no-telemetryYOU_AWARE_TELEMETRY=offonopt out of Tier 2 telemetry
--telemetry-urlYOU_AWARE_TELEMETRY_URL—remote Tier 2 sink (events always spool locally while telemetry is on)
--telemetry-dirYOU_AWARE_TELEMETRY_DIR~/.you-awarewhere the local Tier 2 JSONL spool lives
--compile-modeYOU_AWARE_COMPILE_MODEautoauto (native params + query vocabulary) · operators (portable site:/-site:/after: compilation) · native (params only). Forced to operators on the keyless free tier, which has no native params
--fresh-window-daysYOU_AWARE_FRESH_WINDOW_DAYS180recency window compiled from freshness: fresh in operators mode
--countYOU_AWARE_COUNT10results requested per call
--base-urlYOU_API_BASE_URLhttps://api.ydc-index.ioSearch API endpoint

A sample AGENTS.md showing all section conventions is in examples/AGENTS.md; client configs in examples/client-config/.

Evaluation

The ablation-controlled eval harness (control passthrough vs. compiled lexical vs. compiled + decomposition) lives in 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.

YDC_API_KEY=… npm run eval -- --goldset eval/goldset.sample.jsonl --arm all

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest (unit + e2e against an in-memory MCP client)
npm run build       # tsup → dist/
npm run inspect     # MCP Inspector against the built server

Status & roadmap

v1 (this repo): standalone stdio MCP; four parameters via Mechanism C plus query compilation; decisions-ledger compilation; inspectable trace; two-tier telemetry with near-duplicate-rate baseline collection; ablation eval harness; companion Agent Skill.

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+).

License

MIT © Brian Sparker

Ver o original no GitHub

Bom para

Relacionados