Cómo construiría desde cero un sitio personal legible para agentes

Si construyera desde cero un sitio personal que los agentes pudieran consultar, empezaría por el modelo de datos.

La página importa, pero es una de varias interfaces.

El objetivo es más amplio:

Website: for humans
API: for software
MCP: for AI agents

Una web para las personas, una API para el software y MCP para los agentes de IA.

Para que eso funcione, el sitio necesita contenido estructurado antes de necesitar un acabado visual.

Paso 1: define las entidades

Empieza por decidir de qué está hecho tu sitio personal.

Para el sitio de un desarrollador usaría:

perfil;
proyectos;
productos;
notas;
habilidades;
enlaces;
etiquetas;
tecnologías.

Piensa primero en los objetos que vas a representar. El proyecto es una entidad que después aparecerá en una tarjeta. La nota tiene datos y contenido que luego se mostrarán en una página. El producto existe antes de decidir su sección de presentación. Ese cambio facilita lo demás.

Paso 2: elige la fuente de verdad

Puede ser:

archivos MDX;
archivos JSON;
una base de datos;
un CMS sin interfaz de presentación propia;
un directorio local de contenido.

Para un sitio personal me gusta MDX con frontmatter. Permite conservar los metadatos estructurados y los textos largos en el mismo lugar.

Por ejemplo:

---
title: "ResistGate"
slug: "resistgate"
status: "active"
tags:
  - chrome-extension
  - productivity
tech_stack:
  - TypeScript
  - Chrome Extension Manifest V3
---

El frontmatter alimenta las listas, filtros, respuestas de la API y resultados de las herramientas MCP. El cuerpo alimenta la página que lee una persona.

Paso 3: diseña la API pública

Cuando exista el modelo de contenido, exponlo mediante endpoints sencillos.

Empezaría por:

GET /api/v1/me
GET /api/v1/projects
GET /api/v1/projects/:slug
GET /api/v1/products
GET /api/v1/products/:slug
GET /api/v1/notes
GET /api/v1/notes/:slug

Usa nombres previsibles y filtros que la gente vaya a utilizar:

tag;
status;
featured;
topic;
category;
limit;
offset;
locale.

No compliques la primera versión. El objetivo es que resulte fácil obtener contexto público.

Paso 4: usa un formato de respuesta uniforme

Todos los endpoints deberían devolver una estructura previsible.

Para las colecciones:

{
  "api_version": "1.0.0",
  "ai_summary": "Found 3 active products.",
  "meta": {
    "total": 3,
    "returned": 3,
    "locale": "en",
    "generated_at": "2026-06-05T00:00:00.000Z"
  },
  "data": []
}

Para un solo elemento, sigue el mismo patrón con un objeto en data.

Esto ayuda al software convencional y a los sistemas de IA. El software recibe campos estables; el modelo recibe un resumen de lo que se devolvió.

Paso 5: añade validación

Añádela pronto, antes de acumular decenas de publicaciones y proyectos.

Valida:

campos obligatorios;
formato de los slugs;
categorías válidas;
estados válidos;
formato de fechas;
formato de URL;
campos de listas;
longitudes máximas de metadatos.

La validación protege todas las interfaces. Una nota incorrecta no debería convertirse en silencio en una página rota, una respuesta de API incorrecta y un resultado MCP que no sirve.

Paso 6: añade herramientas MCP

Una vez que exista la API, añade herramientas MCP sobre el mismo contenido.

Un punto de partida:

get_profile
get_projects
get_project
get_products
get_product
get_notes
get_note

Empieza con herramientas de solo lectura. Para un sitio personal suele bastar.

El agente debería poder responder:

¿Quién es esta persona?
¿Qué ha construido?
¿Qué productos ha publicado?
¿Sobre qué ha escrito?
¿Qué proyectos encajan con este tema?
¿Qué trabajo sigue activo?

Eso da contexto útil a los agentes sin concederles poder innecesario.

Paso 7: escribe descripciones útiles

El modelo usa las descripciones para decidir cuándo llamar a una herramienta.

Una descripción débil:

Gets projects.

Una más útil:

Returns public projects from this personal hub. Use when the user asks what this person has built, wants examples by technology or tag, or needs project evidence for evaluation.

La segunda explica que devuelve proyectos públicos y que debe usarse cuando alguien pregunta qué se ha construido, busca ejemplos por tecnología o necesita pruebas para evaluar el trabajo.

La descripción debería aclarar:

qué devuelve la herramienta;
cuándo usarla;
qué entradas importan;
qué límites tiene.

Si el modelo no entiende la herramienta, difícilmente podrá usarla bien.

Paso 8: añade documentación

Crea una página permanente:

/api

O bien:

/developers

Esa página debería incluir:

descripción de la API;
lista de endpoints;
ejemplos de respuesta;
descripción de MCP;
lista de herramientas;
ejemplos de peticiones;
límites de uso;
notas de atribución;
límites de seguridad.

Las publicaciones ayudan a darlo a conocer. La documentación deja una referencia estable que se puede consultar y comprobar.

Paso 9: añade ejemplos

Los ejemplos muestran para qué sirve el sistema.

Para la API:

GET /api/v1/projects?tag=ai
GET /api/v1/products?featured=true
GET /api/v1/notes?topic=agents

Para MCP:

Summarize active products from this personal hub.

Este pide resumir los productos activos del sitio.

Find projects that demonstrate TypeScript and AI product experience.

Este busca proyectos que demuestren experiencia con TypeScript y productos de IA.

Create a recruiter brief from the profile, products, and projects on this personal hub.

Este pide un resumen para un reclutador a partir del perfil, los productos y los proyectos.

Los ejemplos ayudan a las personas a entender el propósito del sistema y a los agentes a producir respuestas más útiles.

Paso 10: mantén pequeño el alcance de seguridad

Empieza con contexto público de solo lectura. No des acceso de escritura a los agentes, no expongas datos de administración ni incluyas borradores. Tampoco devuelvas secretos, analíticas, facturación o contactos privados.

Eso permite que los agentes consulten el sitio sin añadir accesos innecesarios.

El orden de construcción

Lo construiría en este orden:

Definir las entidades.
Crear el contenido estructurado.
Validarlo.
Renderizar las páginas para las personas.
Exponer los endpoints REST.
Añadir las herramientas MCP.
Escribir la documentación.
Añadir ejemplos y demostraciones.

Empezaría por el modelo porque la página es una salida, la API es otra y el servidor MCP es otra.

La base es estructurar el trabajo para que puedan entenderlo las personas, el software y los agentes.