Skip to main content
Glama
Bidcomsrl

bitacora-mcp

by Bidcomsrl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

bitacora-mcp

MCP server en NestJS para crear, versionar, recuperar y publicar presentaciones HTML dirigidas a directivos y PO de Bidcom. Los decks se persisten versionados y se publican en Google Workspace vía Google Apps Script, con una URL estable, editable y con historial.

Qué hace

  • 18 tools para crear, editar, versionar, buscar, comparar, validar y publicar presentaciones HTML (ver tabla completa más abajo).

  • Dos backends de store, switch via env vars:

    • git (default): filesystem local, single-user — ideal para desarrollo

    • mongodb: multi-user, AWS-ready — para deployment centralizado

  • OAuth de Google Workspace restringido a bidcom.com.ar (login real, no texto libre). Sesiones persistidas en SQLite o MongoDB.

  • Publicación en Apps Script con idempotencia por commit + access, reintentos con backoff exponencial, y historial completo de publicaciones.

  • Validación pre-deploy que unifica chequeos de sandbox + estructura HTML.

Related MCP server: marp-agent-mcp

Prerequisitos

  • Node 22 (usa --env-file nativo, sin dependencia de dotenv)

  • MongoDB 7+ (solo si vas a usar DECK_STORE=mongodb o OAUTH_STORE=mongodb)

  • Docker (para levantar MongoDB local fácilmente)

Setup inicial

git clone <repo> bitacora-mcp
cd bitacora-mcp
npm install
npm run build

Configuración

Copiá el template de environment y llená los valores:

cp .env.example .env

Editá .env con los valores correspondientes (el archivo está en .gitignore, no se commitea). Los campos obligatorios dependen del modo de uso:

Modo stdio (local, sin login de Google)

Para usar desde Claude Desktop local sin login de Google, no hace falta .env ni credenciales. Las tools corren con owner libre (texto):

npm start          # levanta el server por stdio

Modo HTTP (con login de Google Workspace)

Requiere credenciales de OAuth en GCP (ver más abajo). Llená en .env:

GOOGLE_WORKSPACE_CLIENT_ID=<client-id>
GOOGLE_WORKSPACE_CLIENT_SECRET=<client-secret>
JWT_SECRET=<openssl rand -hex 32>
npm run start:http # levanta el server por HTTP en http://localhost:3030

Store: git (default) o MongoDB

# Para usar MongoDB (multi-user, AWS-ready):
DECK_STORE=mongodb
OAUTH_STORE=mongodb
MONGODB_URI=mongodb://localhost:27017/bitacora

Si no seteás estas vars, el server usa git + SQLite (filesystem local).

Credenciales de Google (setup una sola vez)

Hay dos OAuth clients distintos en el mismo proyecto GCP:

1. OAuth client "Desktop app" — para deployar en Apps Script

  1. Google Cloud Console → proyecto (nuevo o existente)

  2. Habilitar Google Apps Script API (APIs & Services → Library)

  3. Credentials → Create Credentials → OAuth client ID → Desktop app

  4. Descargar JSON → ~/.bitacora-google/oauth-client.json

  5. Correr el consent flow:

    npm run build
npm run google:authorize

    Abre el navegador, pedí consent, cachea el refresh token en ~/.bitacora-google/token.json. Se refresca solo.

2. OAuth client "Web application" — para login de usuarios (modo HTTP)

  1. En el mismo proyecto GCP → Credentials → Create Credentials → OAuth client ID

  2. Tipo: Web application (no Desktop app — ese no tiene redirect URIs editables)

  3. Authorized redirect URIs: http://localhost:3030/auth/callback

  4. Anotá Client ID y Client Secret → van en .env:

    GOOGLE_WORKSPACE_CLIENT_ID=<este>
GOOGLE_WORKSPACE_CLIENT_SECRET=<este>

Levantar MongoDB local (para modo MongoDB)

docker run -d --name bitacora-mongo -p 27017:27017 mongo:7

MongoDB queda en mongodb://localhost:27017. Seteá en .env:

DECK_STORE=mongodb
OAUTH_STORE=mongodb
MONGODB_URI=mongodb://localhost:27017/bitacora

Pruebas locales

Smoke test (sin credenciales de Google)

Corre las 18 tools end-to-end contra un cliente de Apps Script mockeado:

# Modo git (default)
npm run smoke

# Modo MongoDB
DECK_STORE=mongodb MONGODB_URI=mongodb://localhost:27017/bitacora-smoke npm run smoke

