Consultar el schema de una obra con el recurso

MCP no son solo herramientas (tools) — también tiene recursos (resources). El recurso schema es uno clave: le dice a la IA los permisos exactos de una obra.

Cómo se usa

Resource URI: slima://books/{book_token}/schema

Los clientes compatibles con MCP pueden leer recursos directamente — sin necesidad de llamar a una herramienta.

# Pseudocódigo (depende de la API de recursos del cliente)
schema = read_resource("slima://books/bk_xxx/schema")

Lo que devuelve

{
  "book_token": "bk_xxx",
  "book_type": "script",
  "studio_label": "Script Studio",
  "mcp_capabilities": {
    "readable_paths": "Any path within the book tree ...",
    "writable_paths": [".script_studio/planning/**/*"],
    "writable_exceptions": [".script_studio/planning/.initialized"],
    "readonly_paths": [
      ".script_studio/series.json",
      ".script_studio/seasons/**/season.json",
      ".script_studio/seasons/**/episodes/**/episode.json",
      ".script_studio/seasons/**/scenes/*.scene",
      ".script_studio/characters/**/*.character",
      ".script_studio/locations/**/*.location",
      ".script_studio/storylines/**/*.storyline",
      ".script_studio/notes/**/*.note",
      ".script_studio/planning/.initialized"
    ],
    "write_access_note": "..."
  },
  "ai_file_policy": {
    "writable": [".md", ".markdown", ".txt"],
    "field_level_tools": {
      ".beats": "update_beat_board",
      ".timeline": "update_timeline",
      ".script": "update_script",
      ".map": "update_relationship_map",
      ".geomap": "update_world_map"
    },
    "readonly": [".character", ".location", ".json", ".yaml", ".yml"],
    "authority": "get_capabilities"
  },
  "structured_file_types": { "*.scene": "...", "*.character": "..." },
  "policy_source": "Rails: Mcp::FileOperationService#validate_studio_write_path!"
}

Por qué existe este recurso

Escribir un *.scene va a fallar (400) — pero llamar primero a schema te permite saber de antemano que esa ruta es de solo lectura, sin gastar una llamada a la API en vano.

Flujo de trabajo recomendado para la IA

1. list_books → obtener book_token
2. read_resource(slima://books/{token}/schema) → obtener las reglas
3. Planificar lecturas / escrituras de forma segura según las reglas
4. Ejecutar

Algunos clientes compatibles con MCP exponen los recursos automáticamente a la IA — la IA no necesita llamarlos de forma explícita.

Schema de una obra del Estudio de escritura

{
  "book_token": "bk_xxx",
  "book_type": "book",
  "studio_label": "Writing Studio",
  "mcp_capabilities": {
    "writable_paths": ["**/*"],
    "readonly_paths": []
  },
  "ai_file_policy": {
    "writable": [".md", ".markdown", ".txt"],
    "field_level_tools": {
      ".beats": "update_beat_board",
      ".timeline": "update_timeline",
      ".script": "update_script",
      ".map": "update_relationship_map",
      ".geomap": "update_world_map"
    },
    "readonly": [".character", ".location", ".json", ".yaml", ".yml"],
    "authority": "get_capabilities"
  },
  "structured_file_types": {}
}

Rutas y tipos de archivo son dos preguntas distintas. No las leas como una sola.

mcp_capabilities responde a la de rutas: en un libro del Estudio de escritura, cualquier ruta es escribible.

ai_file_policy responde a la de tipos, y se aplica a los dos estudios. Las herramientas genéricas de escritura (write_file, edit_file, append_to_file, delete_file) solo tocan prosa: .md, .markdown, .txt. Los cinco tipos que hay bajo field_level_tools se editan campo a campo con la herramienta que ahí se nombra; una escritura del documento entero se rechaza, porque deja caer las partes del archivo que el modelo nunca vio. Escribir en ellos requiere un plan de pago; leerlos no. Los tipos bajo readonly no se pueden escribir de ninguna manera.

La excepción que conviene recordar es create_file: sobre un tipo estructurado crea un documento vacío con la forma correcta e ignora el contenido que envíes, así que primero creas y luego rellenas con la herramienta.

Este bloque viaja con el cliente y puede quedarse atrás respecto a un despliegue del servidor. Cuando los dos no coincidan, manda get_capabilities: eso es lo que dice el campo authority.

Relacionado

• Comportamiento de MCP según el estudio
• Protecciones estructuradas de Script Studio
• Auto-alojar con Cloudflare Worker