cygnus-ssh-mcp

Official

Overview Schema Source Related Servers Discussions Admin

ssh_file_insert_lines_after_match

Insert one or more lines into a remote file via SSH after an exact matching line. Fails if the match is not unique, ensuring safe edits.

Instructions

Insert one or more new lines immediately after a matching line. match_line must match EXACTLY ONE line in the file (whitespace-trimmed, literal text - not a pattern); if it matches zero lines or more than one, the operation fails with a descriptive error rather than guessing. Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique.

PARAMETERS:

file_path: Path to the file to modify
match_line: Exact line content to match (whitespace-trimmed)
lines_to_insert: List of lines to insert after the match
- To insert multiple lines: use ["first line", "second line", ...]
- To insert a single line: use ["line to insert"]
- To insert an empty line: use [""]
use_sudo: Use sudo for the operation (default: false)
force: No longer needed (kept for compatibility) - use_sudo reads root-only files with sudo (default: false)

RETURNS: On success: {'success': True, 'lines_inserted': <len(lines_to_insert)>} (note: the key is lines_inserted here, vs. lines_written on ssh_file_replace_line/ssh_file_replace_line_multi). On failure (match not found, match not unique, file not found/unreadable): {'success': False, 'error': str}

not a raised exception. Does NOT return file_path in the response.

EXAMPLES: Example 1: Insert configuration lines after a marker

{
  "file_path": "/etc/nginx/nginx.conf",
  "match_line": "http {",
  "lines_to_insert": ["    server_tokens off;", "    client_max_body_size 20M;"]
}

Example 2: Add a new host entry after localhost

{
  "file_path": "/etc/hosts",
  "match_line": "127.0.0.1 localhost",
  "lines_to_insert": ["192.168.1.10 myserver.local"]
}

Long-running calls: if this takes longer than the server's wait cap (default 50s), it
returns {"status": "in_progress", "handle_id": ...} instead of the result - the work keeps
running. Get the result by polling ssh_cmd_check_status(handle_id=...), which returns this
tool's normal response once finished. Do not call it again meanwhile. Only one such
operation runs at a time; another one started meanwhile fails with a 'busy' error.

Input Schema

TableJSON Schema

Name	Required	Description
`force`	No	No longer needed (kept for compatibility): with use_sudo=true the file is read with sudo when the user can't read it. If it can't be read at all, the edit fails - it never reports success without having seen the file.
`use_sudo`	No	Use sudo for the operation
`file_path`	Yes	Path to the file to modify
`match_line`	Yes	Exact line content to match
`lines_to_insert`	Yes	Line(s) to insert after the match

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.6.1Oct 5, 2026

changedInput schema / properties / force / description

Previous value: -"Force operation even if file can't be read (sudo only)"New value: +"No longer needed (kept for compatibility): with use_sudo=true the file is read with sudo when the user can't read it. If it can't be read at all, the edit fails - it never reports success without having seen the file."

First observedv1.3.0May 28, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and delivers: exact literal (non-pattern) matching, whitespace-trimmed comparison, hard failure on zero or multiple matches rather than guessing, failure returned as a value not a raised exception, deprecated force param, sudo read behavior, and long-running/polling/busy semantics. This is unusually complete behavioral disclosure.

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-loaded with the core behavior and match constraint, then failure modes, then the async polling caveat. Every section is useful, though the long-running paragraph is somewhat verbose and the RETURNS block partly duplicates the output schema.

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?

Covers the mutation, its preconditions, its failure contract, and the async completion path, so an agent has everything needed to invoke and interpret the tool. The explicit return-key naming (lines_inserted vs lines_written on siblings) further reduces cross-tool confusion.

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 100%, so baseline is 3, and the description adds genuine meaning: match_line must match exactly one line literally, lines_to_insert format conventions (single, multiple, empty-string), and that force is deprecated. It clarifies rather than merely restates 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?

States a specific verb and resource ('Insert one or more new lines immediately after a matching line') with clear scoping. The exact-match semantics and the reference to ssh_file_find_lines_with_pattern distinguish it from replace/delete siblings. An agent can tell what it does without opening the schema.

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?

Gives a concrete prerequisite ('Use ssh_file_find_lines_with_pattern first if you're not sure the line is unique') and implicitly contrasts with replace-by-pattern tools. However, it does not state when to prefer this over, say, ssh_file_write or ssh_file_replace_line for the same edit, so the guidance is strong but not exhaustive.

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

Deploy Server