Click on "Deploy 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., "@basic-fns-mcp grep for TODO in the project"
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.
A streamable-HTTP/stdio MCP server exposing the core filesystem, shell, search, and listing tools that mirror the default agent toolset.
Tool | Hint | Purpose |
| readOnly | Read a text file with cat-style line numbers |
| destructive | Create or overwrite a file atomically |
| destructive | Create a directory and any missing parents |
| destructive | Targeted string replacement in a text file |
| destructive | Execute a shell command and capture output/exit code |
| readOnly | Search file contents by regex (uses |
| readOnly | Find files/directories by glob-style name match |
| readOnly | List directory contents |
All filesystem paths are resolved relative to the configured server root. The server refuses any path that resolves outside that root, including symlinks that escape it.
Related MCP server: MCP File Server
Install and run over HTTP:
uv sync
uv run basic-fns-mcp --root . --port 8080Add it to Claude Code:
claude mcp add --transport http basic-fns http://127.0.0.1:8080/mcpThe same server runs over stdio, where the client spawns it as a subprocess:
uv run basic-fns-mcp --stdio # or: --transport stdioAdd it to Claude Code:
claude mcp add basic-fns -- uv run --directory /path/to/basic-fns-mcp basic-fns-mcp --stdioOr in an MCP client config file:
{
"mcpServers": {
"basic-fns": {
"command": "uv",
"args": ["run", "--directory", "/path/to/basic-fns-mcp", "basic-fns-mcp", "--stdio"],
"env": { "BASIC_FNS_ROOT": "/path/to/your/project" }
}
}
}On stdio, stdout is the protocol channel — the startup banner is suppressed and all
logging goes to stderr. The --host/--port flags are ignored.
The module can also be served directly, since tools are registered at import time:
uv run fastmcp run src/basic_fns_mcp/server.pyFlag | Environment variable | Default | Meaning |
|
| current working directory | Sandbox root; all paths resolve under it |
|
|
| HTTP bind address |
|
|
| HTTP bind port |
|
|
| Refuse |
|
|
| Cap any tool result to this length |
|
|
| Default shell timeout in seconds |
|
|
| Disable |
|
|
| Do not register the |
|
|
|
|
Command-line arguments win over environment variables.
Path sandbox: read, write, mkdir, edit, grep, find, and ls resolve every path inside --root. Symlinks are followed and checked; any path that resolves outside the root is rejected.
bash is not sandboxed: bash runs with the full privileges of the server process. A shell command can cd anywhere, read any file the server user can read, and execute arbitrary code. Only bind to loopback (127.0.0.1) and expose this server to trusted clients.
No command blocklist: Blocklists are easily bypassed and create a false sense of security, so none is implemented.
Read-only mode: Use --read-only to prevent file modification via this server.
Run the test suite:
uv run pytest -qMIT
Execute a shell command and return exit code, stdout, and stderr.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory relative to server root | |
| command | Yes | Shell command to run | |
| timeout | No | Timeout override in seconds |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the return format (exit code, stdout, stderr) which is not in the annotations. However, it does not elaborate on side effects or the fact that arbitrary commands can be destructive, though the destructiveHint annotation already signals this.
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 immediately states the action and expected outputs.
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 complete schema with full parameter descriptions, an existing output schema, and the destructiveHint annotation, the description is sufficient for a basic understanding. It could add usage warnings, but the structured fields cover the main safety concern.
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 100% for all three parameters (cwd, command, timeout), so the description does not need to repeat parameter details. The description itself adds no parameter-level semantics, but the schema already provides them.
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 uses a specific verb 'Execute' with a clear resource 'a shell command' and explicitly states the return values (exit code, stdout, stderr). This clearly distinguishes it from siblings like read, grep, find, ls, write, and edit which are file-specific.
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 provides no guidance on when to use bash versus dedicated tools like read, grep, or find. It does not mention exclusions or alternatives, leaving the agent to infer usage from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace old_string with new_string in a text file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path relative to the server root | |
| new_string | Yes | Replacement text | |
| old_string | Yes | Text to replace | |
| replace_all | No | Replace every occurrence |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already signals destructive behavior, and the description does not add further context such as irreversibility, in-place modification, or behavior when old_string is not found. The description restates the basic action without disclosing additional side effects or requirements.
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, clear sentence that is front-loaded with the primary action and parameters. It is concise with no filler, earning a perfect score for structure.
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, combined with the full schema and destructive annotation, provides a basic understanding of the tool. However, it lacks usage guidance and does not elaborate on the effects of the operation or edge cases, making it adequate but not comprehensive for a destructive edit 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?
The schema covers all 4 parameters with descriptions, so the baseline is 3. The description references old_string and new_string in context, but adds no additional semantic meaning beyond what the schema already provides. It does not explain replace_all behavior or path resolution 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 'Replace *old_string* with *new_string* in a text file' uses a specific verb ('Replace') and identifies the resource ('text file'), clearly distinguishing it from read-only siblings like read/grep/find/ls and write (which creates/overwrites files). The purpose is 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?
The description implies use for editing existing text files but does not explicitly state when to use this tool versus alternatives (e.g., write for full-file rewrites) or when not to use it. No exclusions or alternative suggestions are provided, though the intended context is inferable from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find files or directories by glob-style name match.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Directory under the server root | . |
| type | No | Filter by 'file' or 'dir' | |
| pattern | No | Glob-style name pattern | * |
| max_results | No | Maximum entries to return |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description does not contradict this. However, it adds minimal behavioral context beyond the annotation—such as recursion behavior, path interpretation, or handling of max_results—leaving important operational details unspecified.
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, 8-word sentence that is front-loaded with the verb 'Find'. It contains no filler and is appropriately sized for the simplicity of the tool.
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 schema and annotations provide solid structural and safety information, but the description omits key behavioral details such as whether the search is recursive, how 'path' maps to the server root, and the effect of max_results. For a relatively straightforward find tool, this leaves some ambiguity, though it remains adequate.
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?
All four parameters have full schema descriptions, so the baseline is 3. The tool description adds no extra parameter semantics beyond what the schema already provides, and the schema descriptions are sufficient on their own.
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 uses the specific verb 'Find' with a clear resource ('files or directories') and a matching criterion ('glob-style name match'). This clearly distinguishes it from sibling tools like read, grep, and ls, which handle content reading, content searching, and listing respectively.
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 locating files or directories by name pattern, but it does not explicitly state when to prefer this over alternatives like 'ls' or 'grep'. No exclusions or alternative tool references are given, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search file contents by regex.
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | Glob filter, e.g. '*.py' | |
| path | No | Directory under the server root to search | . |
| pattern | Yes | Regular expression pattern | |
| max_results | No | Maximum results to return | |
| case_insensitive | No | Case-insensitive search |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds no further behavioral detail such as return format, recursion behavior, or default path handling. It merely restates the core action without disclosing additional traits beyond the annotation.
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, front-loaded with the action, and contains no filler or redundancy. It efficiently conveys the tool's 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 rich schema, annotations, and output schema, the one-sentence description is largely sufficient for a simple grep tool. However, it lacks any mention of search scope or output expectations that would make it fully self-contained, though the schema covers these details.
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?
The input schema has 100% coverage with descriptive fields for all 5 parameters. The description adds no parameter-specific information beyond the schema, so the baseline score of 3 applies.
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 'Search file contents by regex' uses a specific verb and resource, clearly distinguishing it from sibling tools like find (which searches filenames) and read (which reads files). It precisely defines the tool's function without ambiguity.
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 is provided on when to use this tool versus alternatives. The description does not mention any context, exclusions, or alternative tools, leaving the agent without direction on selecting grep over find or read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the contents of a directory.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Include hidden entries | |
| path | No | Directory to list | . |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already establishes the tool's safety profile. The description adds no additional behavioral traits beyond the basic listing action, such as non-recursiveness or default path behavior. Since the annotation covers the key safety aspect, a score of 3 is appropriate—no contradiction, but no extra context.
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 filler. Every word contributes to conveying the tool's purpose, making it extremely concise and efficiently structured.
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 tool is simple, with an output schema present and well-documented parameters. The description fully captures the tool's essence for an AI agent, and no additional return-value details are needed due to the output schema. It is complete for its intended scope.
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?
The input schema fully describes both parameters (all and path) with their types, defaults, and descriptions, providing 100% coverage. The tool description adds no parameter-level information. Thus, the baseline of 3 applies; the schema does the heavy lifting.
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 'List the contents of a directory' uses a specific verb and resource, clearly distinguishing it from sibling tools like read (file content), find (search), and write/edit (modify). It is unambiguous and immediately conveys the tool's function.
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 is too brief to provide explicit usage guidance or mention alternatives. While the purpose implies listing directory contents, it does not state when to prefer this over find or grep in recursive or search scenarios. Usage context is only implied by the tool's name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a text file and return its contents with cat-style line numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path relative to the server root | |
| limit | No | Maximum number of lines to return | |
| offset | No | 0-indexed starting line number |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true, so the safety profile is known. The description adds meaningful behavioral detail about the output format (cat-style line numbers), which goes beyond the annotation. No contradictions exist.
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 that is front-loaded with the primary action and includes a specific output detail. Every word earns its place with no waste.
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?
Even though the tool has parameters and an output schema, the description covers the essential purpose and behavior. With an output schema present, the description need not explain return values. The tool is simple and the description is sufficient.
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 100%, with all three parameters documented in the schema. The description does not add any additional semantics about parameters, so the baseline score of 3 applies.
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 'Read' and resource 'text file', and specifies the output format as 'cat-style line numbers'. This distinguishes it from sibling tools like grep (search), find (locate files), ls (list), and write/edit (modify files).
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 makes it clear that the tool is for reading text file contents. It does not explicitly mention when not to use it or point to alternatives, but the specificity of the action ('Read a text file') provides clear context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or overwrite a file atomically (temp file + os.replace).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path relative to the server root | |
| content | Yes | Text content to write |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds atomicity and the implementation detail of 'temp file + os.replace' beyond the destructiveHint annotation. It also explicitly mentions overwrite, which gives the agent a clear picture of the tool's behavior and safety profile.
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 that states the core purpose and implementation detail without any filler. It is front-loaded and every word contributes to understanding.
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?
For a simple two-parameter tool with full schema coverage, annotations, and an output schema, the description sufficiently covers the core behavior and atomicity. There is no missing critical information.
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?
The input schema fully describes both parameters (path and content) with meaningful descriptions. The tool description does not add additional semantic meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
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 creates or overwrites a file atomically, using a specific verb ('create/overwrite') and resource ('file'). It distinguishes itself from siblings like 'edit' (which implies modifying existing files) and 'bash' (which could write via shell) by emphasizing atomic write behavior.
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 provides no explicit guidance on when to use this tool versus alternatives such as 'edit' or 'bash'. It only defines the action without mentioning use cases, prerequisites, or exclusions, leaving the agent to infer when atomic file writing is preferred.
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.
v0.1.0basheditfindgreplsreadwriteScored across 7 tools
read, grep, find, and ls each target a distinct operation (reading content, searching content, finding files by name, listing directories), but the generic bash tool can perform all of these actions, creating overlap and ambiguity about when to use the specialized tools versus bash.
All tool names are single lowercase verbs (read, grep, find, ls, write, edit, bash) following a consistent Unix-command style. The naming pattern is uniform and predictable.
With 7 tools, the server is well-scoped for a basic file operations server. Each tool addresses a core operation (read, write, edit, search, list), and the count is within the ideal range.
The server covers create (write), read (read), and update (edit) but lacks an explicit delete, move, or copy operation. The bash tool can work around these gaps, but the dedicated surface is incomplete for full file lifecycle management.
Artifact store for AI agents — read, write, and search files by path; share by rendered URL.
Get share links, publish and manage websites, artifacts and agents. No account needed.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
