Referencia de tools

Cada tool del servidor MCP de Vidext Operator — argumentos, límites, valores por defecto, resultados y cuál llamar para cada tarea.

El servidor expone tres tools. Todas son lecturas deterministas que no ejecutan ningún modelo, y todas llevan las mismas anotaciones:

Anotación	Valor
`readOnlyHint`	`true`
`destructiveHint`	`false`
`idempotentHint`	`true`
`openWorldHint`	`false`

Qué tool para cada tarea

Tarea	Llamada
Encontrar qué dicen las fuentes de la organización sobre algo	`search_knowledge` y después `read_knowledge_source` sobre el `handle` de un resultado
Encontrar un módulo, o comprobar si está en vivo	`list_modules`

No disponible por MCP: cursos, las escenas o el guion de un módulo, generar o publicar, y el progreso de los participantes. Hazlo en la aplicación de Vidext.

Convenciones

Los argumentos son estrictos. Cada tool acepta solo los argumentos listados aquí. Una tool desconocida, un argumento obligatorio ausente, un argumento de más o un valor fuera de sus límites se rechaza con el error JSON-RPC InvalidParams (-32602). Corrige la llamada; repetirla sin cambios no puede funcionar.
Selector de organización. Todas las tools aceptan además organizationSlug y organizationId (strings de 1–255 caracteres). Omite los dos para usar la organización ligada al token. Consulta ámbito de organización.
Resultados. Una llamada correcta devuelve su objeto JSON dos veces: como texto en content[0].text y como structuredContent. Un fallo devuelve isError: true con un objeto de error, salvo en las dos tools de conocimiento, que informan de la mayoría de fallos dentro del propio resultado con success: false. Consulta Errores y límites.
IDs. moduleId es un UUID, tal como lo devuelve list_modules.

search_knowledge

Busca en el conocimiento de la organización y devuelve fragmentos ordenados por relevancia, cada uno con un handle opaco para read_knowledge_source.

Busca en:

el perfil de la organización (org_profile);
el catálogo de fuentes, el título y los metadatos de cada fuente que ha añadido la organización (source_registry);
el texto procesado de esas fuentes (source_content);
una wiki heredada de la organización (generated_org_wiki), cuando una organización aún la tiene. Se lee, pero ya no se actualiza.

Las fuentes se añaden en la aplicación, y una fuente se puede buscar en cuanto está procesada.

Prop

Type

Resultado. success: true, mode: "search", status ("indexed", o "empty" cuando no había nada en lo que buscar), la query, matchedResults y results, ordenados por relevancia. Cada resultado lleva:

Campo	Significado
`handle`	Handle opaco que pasar a `read_knowledge_source`. No lo construyas ni lo edites.
`sourceKind`	Uno de los tipos de arriba.
`title`, `path`, `documentId`	Qué es la coincidencia. `documentId` se rellena en las fuentes.
`excerpt`, `excerptOffset`, `excerptEndOffset`, `excerptTruncated`	El pasaje que coincide y dónde está en el texto de la fuente.
`suggestedReadOffset`	Cuando aparece, la posición de la sección que mejor coincide. Empieza `read_knowledge_source` ahí.
`score`, `relevance`, `matchedFields`	Cómo se ordenó la coincidencia.
`originalContentLength`, `sourceMetadata`	Tamaño del texto completo y los metadatos de catálogo de la fuente.

El resultado lleva además contadores de diagnóstico (como retrievalTrace). Describen cómo se ejecutó la búsqueda; no construyas sobre ellos.

Fallos dentro del resultado. success: false con status: "invalid" (una consulta vacía o demasiado vaga) o status: "unavailable" (no se pudo leer el conocimiento; reason: "timeout" cuando se agotó el plazo de 15 segundos). Las búsquedas no disponibles se pueden reintentar.

read_knowledge_source

Lee un tramo acotado de una fuente, a partir de un handle que devolvió search_knowledge. Las rutas arbitrarias y los handles caducados o alterados se rechazan, y el acceso a la organización se vuelve a comprobar.

Prop

Type

Resultado. success: true, mode: "read", el handle, sourceKind, title, path, documentId, sourceMetadata y el tramo:

Campo	Significado
`content`	El texto, en markdown.
`contentOffset`	Dónde empieza el tramo.
`contentTruncated`	`true` cuando sigue habiendo texto.
`nextOffset`	Aparece cuando sigue habiendo texto: pásalo como `offset` para continuar.
`remainingChars`, `originalContentLength`	Lo que queda y la longitud total.

Fallos dentro del resultado. success: false con status:

"rejected": el handle no salió de search_knowledge para esta organización, o ya no coincide con la fuente. Vuelve a buscar.
"missing" o "empty": la fuente, o su texto procesado, ya no está.
"unavailable": no se pudo leer el conocimiento en este momento (reason: "timeout" tras 15 segundos). Reintenta.
"invalid": no se pasó ningún handle.

list_modules

Lista los módulos de la organización, primero los actualizados más recientemente. Admins y miembros ven todos los módulos de la organización.

Prop

Type

Resultado.

{
  "organizationId": "…",
  "modules": [
    {
      "id": "018f1111-2222-7333-8444-555555555555",
      "name": "Incident response",
      "description": "…",
      "color": "…",
      "published": true,
      "createdAt": "…",
      "updatedAt": "…"
    }
  ]
}

published es true mientras el módulo está en vivo: su curso está publicado y los participantes pueden verlo. Un módulo generado pero no en vivo, o todavía en borrador, tiene published: false. El resultado no tiene cursor; devuelve como mucho limit módulos, así que acota con search para encontrar los más antiguos. No incluye el curso del módulo.

Referencia de tools

Qué tool para cada tareaCopy Anchor Link

ConvencionesCopy Anchor Link

search_knowledgeCopy Anchor Link

read_knowledge_sourceCopy Anchor Link

list_modulesCopy Anchor Link

On this page

Qué tool para cada tarea

Convenciones

search_knowledge

read_knowledge_source

list_modules