portal-mcp-server

remote_grep

Search remote file contents by regex via SSH, returning structured JSON with capped output so broad queries don't overflow context.

Instructions

Search file contents with a regex on a remote host (ripgrep, fallback grep). Prefer this over running raw rg/grep through remote_exec — it returns structured JSON and caps output so a broad search can't blow up your context. Pair it with remote_glob to find files by name.

Args: host: SSH host alias / registered name. pattern: the regex to search for (rg/PCRE-ish syntax). path: file or directory to search under (default: cwd "."). Result paths are returned relative to it. glob: filter files by a glob, e.g. ".py" or "!.test.ts". file_type: rg --type filter, e.g. "py", "rust", "js". output_mode: - "files_with_matches" (default): just the matching file paths, NEWEST FIRST. Cheapest; use it to locate, then re-grep with output_mode="content" on the file you care about. - "content": matching lines as {file, line, text} (context lines carry "context": true). head_limit caps the TOTAL lines returned and offset pages through them. - "count": per-file match counts + a grand total. ignore_case: case-insensitive match. before_context / after_context / context: lines of context to include around each match in "content" mode (context = both sides). head_limit: cap on results (files / content lines / count rows). Default 250; a truncated flag in the result tells you more were dropped. offset: skip the first offset results (pagination). multiline: let . and the pattern span line boundaries.

Respects .gitignore (ripgrep's default). Returns JSON whose shape depends on output_mode; every shape includes a truncated flag.

Input Schema

TableJSON Schema

Name	Required	Default
`glob`	No
`host`	Yes
`path`	No	.
`offset`	No
`context`	No
`pattern`	Yes
`file_type`	No
`multiline`	No
`head_limit`	No
`ignore_case`	No
`output_mode`	No	files_with_matches
`after_context`	No
`before_context`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv4.0.3Sep 28, 2026

TDQS

A4.7/5.0

Behavior4/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 and does well: it discloses .gitignore respect, output capping to protect context, a truncated flag, newest-first ordering, and pagination via offset. It does not mention auth/permission requirements or rate limits, which is the only real gap for a remote operation.

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

Conciseness4/5

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

Front-loads the most valuable guidance (prefer over remote_exec, pair with remote_glob) before the args list, and each arg line earns its place given zero schema documentation. It is lengthy, but the length is justified by the 13 undocumented parameters.

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?

An output schema exists, so return values need not be spelled out, yet the description still notes that the JSON shape depends on output_mode and always carries a truncated flag. Combined with the threading of grepping workflow and pagination, nothing needed to invoke it correctly is missing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it does: it documents the meaning of every non-trivial parameter (glob syntax and negation, file_type examples, all three output_mode values, context/before_context/after_context, head_limit default and truncation, offset paging, multiline). This is far beyond bare schema titles.

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?

States a specific verb and resource ('Search file contents with a regex on a remote host') with the implementation noted (ripgrep, fallback grep). It explicitly distinguishes itself from two siblings: it is preferred over raw rg/grep via remote_exec and pairs with remote_glob for filename search.

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?

Explicit when-to-use routing: 'Prefer this over running raw rg/grep through remote_exec' plus 'Pair it with remote_glob to find files by name'. It also gives workflow guidance for the output_mode choice ('use it to locate, then re-grep with output_mode=content').

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

Deploy Server