Los 48 tests cubren: create → update → rollback → deploy → unpublish → list_deployments, diff, search, archive, validate, fragment update, y cargas chunked/from-file.

Probar con MCP Inspector

  1. Levantá el server HTTP:

    npm run build
npm run start:http

  2. En otra terminal, abrí el Inspector:

    npx @modelcontextprotocol/inspector

  3. En el Inspector: Add Server → Streamable HTTP → URL: http://localhost:3030/mcp

  4. Al llamar una tool, se abre el navegador para login de Google Workspace. Logueate con tu cuenta @bidcom.com.ar.

  5. Las tools van a usar tu email real como owner automáticamente.

Probar con Claude Desktop

  1. Configurá claude_desktop_config.json (en ~/Library/Application Support/Claude/ en macOS):

    {
  "mcpServers": {
    "bitacora-remote": {
      "url": "http://localhost:3030/mcp"
    }
  }
}

  2. Reiniciá Claude Desktop (Cmd+Q y volver a abrir).

  3. Pedile a Claude: "Mostrame las presentaciones que tengo" — debería disparar el flujo OAuth la primera vez y listar tus decks.

Sesión persistente: si ya te logueaste desde el Inspector, Claude Desktop reusa esa sesión (SQLite/MongoDB la persiste). Para forzar el flujo OAuth desde cero, borrá el store de sesiones: rm ~/.bitacora-store/oauth.db (SQLite) o limpiá las colecciones oauth_* en MongoDB.

Conectar a Claude Desktop (modo stdio, sin login)

Para uso local sin login de Google, stdio es más simple:

{
  "mcpServers": {
    "bitacora": {
      "command": "node",
      "args": ["/RUTA/ABSOLUTA/bitacora-mcp/dist/main.js"],
      "env": {
        "DECK_STORE_DIR": "/RUTA/ABSOLUTA/deck-store",
        "DECK_STORE": "git"
      }
    }
  }
}

O con MongoDB:

{
  "mcpServers": {
    "bitacora": {
      "command": "node",
      "args": ["/RUTA/ABSOLUTA/bitacora-mcp/dist/main.js"],
      "env": {
        "DECK_STORE": "mongodb",
        "MONGODB_URI": "mongodb://localhost:27017/bitacora"
      }
    }
  }
}

Tools (18)

Versionado (13)

Tool

Qué hace

presentation_create

Crea un deck y lo guarda versionado. Devuelve id + version. Con partial: true, reserva el id y guarda el HTML recibido como primer chunk sin comitear nada — hay que cerrar con presentation_append.

presentation_create_from_file

Igual que presentation_create, pero lee el HTML de un archivo local (path absoluto) en vez de tomarlo como argumento. Para decks grandes o con base64 embebido.

presentation_append

Agrega un chunk de HTML a una carga iniciada con presentation_create({partial: true}). done: true en el último chunk cierra, valida y comitea el deck completo.

presentation_update

Nueva versión con HTML y/o metadata nuevos. Con fragment: true, inyecta el HTML antes de </body> sin reemplazar el documento completo.

presentation_update_from_file

Igual que presentation_update, pero lee el HTML nuevo de un archivo local.

presentation_get

HTML + metadata en HEAD o en un version histórico. La descripción le pide al asistente mostrar el html como Artifact.

presentation_list

Lista los decks, filtrable por owner. Excluye archivados por defecto (includeArchived: true para verlos).

presentation_list_versions

Historial de commits/versiones de un deck.

presentation_rollback

Vuelve a un version anterior creando una versión nueva (no destructivo).

presentation_search

Búsqueda full-text sobre título, tags y contenido HTML. Devuelve matches con snippet y matchedIn.

presentation_diff

Dif textual + visual HTML side-by-side entre dos versiones. Resuelve "¿qué cambió entre la versión que aprobó el director y la actual?".

presentation_archive

Soft-delete no destructivo: marca el deck como archivado, lo saca de list/search.

presentation_unarchive

Restaura un deck archivado.

presentation_validate

Reporte estructurado pre-deploy: DOCTYPE, mixed content, <base target>, charset, viewport, scripts inline, event handlers, múltiples <body>. Devuelve canDeploy.

Publicación (5)

Tool

Qué hace

presentation_deploy

Publica un version (default HEAD) como web app de Apps Script. access opcional controla quién puede verla (MYSELF/DOMAIN/ANYONE/ANYONE_ANONYMOUS, default DOMAIN). Idempotente por commit + access.

presentation_get_deployment

Devuelve el estado de publicación actual (commit, scriptId, deploymentId, url).

