Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Proposal: site guide for agents — a declarative map of screens, tools and workflows (pre-navigation, complements page-scoped tools)

Abierto
  • ¿Algo no está bien?
#340 0 comentarios 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
html, json
Área
documentation, web-dev

Línea de trabajo

Read the related proposals #161, #166 and #242, then review the live example at https://app.ainote.dev/.well-known/agent-guide.json and the discovery options in the issue. The open questions concern scope, discovery, tool naming and whether to converge with other manifests, so the change is complete when the group agrees on those semantics and documents the resulting proposal.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

declarative-discovery

Summary

A site may publish a small, declarative site guide: a map of its screens, which WebMCP tools are useful where, and a few common workflows. It is a hint for planning, not a tool manifest and not a permission grant. The tools a page actually registers stay the source of truth.

A live example is running now: https://app.ainote.dev/.well-known/agent-guide.json, linked from every page with <link rel="agent-guide" href="/.well-known/agent-guide.json">.

Problem

WebMCP tools are registered by a loaded document, so an agent discovers them only after it reaches the right page. Keeping tools page-scoped is the right call, because tools depend on page state and authentication. But it leaves agents with no cheap answer to the questions they ask first:

  • What screens does this site have, and which one can do what I need?
  • Is the tool I want available everywhere, or only on one screen? Do I need to sign in?
  • What is the usual sequence of steps for a common task?

Agents fill the gap by crawling, which is costly and risky with side-effecting GETs, or by guessing from menus. Small on-device or on-prem models struggle the most. We see this with an 8B local model in a closed-network agent browser: it can work out menus, page kinds, forms and tables, but every inference step costs tokens and adds errors.

Repositories solved the same problem with AGENTS.md, and content sites with llms.txt and sitemap.xml. Interactive web apps need an equivalent that sits next to WebMCP.

Sketch

Discovery: <link rel="agent-guide"> and/or /.well-known/agent-guide.json. Same origin only.

{
  "version": 1,
  "site": { "name": "AI Note", "description": "Tasks, notes, calendar and a synced wiki" },
  "sections": [
    {
      "id": "tasks", "title": "Tasks", "url": "/tasks", "urlPattern": "/tasks*",
      "kinds": ["list", "search", "filter"],
      "tools": ["search_tasks", "list_tasks", "create_task"],
      "writes": ["create_task"],
      "requiresAuth": true
    },
    {
      "id": "task-detail", "title": "Task detail", "urlPattern": "/tasks/:id",
      "kinds": ["detail", "form"],
      "summary": "update_task / complete_task use the task in the URL when no task_id is given; delete_task always needs task_id.",
      "tools": ["update_task", "complete_task", "delete_task"],
      "writes": ["update_task", "complete_task", "delete_task"],
      "requiresAuth": true
    }
  ],
  "workflows": [
    {
      "id": "weekly-review", "title": "Summarise this week's open tasks",
      "steps": [
        { "section": "tasks", "tool": "list_tasks", "hint": "is_completed=false, start_date/end_date = this week" },
        { "section": "calendar", "tool": "get_calendar_events", "hint": "once per day with date=YYYY-MM-DD" }
      ]
    }
  ]
}

Semantics:

  • tools only names tools the page is expected to register. If the guide and the live registerTool() disagree, the page wins.
  • writes marks tools that change data, so an agent can plan confirmations up front. It does not replace per-call annotations such as readOnlyHint or user confirmation.
  • workflows are hints written by the site. They carry the kind of knowledge a tool description can't hold, such as "this tool refuses the note that is open in the editor; append from another page".

Security considerations

  • Treat the guide as untrusted, site-authored text, like tool descriptions. It must not grant permissions, change confirmation policy, or be placed in a system prompt as instructions.
  • Agents must not auto-navigate to every section. Navigation still follows the user's task and the browser's policies.
  • A malicious guide could steer an agent toward phishing-like flows within its own origin. The same-origin rule, the "page wins" rule and showing the origin in UI limit this.

What we learned writing the live example

We checked every path and tool name against the app's routes and WebMCP code. Getting the guide right took several review passes, and most corrections were behaviour that a tool's schema doesn't show: which tools act on "the current page", which need explicit IDs, and which accept a date but not a range. That is the information a planner most needs before choosing a page.

Related

  • #161 (Skills) puts workflow guidance on a loaded page through registerSkill(). A site guide is the static, pre-navigation counterpart and could reference skill names the same way it references tools.
  • #166 proposes a signed /.well-known/webmcp.json that describes tool schemas for pre-flight discovery. This proposal stays one level up: screens and workflows, no schemas, no capability claims.
  • #242 discusses an app-to-agent manifest.

Questions

  1. Is a site-level guide in scope for this group, or better as a separate companion note?
  2. <link rel> only, well-known only, or both?
  3. Should tools stay names only, or allow a schema hash so agents can detect drift?
  4. Should this converge with llms.txt or A2A/MCP "cards" into one well-known document?
Lenguaje dominante
Bikeshed
Estrellas
4.7k
Forks
328
Merge medio
2 d 15 h
PR fusionados (30 d)
16

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de webmachinelearning/webmcp

Todos los issues de webmachinelearning/webmcp

Issues similares

Más issues de Documentation

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.