Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@file-mcp Replace 'copyright 2023' with 'copyright 2024' in C:\legal.txt"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
file-mcp is a Windows-first MCP server focused on deterministic text writes.
It intentionally exposes write-only tools for create, replace, and structured edit workflows.
Public read and search capabilities have been removed from the tool surface.
Keep the MCP surface focused on writing files
Preserve encoding, BOM, newline style, and trailing newline by default when editing existing files
Support atomic writes guarded by base_hash
Handle chunked large-file generation without giant single-call payloads
Keep existing mixed-newline files writable without forcing full normalization first
Related MCP server: local-code-mcp
write_full_text(path, content, encoding="preserve", bom="preserve", newline="preserve", final_newline="preserve", create_dirs=True, if_exists="overwrite", base_hash=None)
Whole-file atomic write.
apply_text_edits(path, edits, encoding="preserve", bom="preserve", newline="preserve", final_newline="preserve", base_hash=None)
Atomic line-range edits. Each edits[] item must provide start_line and new_text; end_line and expected_old_text are optional.
apply_text_spans(path, spans, encoding="preserve", bom="preserve", newline="preserve", final_newline="preserve", base_hash=None)
Atomic offset-based edits using normalized-text offsets. Each spans[] item must provide start_offset, end_offset, and new_text; expected_old_text is optional.
replace_literal(path, old_text, new_text, encoding="preserve", expected_occurrences=1, bom="preserve", newline="preserve", final_newline="preserve", base_hash=None)
Exact-count literal replacement. When no exact match is found, the server also tries conservative mojibake recovery for non-ASCII old_text/new_text pairs before failing and reporting whitespace or codec hints.
replace_regex(path, pattern, replacement, encoding="preserve", expected_occurrences=1, case_sensitive=True, dotall=False, bom="preserve", newline="preserve", final_newline="preserve", base_hash=None)
Exact-count regex replacement.
replace_block(path, start_marker, end_marker, replacement, encoding="preserve", occurrence=1, mode="between", bom="preserve", newline="preserve", final_newline="preserve", base_hash=None)
Marker-delimited block replacement.
begin_write_session(path, encoding="preserve", bom="preserve", newline="preserve", final_newline="preserve", create_dirs=True, if_exists="overwrite", base_hash=None)
append_write_chunk(session_id, content)
commit_write_session(session_id)
abort_write_session(session_id)
inspect_text was removed from the public MCP interface
read_text was removed from the public MCP interface
search_text was removed from the public MCP interface
apply_search_replacements was removed from the public MCP interface
The server still reads existing file contents internally when a write operation needs style preservation, conflict checks, or targeted replacement. That internal read path is now an implementation detail rather than a client-facing capability.
Recommended usage now is:
Use a caller-side source of truth for the target file content or edit coordinates.
Choose one write primitive:
write_full_text, apply_text_edits, apply_text_spans, replace_literal, replace_regex, or replace_block.
Pass base_hash when you already have a trusted hash and want fail-closed concurrency protection.
Use chunked sessions for large generated outputs.
Successful write tools return compact natural-language summaries for LLM attention hygiene. The default result includes only the operation outcome, target path, and essential counts or session id.
Examples:
Created C:\work\repo\README.md.
Updated C:\work\repo\src\app.ts: replaced 1 occurrence.
Unchanged C:\work\repo\README.md: new content matched existing file.
Write session started for C:\work\repo\large.txt. Session: 8f6c2c4e0f134f49a6b48bbf55f7156a
Committed write session 8f6c2c4e0f134f49a6b48bbf55f7156a to C:\work\repo\large.txt: updated file.The tool output intentionally omits audit fields such as hashes, byte counts, encoding, newline style, and total line counts.
apply_text_edits item fields:
start_line: 1-based inclusive line number.
end_line: optional 1-based inclusive end line. Omit to replace only start_line; set to start_line - 1 to insert before start_line.
new_text: replacement text for the line range.
expected_old_text: optional guard text for the existing line range.
apply_text_spans item fields:
start_offset: 0-based inclusive offset in normalized file text.
end_offset: 0-based exclusive offset in normalized file text.
new_text: replacement text for the offset range.
expected_old_text: optional guard text for the existing normalized offset range.
When editing an existing file with the default "preserve" modes:
encoding keeps the detected file encoding
bom keeps the existing BOM state
newline keeps LF, CRLF, or CR
final_newline keeps whether the file ended with a newline
If the existing file uses mixed newline styles and you keep newline="preserve", unchanged or positionally corresponding lines retain their original endings and inserted lines use the dominant existing newline style.
By default the server only allows access under F:\.
Override with an environment variable:
$env:FILE_MCP_ALLOWED_ROOTS = 'F:\;F:\GGPK3\;F:\repo\'Multiple roots are separated with ;.
Set FILE_MCP_ALLOWED_ROOTS to * to disable root restrictions entirely.
cd D:\file-mcp
py -m pip install -e .cd D:\file-mcp
py -m file_mcp{
"mcpServers": {
"file-mcp": {
"command": "py",
"args": ["-m", "file_mcp.server"],
"cwd": "D:\\file-mcp",
"env": {
"FILE_MCP_ALLOWED_ROOTS": "*"
}
}
}
}Auto-detection supports UTF-8, UTF-8 BOM, UTF-16 LE/BE, UTF-32 LE/BE, and gb18030, and it now prefers gb18030 over UTF-8 only when both decoders succeed and the UTF-8 result looks materially more like mojibake
Successful write tools return compact natural-language summaries instead of JSON metadata
write_full_text is the simplest primitive when whole-file replacement is acceptable
Abort a chunked write session without writing anything.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It mentions the outcome (no data written) but omits side effects such as session invalidation, error conditions, or whether prior appended chunks are discarded. The description is too terse to be fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no extraneous information. It is concise and front-loaded with the key action and differentiator, though very brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema present), the description is minimally adequate. It states the core purpose and key differentiator, but lacks detail on parameters and usage context. The presence of an output schema partially compensates, yet the description could still elaborate on when and how to apply the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should add parameter meaning. The only parameter `session_id` is named but the description provides no format, source, or constraints, adding no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'abort' and the resource 'chunked write session', and distinguishes from siblings like commit_write_session by adding 'without writing anything', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., when to abort vs commit). The description only states the action, leaving the agent to infer usage context from sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a text chunk to an open write session.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only says 'append' which implies mutation but lacks details on permissions, error handling, idempotency, or effects on existing content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 8-word sentence that is direct and front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema coverage, and an output schema not described, the description is too minimal. It lacks preconditions, return info, and error details, requiring the agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the parameters. 'content' and 'session_id' are named but not described, forcing reliance on inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (append) and resource (text chunk) and specifies context (open write session). This distinguishes it from sibling session lifecycle and write tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'apply_text_edits' or 'replace_block'. It only implies session must be open but doesn't mention preconditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply multiple non-overlapping line-range edits in a single atomic write.
| Name | Required | Description | Default |
|---|---|---|---|
| bom | No | preserve | |
| path | Yes | ||
| edits | Yes | ||
| newline | No | preserve | |
| encoding | No | preserve | |
| base_hash | No | ||
| final_newline | No | preserve |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behaviors but only mentions atomicity and non-overlap. It omits details about encoding, line endings, concurrency via base_hash, and behavior on overlap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no superfluous content, effectively front-loading the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (7 parameters, no annotations, output schema exists but unused), the description is too sparse. It provides only the minimal function without addressing usage nuances or parameter roles.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema_description_coverage is 0%, meaning top-level parameters have no descriptions. The tool description adds no parameter semantics, leaving path, bom, newline, encoding, base_hash, final_newline unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies multiple non-overlapping line-range edits in a single atomic write, distinguishing it from siblings like replace_literal or replace_regex that handle single edits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for multiple non-overlapping edits in a batch, but lacks explicit guidance on when not to use it or comparisons with alternatives like apply_text_spans or replace_block.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply multiple non-overlapping normalized-text span edits using 0-based offsets.
| Name | Required | Description | Default |
|---|---|---|---|
| bom | No | preserve | |
| path | Yes | ||
| spans | Yes | ||
| newline | No | preserve | |
| encoding | No | preserve | |
| base_hash | No | ||
| final_newline | No | preserve |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It mentions non-overlapping constraint but omits details on mutation safety, atomicity, effect on file, or how 'base_hash' guard works.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (7 parameters, no schema descriptions, no annotations, and many siblings), the description is too sparse. It fails to clarify 'normalized text', offset semantics, when to prefer this tool, or what the output schema contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 7 parameters with 0% description coverage in the top-level schema; nested $defs have minimal descriptions. Tool description adds no explanation of parameters like 'bom', 'newline', 'encoding', 'base_hash', or 'final_newline', leaving the agent without semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action ('apply'), resource ('multiple non-overlapping normalized-text span edits'), and key detail (0-based offsets). This distinguishes it from siblings like 'apply_text_edits' (likely singular) and 'replace_literal'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool instead of alternatives like 'apply_text_edits' or 'replace_literal'. The description only states what it does, not the context or prerequisites for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a chunked write session for large generated files.
| Name | Required | Description | Default |
|---|---|---|---|
| bom | No | preserve | |
| path | Yes | ||
| newline | No | preserve | |
| encoding | No | preserve | |
| base_hash | No | ||
| if_exists | No | overwrite | |
| create_dirs | No | ||
| final_newline | No | preserve |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'Start a chunked write session' without mentioning that the session must be committed/aborted, potential side effects, or required permissions. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (7 words) but under-specified. Conciseness should not come at the cost of missing critical information. It fails to earn its place by omitting essential usage details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, no schema descriptions, no annotations, and 9 sibling tools, the description is far too minimal. It does not explain the workflow, how the session integrates with other write tools, or the meaning of any parameters. The presence of an output schema does not compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 8 parameters (e.g., path, encoding, if_exists). The agent gains no additional insight beyond parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Start') and the resource ('chunked write session'), and specifies it is 'for large generated files', distinguishing it from sibling tools like 'write_full_text'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for large files when chunked writing is needed, but does not explicitly state when to use this tool over alternatives like 'write_full_text' or provide context about workflow (e.g., must commit or abort).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Commit a chunked write session via a single atomic file replacement.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions 'atomic file replacement' but does not cover side effects, idempotency, permissions, or what happens if the session is invalid. This is insufficient for a commit operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded. However, it could be slightly more informative without adding verbosity. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but covers the core action. Given the presence of an output schema (not shown), return values are not required. However, it lacks context about prerequisites, error cases, or the relationship with sibling tools, leaving gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. However, it provides no explanation for the 'session_id' parameter beyond its name. The parameter name is self-explanatory, but the description adds no additional meaning or context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Commit') and the resource ('chunked write session'). It also emphasizes 'atomic file replacement', which distinguishes it from siblings like 'append_write_chunk' or 'abort_write_session'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used after appending chunks to finalize a session, but it does not explicitly state when to use it or when alternatives (like abort) are more appropriate. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a marker-delimited block with base-hash protection and style preservation.
| Name | Required | Description | Default |
|---|---|---|---|
| bom | No | preserve | |
| mode | No | between | |
| path | Yes | ||
| newline | No | preserve | |
| encoding | No | preserve | |
| base_hash | No | ||
| end_marker | Yes | ||
| occurrence | No | ||
| replacement | Yes | ||
| start_marker | Yes | ||
| final_newline | No | preserve |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It mentions base-hash protection and style preservation but does not disclose other behaviors like file modification, session requirements, or error handling. The description is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core action and unique features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, 4 enums, no schema descriptions), the description is insufficient. It lacks explanations for 'base-hash protection', 'style preservation', and marker semantics, which are critical for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 11 parameters, the description provides only high-level context about markers and block replacement. It does not explain key parameters like mode, occurrence, bom, or newline, leaving agents to infer from names and enums.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Replace') and the resource ('marker-delimited block'), and adds unique details like base-hash protection and style preservation, distinguishing it from siblings like replace_literal and replace_regex.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for blocks delimited by markers but does not explicitly state when to use it versus alternatives or exclude cases. Given sibling tools, more guidance would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace literal text only when the exact expected occurrence count matches.
| Name | Required | Description | Default |
|---|---|---|---|
| bom | No | preserve | |
| path | Yes | ||
| newline | No | preserve | |
| encoding | No | preserve | |
| new_text | Yes | ||
| old_text | Yes | ||
| base_hash | No | ||
| final_newline | No | preserve | |
| expected_occurrences | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It mentions the occurrence count condition but does not clarify what happens when count matches (replaces all? replaces exactly expected?), nor other effects like file modification, permissions, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one sentence, no fluff. However, it may be too terse given the tool's complexity, but conciseness is good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 9 parameters, no schema descriptions, and no annotations, the description is insufficient. It explains only the core condition but misses context for many parameters and behavior. Output schema exists, so return values are not required, but other aspects are lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description should explain parameters. It only mentions 'literal text' and 'expected occurrence count', leaving 7 parameters (path, encoding, newline, bom, etc.) unexplained. The description adds minimal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it replaces literal text conditional on occurrence count matching, which clearly differentiates from replace_regex (regex) and replace_block. However, it could be more explicit about what 'replace' means (all occurrences or exactly expected_occurrences?).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like replace_regex or replace_block. The description only states a condition, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace regex matches only when the exact expected occurrence count matches.
| Name | Required | Description | Default |
|---|---|---|---|
| bom | No | preserve | |
| path | Yes | ||
| dotall | No | ||
| newline | No | preserve | |
| pattern | Yes | ||
| encoding | No | preserve | |
| base_hash | No | ||
| replacement | Yes | ||
| final_newline | No | preserve | |
| case_sensitive | No | ||
| expected_occurrences | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions the replacement condition but omits critical details such as whether the operation is destructive, required permissions, error handling when occurrence count doesn't match, or any side effects on file state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise. However, it is overly terse and does not front-load essential information like the tool's primary function beyond what the name implies. Additional context could be added without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters and no annotations, the description is insufficiently complete. It does not explain the return value (output schema exists but not referenced), error conditions, or advanced options. A more comprehensive description is needed for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It only implicitly references the 'expected_occurrences' parameter but fails to explain other key parameters like 'pattern', 'replacement', 'path', or flags such as 'case_sensitive' and 'dotall'. This leaves significant gaps in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it replaces regex matches conditionally based on occurrence count. It clearly specifies the resource (regex matches) and the verb (replace), distinguishing it from literal or block replacements among siblings. However, it could be more explicit about the exact behavior when the count does not match.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like replace_literal or replace_block. The description implies a conditional regex replacement but fails to provide explicit scenarios or exclusions, leaving the agent without clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write an entire text file with explicit style controls and optional base-hash protection.
| Name | Required | Description | Default |
|---|---|---|---|
| bom | No | preserve | |
| path | Yes | ||
| content | Yes | ||
| newline | No | preserve | |
| encoding | No | preserve | |
| base_hash | No | ||
| if_exists | No | overwrite | |
| create_dirs | No | ||
| final_newline | No | preserve |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses key behaviors like style controls and base-hash protection, but fails to detail what happens on base-hash mismatch, path non-existence, or the effect of 'if_exists' and 'create_dirs'. With no annotations, the description carries the burden and only moderately covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words, but could be slightly longer to cover more details without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no annotations, and an output schema (per context), the description is too short. It omits how each parameter affects behavior and what the output looks like. The output schema is present but not referenced, so the description should still provide minimal return value context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It mentions 'style controls' and 'base-hash protection' but does not explain individual parameters like 'bom', 'newline', 'encoding', 'final_newline', 'base_hash', 'if_exists', or 'create_dirs'. This is insufficient for a 9-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Write an entire text file' with specific verb and resource, and mentions 'explicit style controls' and 'optional base-hash protection', which distinguish it from siblings that handle incremental writes or edits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies full file write but does not explicitly state when to use this tool versus alternatives like 'append_write_chunk' or 'apply_text_edits'. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.3.0abort_write_sessionappend_write_chunkapply_text_editsapply_text_spansbegin_write_sessioncommit_write_sessionreplace_blockreplace_literalreplace_regexwrite_full_textEach tool has a clearly distinct purpose: session management, various replace methods, and full file writing. No two tools appear to do the same thing, and descriptions clarify the differences.
All tool names follow a consistent verb_noun snake_case pattern (e.g., abort_write_session, replace_literal), making them predictable and easy to interpret.
10 tools is well within the ideal range. Each tool addresses a specific file editing operation without being excessive or insufficient.
The tool set lacks basic file operations like reading, deleting, or listing files. While editing and writing are covered, the absence of read functionality creates a significant gap for typical file management workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
A MCP server built for developers enabling Git based project management with project and personal…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/yun-wulian/file-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
