wp_search: buscar contenido del sitio
Ejecuta una búsqueda de WordPress sobre un tipo de contenido y devuelve los elementos coincidentes.
Argumentos
| Argumento | Valor por defecto | Significado |
|---|---|---|
query |
— | El término de búsqueda |
post_type |
post |
Cualquier tipo de contenido público |
status |
publish |
Estado de la entrada que se va a buscar |
page |
1 | Número de página |
per_page |
20 | Elementos por página, limitado a 1–100 |
Permisos
mcp:read y wp:content:read.
Buscar contenido publicado no requiere ninguna capacidad adicional. Buscar cualquier otro estado requiere edit_posts, o edit_pages para páginas.
Qué devuelve
La misma estructura que wp_get_posts: items y total, con cada elemento portando id, post_type, title, slug, status, date, modified, link y excerpt.
Sin content. Para leer una coincidencia en su totalidad, llama a wp_get_post con su ID.
Busca un tipo de contenido a la vez
A pesar del nombre, esta no es una búsqueda de todo el sitio. Busca dentro de un único tipo de contenido, por defecto post.
Para buscar en varios, llámala una vez por tipo:
Busca en entradas la palabra «warranty»; luego busca en páginas el mismo término y muéstrame ambos conjuntos de resultados.
Es la búsqueda de WordPress
La coincidencia es la propia de WordPress, con sus características conocidas: examina títulos, contenido y extractos, no hace coincidencias difusas y su ordenación por relevancia es básica.
Si el sitio ejecuta un plugin de mejora de búsqueda, los resultados del MCP pueden diferir de lo que ve un visitante: esta herramienta consulta WordPress directamente en lugar de pasar por la página de búsqueda del sitio.
No trates un resultado vacío como prueba de que un término no está en el sitio.
Su trabajo más útil: encontrar lo que estás a punto de cambiar
Antes de una edición cuyo objetivo conoces por su redacción y no por su ID:
Busca en páginas «0800 123 456» y dime cuáles lo contienen.
Eso convierte «actualiza el número de teléfono en todas partes» de una instrucción sin límites en una lista de IDs a los que puedes acotar el trabajo.
El mismo patrón sirve para encontrar afirmaciones desactualizadas, nombres de productos antiguos o un término que tienes previsto retirar.
Se aplica la paginación
per_page se limita a 100 y total informa del número real de coincidencias. Una búsqueda que devuelve muchos resultados necesita paginación, y un asistente que actuó sobre «todas las coincidencias» de una sola llamada actuó como mucho sobre cien.
Cómo usarla bien
Busca en entradas «spring campaign» y muéstrame los IDs y los títulos; luego detente.
Busca en el tipo de contenido «project» la palabra «Bilbao».
Busca en borradores «TODO».
Ese último ejemplo requiere la capacidad para contenido no publicado y es una auditoría realmente útil.
Lo que no hace
- Sin búsqueda entre tipos en una sola llamada.
- Sin contenido en los resultados.
- Sin búsqueda de taxonomías ni de metadatos.
- Sin reemplazo. Encontrar ocurrencias es una lectura; cambiarlas es una escritura independiente por elemento y debe acotarse a los IDs encontrados.
Problemas comunes
| Síntoma | Causa |
|---|---|
| Sin resultados para un término que ves en el sitio | El término está en un atributo de shortcode o en metadatos, no en el contenido buscable |
| Menos resultados de lo esperado | per_page se limita a 100; lee total |
| Faltan borradores | El estado por defecto es publish |
| Los resultados difieren de la búsqueda del sitio | Un plugin de búsqueda mejora la interfaz pública, no esta consulta |
pom_ai_mcp_forbidden |
Buscar contenido no publicado sin la capacidad correspondiente |