presentation_list_deployments

Historial completo de publicaciones por deck (incluye despublicadas), para auditoría.

presentation_unpublish

Despublica: borra el deployment de Apps Script (la URL deja de servir), marca el registro con unpublishedAt. No destructivo.

presentation_get_deployment

Estado de publicación actual de un deck.

Decks grandes

Dos problemas distintos, dos soluciones distintas:

1. El HTML ya existe como archivo en disco → create_from_file / update_from_file. El server lo lee directo del filesystem, byte a byte. El modelo nunca reproduce el contenido, así que no importa cuán grande sea ni si tiene base64 embebido.

2. El HTML lo está generando el modelo y no entra en una sola tool call → create({partial: true}) + append por chunks. Recién en done: true se normaliza y comitea, igual que un create de una sola llamada.

Arquitectura

src/
  core/                    # DeckService (normalize/escHtml), DeckValidateService
  store/                   # DeckStore interface + GitSpecStore | MongoDeckStore
  auth/                    # WorkspaceDomainGuard, SqliteOAuthStore, MongoOAuthStore
  presentations/           # PresentationsService + Controller (13 tools), PendingUpload
  deployer/               # AppsScriptClient (real/mock), SandboxTransform, DeployerService (5 tools)
  shared-tools.module.ts  # controllers + providers, importado por stdio y HTTP
  app.module.ts            # bootstrap stdio (sin auth)
  http-app.module.ts       # bootstrap HTTP (con OAuth de Workspace)
  main.ts / main-http.ts   # entry points

Dos modos de store, dos modos de auth:

Componente

Default (local)

MongoDB (multi-user/AWS)

Decks

GitSpecStore (filesystem)

MongoDeckStore (colección decks)

OAuth sessions

SqliteOAuthStore (archivo)

MongoOAuthStore (colecciones oauth_*)

Switch via DECK_STORE y OAUTH_STORE env vars.

Notas de stack

  • @rekog/mcp-nest v2 — API McpStrategy + @McpController

  • @rekog/mcp-nest-auth v2 — servidor de autorización OAuth 2.1/MCP embebido (McpAuthModule + GoogleOAuthProvider)

  • Node 22 con --env-file=.env nativo (sin dotenv)

  • mongodb driver oficial (sin Mongoose ni ODM)

  • simple-git para el store git, better-sqlite3 para el store de sesiones

  • zod v4 para schemas de las tools

  • TypeScript 7.x, module/moduleResolution: nodenext

Available Tools

8 tools
presentation_createA

Crea una presentación HTML y la guarda versionada en el store. No la publica (deploy es Fase 2). Devuelve id y versión (commit SHA).

ParametersJSON Schema
NameRequiredDescriptionDefault
htmlYesHTML de la presentación. Puede ser un documento completo o un fragment.
tagsNoEtiquetas opcionales.
ownerNoIdentidad dueña del deck. En Fase 1 es libre; en Fase 3 sale del OAuth.local
titleYesTítulo de la presentación.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses key behaviors: the presentation is saved versioned (implying each call creates a new version/commit) and not published, and it returns id and commit SHA. This adds value beyond the schema, though it omits details like authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise sentence that front-loads the main action, includes the key boundary (no deploy), and states the return value. Every phrase earns its place with no redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description adequately covers the essential return values (id and commit SHA) and the phase distinction. It could further clarify handling of duplicate titles, but 'versionada' strongly implies new-version creation, making it sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for all four parameters (e.g., html can be a full document or fragment). The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates an HTML presentation and saves it versioned in the store. It explicitly distinguishes itself from the sibling presentation_deploy by stating 'No la publica (deploy es Fase 2)', making the scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: it creates and versions, and notably excludes deployment by mentioning deploy is Phase 2. This implies when to use this tool versus deploy, but it does not explicitly name alternatives like presentation_update for modifying existing presentations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

presentation_deployA

Publica una versión (commit) de una presentación como web app de Apps Script y devuelve su URL. Idempotente por versión: si ese commit ya está publicado, devuelve la URL existente sin volver a deployar.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesID del deck a publicar.
versionNoSHA de commit a publicar. Si se omite, publica el HEAD actual.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden for behavioral disclosure. It clearly states idempotency by version and the behavior of returning the existing URL without redeploying. This adds meaningful context about side effects and repeatability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wasted words. It front-loads the core action and result, then adds the idempotency behavior. Perfectly sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, behavior, and output (URL), which is sufficient for a simple deploy action. No output schema exists, but the URL return is stated. It lacks error conditions or prerequisites, but these are not critical for a clear understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are already well-documented. The description adds no extra semantic detail beyond what the schema provides for the 'version' and 'id' parameters, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Publica') and resource ('una presentación como web app de Apps Script'), clearly stating the action and return value (URL). It distinguishes from siblings like presentation_get_deployment and presentation_rollback by focusing on the deployment action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (to publish a version as a web app) but does not explicitly state when to use this tool versus alternatives like presentation_get_deployment or presentation_rollback. There are no exclusions or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

