Skip to main content
Glama
Nextcloud MCP Server

Nextcloud MCP Server

by stack74

Search text inside files

nextcloud_search_file_contents
Read-onlyIdempotent

Search for a word or phrase inside files below a folder and get the matching lines. Use it to locate content across text, PDF, and Office documents when you do not know file names.

Instructions

Search for a word or phrase INSIDE files below a folder and return the matching lines.

Reads the most recently changed readable files (text, CSV, Markdown, PDF, Word, Excel, PowerPoint, OpenDocument) one by one, so it is bounded by 'max_files' — narrow 'path' to the right folder for best results. Scanned PDFs without a text layer cannot be searched.

To find files by NAME use nextcloud_search_files (much faster). If the server has a full-text index, nextcloud_unified_search may also find content across all files.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "nextcloud_search_file_contents"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoFolder to search below. The narrower, the better./
queryYesWord or phrase to find (plain text, not a regex).
documentsNoAlso search PDF and office documents (slower). false = only plain text files.
max_filesNoHow many files to read at most (newest first).
case_sensitiveNo
modified_afterNoOnly files changed on/after this date (YYYY-MM-DD).
response_formatNo'markdown' for readable output, 'json' for structured datamarkdown
max_matches_per_fileNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.2

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare this a read-only, idempotent, non-destructive operation, and the description adds real behavioral context on top: files are read one at a time in recency order, work is bounded by 'max_files', the supported file types are enumerated, and scanned PDFs without a text layer silently fail to match. What it omits is any sense of cost/latency scaling beyond the brief 'slower' note for documents.

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?

Three short paragraphs with the core capability front-loaded, then the operational constraint, then the sibling routing. Every clause carries information — the file-type list, the max_files bound, and the scanned-PDF caveat all prevent plausible failure modes.

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 an eight-parameter search tool with no output schema, the description covers capability, cost bounding, format support, and a key failure mode. It stops short of describing how multiple matches per file are ordered or truncated, though the schema's 'max_matches_per_file' partially closes that gap.

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

Parameters4/5

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

Schema coverage is 75%, so the baseline is a 3; the description earns an extra point by tying parameters to behavior — 'max_files' as the cost bound, recency ordering of the files read, 'path' narrowness improving results, and 'query' being plain text rather than a regex. It doesn't explain 'modified_after', 'case_sensitive', or 'max_matches_per_file' beyond what the schema already says.

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 gives a specific verb and scope ('Search for a word or phrase INSIDE files below a folder') and states the return shape ('matching lines'). It explicitly distinguishes itself from nextcloud_search_files by content-vs-name, so an agent can pick between them without opening a schema.

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

Usage Guidelines5/5

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

It names both alternatives and the precise conditions that select them: name lookups go to nextcloud_search_files ('much faster'), and indexed full-text lookups may be served by nextcloud_unified_search. It also advises narrowing 'path' for best results, which is actionable usage guidance rather than restating a field.

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