ufsc-moodle-mcp

Ler e extrair texto/layout visual de arquivo do Moodle (com OCR local automático opcional)

read_moodle_file

Read-onlyIdempotent

Extracts native text or runs local OCR on authorized Moodle files, reusing cached fileId to avoid re-downloads and preserving originals via download links.

Instructions

Lê qualquer arquivo autorizado do Moodle (por fileurl ou reutilizando fileId já baixado em TempFileStore sem novo download), preservando o arquivo original via downloadUrl/resourceUri e extraindo texto nativo (PDF, DOCX, ODT, PPTX, ZIP, código) ou executando OCR local automático no servidor (ocrMode="auto"|"force"|"status" via Poppler pdftoppm + Tesseract) com blocos visuais posicionados (coordenadas, região na página, confiança e ordem de leitura).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "read_moodle_file"
  }
}

Input Schema

Name	Required	Description
`fileId`	No	ID temporário retornado anteriormente por download_moodle_file, read_moodle_file ou get_submission_content para reprocessar o arquivo (ex: com ocrMode="auto") sem baixá-lo novamente do Moodle.
`fileurl`	No	URL do arquivo no Moodle (pluginfile.php ou webservice/pluginfile.php). Opcional quando fileId válido for informado.
`ocrMode`	No	Modo de OCR local no servidor: "off" (padrão compatível, apenas texto nativo), "auto" (usa texto nativo quando suficiente e aplica OCR local apenas nas páginas de imagem/sem camada textual), "force" (força OCR em todas as páginas até maxOcrPages) ou "status" (apenas diagnostica necessidade e suporte de OCR).
`filename`	No	Nome opcional do arquivo para auxiliar na detecção de formato.
`maxBytes`	No	Limite máximo opcional em bytes para o download.
`maxChars`	No	Limite máximo de caracteres a extrair (padrão: 60000).
`timeoutMs`	No	Timeout opcional em milissegundos para o download no Moodle.
`maxOcrPages`	No	Limite máximo de páginas processadas via OCR (padrão: 30).
`ocrLanguages`	No	Idiomas do Tesseract para OCR (padrão: ["eng", "por"]).
`ocrTimeoutMs`	No	Timeout máximo global em ms para o processamento OCR local (padrão proporcional: 120000).
`forceDownload`	No	Se true, força novo download do Moodle quando fileurl é informado.
`ocrPageTimeoutMs`	No	Timeout individual por página em ms para o processamento OCR local (padrão: 60000).

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.2.1Nov 7, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety bar is covered. The description still adds real context: OCR executes locally on the server via Poppler pdftoppm + Tesseract, the original file is preserved via downloadUrl/resourceUri, and reuse of fileId avoids a redundant Moodle download. It does not mention server load cost or what happens when OCR is unavailable, which keeps it below a 5.

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

Conciseness3/5

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

The purpose is front-loaded, which is good, but the whole definition is a single long run-on sentence with deep parenthetical nesting ('via Poppler pdftoppm + Tesseract') that is hard to parse. It contains little waste, yet the structure would benefit from splitting the extraction behavior from the OCR behavior.

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

Completeness5/5

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

For a 12-parameter read tool with no output schema, the description carries the needed weight: it discloses input sources, the format support matrix, the OCR engine and modes, the shape of results (positioned visual blocks with coordinates, page region, confidence and reading order), and where the original file is exposed. Only the zero-required-parameter edge case is unaddressed, which is minor.

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%, so every parameter is already documented in the input schema, warranting the baseline 3. The description echoes the ocrMode values and the fileId/fileurl either-or relationship, but adds no cross-parameter rules (e.g., what happens with neither supplied, or how maxBytes interacts with maxOcrPages) beyond what the schema already states.

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?

States a specific verb and resource ('Lê qualquer arquivo autorizado do Moodle') and enumerates supported formats (PDF, DOCX, ODT, PPTX, ZIP, código) plus the OCR path. The 'reutilizando fileId já baixado em TempFileStore sem novo download' clause implicitly separates it from download_moodle_file, but no sibling is actually named, so the differentiation is inferential rather than explicit.

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?

Usage is implied rather than stated: an agent can infer that fileurl is for a fresh read and fileId for reprocessing, and ocrMode='auto'|'force'|'status' hints at escalation paths. However, there is no explicit statement of when to prefer this over download_moodle_file or get_submission_content, no prerequisites, and no failure-mode guidance.

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