presentation_getA

Devuelve el HTML y la metadata de una presentación. Por defecto la versión actual (HEAD); con "version" (SHA) devuelve esa versión histórica.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesID del deck.
versionNoSHA de commit. Si se omite, devuelve la versión actual (HEAD).

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It explains default HEAD behavior, historical version retrieval, and return content (HTML and metadata), which is useful. However, it does not specify what 'metadata' includes, error behavior for invalid IDs/SHAs, or any authentication/permission requirements, leaving gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loading the main purpose and then adding the version-specific behavior. Every sentence serves a purpose with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (two params, no nested objects, no output schema), the description adequately covers the primary purpose, return type, and version selection behavior. It could be more complete by detailing the metadata structure or error conditions, but it is sufficient for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% because both id and version have descriptions in the input schema. The description largely repeats the version param semantics already present in the schema ('SHA', 'HEAD'), adding minimal extra meaning beyond what the structured schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Devuelve') and a clear resource ('el HTML y la metadata de una presentación'), while also distinguishing version behavior (HEAD vs a historical SHA). This clearly differentiates it from siblings like presentation_list_versions, which lists versions, and presentation_get_deployment, which fetches deployment info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states when to use the version parameter: omit it for the current HEAD, or provide a SHA for a historical version. It gives clear context, but it does not explicitly mention when not to use this tool or point to alternatives among the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

presentation_get_deploymentA

Devuelve el estado de publicación actual de una presentación (commit, scriptId, deploymentId, url).

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesID del deck.

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. It only states that it returns data; it does not explicitly confirm a read-only operation, mention permissions, side effects, or error conditions. The verb 'Devuelve' hints at read-only but is not sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that directly states the purpose and the returned fields. Every word earns its place, and it is front-loaded with the key verb and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete enough for a simple one-parameter read tool: it lists the return fields and makes the purpose clear. However, it lacks context about prerequisites (e.g., presentation must exist) or potential error/failure scenarios, which would warrant a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage for the single parameter 'id' with a description 'ID del deck.' The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Devuelve' (returns) and identifies the resource as 'el estado de publicación actual de una presentación', further detailing the exact fields (commit, scriptId, deploymentId, url). This clearly distinguishes it from sibling tools like presentation_deploy or presentation_get.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when one needs to check the current publication status of a presentation, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or comparisons to sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

presentation_listB

Lista las presentaciones guardadas, opcionalmente filtradas por dueño.

ParametersJSON Schema
NameRequiredDescriptionDefault
ownerNoFiltrar por dueño (opcional).

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that it lists saved presentations with an optional filter, but does not disclose whether it is a read-only operation, what the return format looks like, pagination behavior, or any side effects. This is minimal and leaves significant behavioral ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence in Spanish, front-loading the core action (list presentations) and the optional filter. There is no extraneous information, making it appropriately sized and structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter, the description is not fully complete given the absence of an output schema and annotations. It does not explain what the returned list contains, whether it is ordered, how 'owner' filtering works, or how this differs from presentation_list_versions. This leaves gaps for an agent trying to use the tool confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single 'owner' parameter, with the schema already stating it filters by owner. The tool description merely repeats this ('opcionalmente filtradas por dueño') without adding additional semantic meaning, such as the format of the owner value or how filtering behaves. Baseline of 3 is appropriate given full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb (Lista) and resource (presentaciones guardadas), clearly indicating it lists saved presentations. However, it does not differentiate itself from the sibling tool presentation_list_versions, which may also list presentations (or versions), so it lacks explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a usage scenario: list presentations, optionally filtered by owner. It does not provide explicit guidance on when to use this tool over alternatives, such as presentation_list_versions, nor does it mention exclusion criteria or prerequisites. The optional owner filter is stated, but no further context is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

presentation_list_versionsA

Lista el historial de versiones (commits) de una presentación, del más nuevo al más viejo.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesID del deck.

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the burden. It discloses ordering (newest to oldest), but does not explicitly state read-only behavior, pagination, or output structure. The word 'list' implies read-only, but more details would be needed for full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the purpose and key behavioral detail (ordering). Every word is necessary, and there is no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and no output schema. The description lists versions but does not mention what fields are returned (e.g., timestamps, authors, commit messages), which is a gap for an agent expecting to use the result. It is adequate but incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the single 'id' parameter has a description). The tool description adds no extra parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists version history (commits) of a presentation, with a specific verb and resource. It distinguishes from sibling tools like presentation_list (lists presentations) and presentation_get (gets a presentation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies usage: when needing the version history of a specific presentation. It provides no explicit alternatives or when-not-to-use, but the context is unambiguous and enough for an agent to select this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

presentation_rollbackA

Vuelve una presentación a una versión anterior creando un nuevo commit con ese contenido (rollback no destructivo).

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesID del deck.
versionYesSHA de commit al que volver.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full transparency burden. It discloses a critical behavioral trait: the rollback is non-destructive because it creates a new commit rather than overwriting history. This directly informs the agent about side effects and safety. It does not disclose permissions or response formats, but the key behavioral insight is clearly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly-worded sentence that states the action, resource, method, and safety property. There is no redundant information or filler. It earns its place by communicating the essential aspects efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter rollback tool, the description covers the core purpose and behavioral nuance well. It lacks an explicit mention of return values, but the non-destructive rollback concept is fully captured. Given the absence of annotations and output schema, it's reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides descriptions for both parameters: 'ID del deck' and 'SHA de commit al que volver', giving 100% coverage. The tool description adds no extra parameter-level information, so there's no value beyond the schema. Baseline of 3 applies since the schema is informative.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Vuelve' (returns) targeting 'una presentación' and clearly defines the action as rolling back to a previous version, which is distinct from siblings like presentation_update or presentation_append. It also clarifies the mechanism (creating a new commit) without ambiguity. This makes the tool's purpose fully unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use this tool: to revert a presentation to an earlier version in a non-destructive way. While it doesn't explicitly name alternatives like presentation_update or presentation_list_versions, the rollback intent is unmistakable. The 'rollback no destructivo' note implicitly discourages using destructive methods, giving sufficient guidance for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

presentation_updateA

Actualiza una presentación existente (reemplaza HTML y/o metadata) creando una nueva versión. No borra el historial.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesID del deck a actualizar.
htmlNoNuevo HTML (si se omite, se conserva el actual).
tagsNoNuevas etiquetas (reemplazan las anteriores).
titleNoNuevo título (opcional).

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the disclosure burden. It reveals that updates create a new version and preserve history, which is valuable behavioral context. However, it omits details about permissions, reversibility, or response format, leaving room for more transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence that front-loads the action and scope, followed by a key behavioral note. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, no annotations, and no output schema, the description covers the core functionality, the effect on versions, and the non-destructiveness. It lacks explicit return-value information, but for an update operation this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptive parameter comments, so the baseline is 3. The description adds minimal semantic value by summarizing that html and metadata (tags, title) are replaced, but it does not provide details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action ('Actualiza'), the target ('presentación existente'), and the scope ('reemplaza HTML y/o metadata' and 'creando una nueva versión'). It also differentiates from siblings by emphasizing it does not delete history, which separates it from rollback and create operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it (for direct HTML/metadata updates) but does not explicitly exclude alternatives like presentation_update_from_file or presentation_append. It mentions the versioning behavior but lacks explicit 'use instead of X' guidance, so usage context is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.1.0
    • First observedpresentation_create
    • First observedpresentation_deploy
    • First observedpresentation_get
    • First observedpresentation_get_deployment
    • First observedpresentation_list
    • First observedpresentation_list_versions
    • First observedpresentation_rollback
    • First observedpresentation_update
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 8 tools

Disambiguation5/5

Each tool targets a distinct resource and action: create, update, get, list_versions, list, rollback, deploy, and get_deployment. The boundaries are clear, e.g., presentation_get for content vs presentation_get_deployment for deployment status.

Naming Consistency5/5

All tools follow the presentation_verb pattern consistently, using straightforward verbs like create, update, get, list, rollback, deploy. Even sub-actions like list_versions and get_deployment maintain the pattern.

Tool Count5/5

8 tools is well-scoped for a presentation management service with versioning and deployment. Each tool serves a distinct purpose without redundancy or bloat.

Completeness4/5

The lifecycle is well covered with create, read, update, versioning, rollback, and deployment. The only notable gap is the absence of a delete/purge operation for presentations, which agents might need for full lifecycle management.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers