A
licenseNot graded
qualityD
maintenanceA Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.
7
MIT
stela-mcp
by Sachin-Bhat
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., "@stela-mcplist files in /home/user/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.
STeLA MCP
A Python implementation of a Model Context Protocol server that provides secure access to local system operations via a standardized API interface.
STeLA (Simple Terminal Language Assistant) MCP is a lightweight server that provides secure access to local machine commands and file operations via a standardized API interface. It acts as a bridge between applications and your local system, implementing the Model Context Protocol (MCP) architecture.
Overview
STeLA MCP implements the Model Context Protocol (MCP) architecture to provide a secure, standardized way for applications to execute commands and perform file operations on a local machine. It serves as an intermediary layer that accepts requests through a well-defined API, executes operations in a controlled environment, and returns formatted results.
Related MCP server: Command Executor MCP Server
Features
Command Execution: Run shell commands on the local system with proper error handling
File Operations: Read, write, and manage files on the local system
Directory Visualization: Generate recursive tree views of file systems
Working Directory Support: Execute commands in specific directories
Robust Error Handling: Detailed error messages and validation
Comprehensive Output: Capture and return both stdout and stderr
Simple Integration: Standard I/O interface for easy integration with various clients
Multi-Directory Support: Configure multiple allowed directories for file operations
Security-First Design: Strict path validation and command execution controls
File Search: Search for files matching a pattern
File Edit: Make selective edits to a file
Type Safety: Strong type checking with Pydantic models for all tool inputs
Path Validation: Enhanced symlink and parent directory validation
Installation
Installing via Smithery
To install STeLA for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @Sachin-Bhat/stela-mcp --client claudePrerequisites
Python 3.10 - 3.12
pip or uv package manager
Pydantic v2.x
Installation Steps
Clone the repository:
git clone <repository-url>
cd stela-mcpCreate and activate a virtual environment:
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activateInstall dependencies:
pip install -e .Creating a Binary Distribution
To create a self-contained binary:
Install PyInstaller:
pip install pyinstallerCreate the binary:
pyinstaller --onefile src/stella_mcp//server.py --name stela-mcpThe binary will be created in the dist directory.
Configuration
STeLA MCP can be configured using environment variables:
Directory Access Control
ALLOWED_DIRS(Required): Comma-separated list of directories where file operations are allowedExample:
/home/user/project,/home/user/docsDefault: Current working directory if not specified
Note: All paths must be absolute
ALLOWED_DIR(Optional): Primary directory for command execution contextExample:
/home/user/projectDefault: First directory from
ALLOWED_DIRSor current working directoryNote: This is separate from
ALLOWED_DIRSand controls command execution context
Command Execution Security
ALLOWED_COMMANDS(Optional): Comma-separated list of allowed shell commandsExample:
ls,cat,pwd,echoDefault:
ls,cat,pwd,echoSpecial value:
allto allow any command (not recommended)
ALLOWED_FLAGS(Optional): Comma-separated list of allowed command flagsExample:
-l,-a,-h,--helpDefault:
-l,-a,-h,--helpSpecial value:
allto allow any flag (not recommended)
MAX_COMMAND_LENGTH(Optional): Maximum length of command stringsExample:
1024Default:
1024Note: Prevents command injection via overly long strings
COMMAND_TIMEOUT(Optional): Maximum execution time for commands in secondsExample:
60Default:
60Note: Prevents hanging commands
Example Configuration
# Directory access
export ALLOWED_DIRS="/home/user/project,/home/user/docs"
export ALLOWED_DIR="/home/user/project"
# Command execution
export ALLOWED_COMMANDS="ls,cat,pwd,echo"
export ALLOWED_FLAGS="-l,-a,-h,--help"
export MAX_COMMAND_LENGTH=1024
export COMMAND_TIMEOUT=60Project Structure
stela-mcp/
├── src/
│ ├── stela_mcp/
│ │ ├── __init__.py
│ │ ├── shell.py # Shell command execution
│ │ ├── filesystem.py # File system operations
│ │ └── security.py # Security configuration
│ └── server.py # Main server implementation
├── pyproject.toml # Project configuration
└── README.mdUsage
Starting the Server
Run the server using:
uv run python -m src.stella_mcp.serverThe server will start and listen for connections through standard I/O.
Using with Claude Desktop
To use STeLA MCP with Claude Desktop:
Option 1: Using Python directly
Start the server using:
uv run python -m src.stela_mcp.serverIn Claude Desktop:
Go to Settings
Under "Tools", click "Add Tool"
Select "MCP Server"
Enter the following configuration:
Name: STeLA MCP
Path: The absolute path to your Python executable (e.g.,
/home/username/.venv/bin/python)Arguments:
-m src.stela_mcp.serverWorking Directory: The path to your STeLA MCP project directory
Option 2: Using the binary
Copy the binary from
dist/stela-mcpto a location in your PATHIn Claude Desktop:
Go to Settings
Under "Tools", click "Add Tool"
Select "MCP Server"
Enter the following configuration:
Name: STeLA MCP
Path: The absolute path to the binary (e.g.,
/usr/local/bin/stela-mcp)Arguments: (leave empty)
Working Directory: (leave empty)
Once configured, you can use STeLA MCP tools in your conversations with Claude. For example:
"Show me the contents of my home directory"
"Create a new file called 'test.txt' with some content"
"Run the command 'ls -la' in my current directory"
Claude will automatically use the appropriate tools based on your requests and display the results in the conversation.
Available Tools
Command Tools
execute_command
Executes shell commands on the local system.
Parameters:
command(string, required): The shell command to executeworking_dir(string, optional): Directory where the command should be executed
Returns:
On success: Command output (stdout)
On failure: Error message and any command output (stderr)
change_directory
Changes the current working directory.
Parameters:
path(string, required): Path to change to
Returns:
On success: Success message with new path
On failure: Error message
File System Tools
read_file
Reads the contents of a file.
Parameters:
path(string, required): Path to the file to read
Returns:
On success: File contents
On failure: Error message
read_multiple_files
Reads multiple files simultaneously.
Parameters:
paths(array, required): List of file paths to read
Returns:
On success: Combined contents of all files
On failure: Error message and partial results
write_file
Writes content to a file.
Parameters:
path(string, required): Path where the file will be writtencontent(string, required): Content to write to the file
Returns:
On success: Success message
On failure: Error message
edit_file
Makes selective edits to a file.
Parameters:
path(string, required): Path to the file to editedits(array, required): List of edit operationsEach edit contains
oldTextandnewText
dryRun(boolean, optional): Preview changes without applying
Returns:
On success: Git-style diff of changes
On failure: Error message
list_directory
Lists contents of a directory.
Parameters:
path(string, required): Path for the directory to list
Returns:
On success: List of files and directories
On failure: Error message
create_directory
Creates a new directory.
Parameters:
path(string, required): Path for the directory to create
Returns:
On success: Success message
On failure: Error message
move_file
Moves or renames files and directories.
Parameters:
source(string, required): Source path of the file or directory to movedestination(string, required): Destination path where the file or directory will be moved to
Returns:
On success: Success message
On failure: Error message
search_files
Searches for files matching a pattern.
Parameters:
path(string, required): Starting path for the searchpattern(string, required): Search pattern to match file and directory namesexcludePatterns(array, optional): List of glob patterns to exclude
Returns:
On success: List of matching files
On failure: Error message
directory_tree
Generates a recursive tree view of files and directories.
Parameters:
path(string, required): Path for the directory to generate tree from
Returns:
On success: JSON structure representing the directory tree
On failure: Error message
get_file_info
Retrieves detailed metadata about a file or directory.
Parameters:
path(string, required): Path to the file or directory
Returns:
On success: File/directory metadata
On failure: Error message
list_allowed_directories
Lists all directories the server is allowed to access.
Parameters:
None
Returns:
On success: List of allowed directories
On failure: Error message
show_security_rules
Shows current security configuration.
Parameters:
None
Returns:
On success: Security configuration details
On failure: Error message
Security Considerations
STeLA MCP provides direct access to execute commands and file operations on the local system. Consider the following security practices:
Run with appropriate permissions (avoid running as root/administrator)
Use in trusted environments only
Consider implementing additional authorization mechanisms for production use
Be cautious about which directories you allow command execution and file operations in
Implement path validation to prevent unauthorized access to system files
Use the most restrictive configuration possible for your use case
Regularly review and update allowed commands and directories
Validate symlinks to prevent access outside allowed directories
Ensure parent directory checks for file creation operations
Platform-Specific Security Notes
Linux/macOS
Run with a dedicated user with limited permissions
Consider using a chroot environment to restrict file system access
Use
chmodto restrict executable permissionsConsider using SELinux/AppArmor for additional security
Windows
Run as a standard user, not an administrator
Consider using Windows Security features to restrict access
Use folder/file permissions to limit access to sensitive directories
Consider using Windows Defender Application Control
Development
Adding New Tools
To extend STeLA MCP with additional functionality, follow this pattern:
Define a Pydantic model for the tool's input parameters in
server.pyAdd a new method to the appropriate class in
shell.pyorfilesystem.pyRegister the tool in
server.pyusing the@server.call_tool()decoratorImplement the tool handler with proper error handling and return types
Example:
from pydantic import BaseModel, Field
class MyToolInput(BaseModel):
param1: str = Field(description="Description of param1")
param2: int = Field(description="Description of param2")
@server.call_tool()
async def my_tool(request: Request[MyToolInput, str], arguments: MyToolInput) -> Dict[str, Any]:
"""Description of the tool."""
try:
# Tool implementation
result = await do_something(arguments.param1, arguments.param2)
return {"success": True, "result": result}
except Exception as e:
return {"error": str(e)}License
Apache-2.0 License
Acknowledgements
Built with the MCP Python SDK
Available Tools
14 toolschange_directoryA
Change the shell's current working directory. The path must be within the primary allowed directory context:/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to change to |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description describes the core behavior and adds a constraint, but without annotations it lacks details on failure modes, permissions, or side effects (e.g., persistence). Adequate for a simple tool.
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?
Two sentences with zero wasted words. Every sentence provides essential information (action, resource, constraint). Highly concise and well-structured.
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?
For a simple one-parameter tool with no output schema, the description covers the key aspects: what it does, the constraint, and implies it's a navigation action. No missing essential info.
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. The description adds value by stating the allowed directory context ('/app') beyond the schema's 'Path to change to', clarifying a critical constraint.
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 clearly states the action ('Change') and the resource ('shell's current working directory'), distinguishing it from sibling tools like create_directory or directory_tree. The constraint about allowed directories further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. While it notes a path constraint, it does not specify prerequisites, conditions, or scenarios where other tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_directoryA
Create a new directory, including parent directories if needed. Succeeds silently if the directory already exists. Only works within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the directory to create |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It discloses key behaviors: creating parent directories, silent success if exists, and workspace restrictions. This provides sufficient transparency.
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?
The description is three concise sentences. It front-loads the primary action, adds important details about behavior, and ends with constraints. No unnecessary words.
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?
Given only one parameter, no output schema, and no annotations, the description covers the essential aspects: what the tool does, its idempotent behavior, and access restrictions. It is complete for the tool's complexity.
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?
The schema has 100% coverage for the 'path' parameter with a description. The tool description adds value by specifying that the path must be within allowed directories, which is not in the schema. This enhances understanding beyond 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?
The description clearly states the verb 'create' and resource 'directory', and includes details like parent directory creation and silent success if exists. It distinguishes from siblings like change_directory, directory_tree, list_directory by specifying creation behavior.
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?
The description indicates when to use this tool (to create directories) and includes constraints (only works within /app). However, it does not explicitly state when not to use it or mention alternative tools for different operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
directory_treeA
Get a recursive tree view of files and directories as a JSON structure. Each entry includes 'name', 'type' (file/directory), and potentially 'children' for directories. Only works within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Path to the directory (default: current shell directory) |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes output structure and path restriction. No annotations, so description carries burden; side effects not mentioned but tool is read-only by nature.
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?
Two sentences, front-loaded with key information, no filler.
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 a simple one-param tool with no output schema, description covers return structure and constraints. Lacks error handling details but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers path parameter well (100% coverage). Description does not add extra semantic value beyond 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?
Clearly states it returns a recursive tree view as JSON with name, type, and children. Distinguishes from siblings like list_directory (flat) and get_file_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Notes allowed directories constraint but does not explicitly compare to sibling tools like list_directory or search_files. Agent left to infer when to use tree vs. flat listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
edit_fileA
Make selective edits to a text file based on exact line matches (or whitespace normalized). Each edit replaces an existing sequence of lines (old_text) with new lines (new_text). Returns a git-style diff of the changes. Use dry_run to preview. Only works within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file to edit | |
| edits | Yes | List of edit operations | |
| dry_run | No | Preview changes without applying |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses that edits replace exact line sequences, returns a git-style diff, and restricts to allowed directories. It does not mention potential side effects like file locking or permission requirements, but for a file editing tool this is sufficient.
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?
The description is concise (3 sentences), front-loaded with the core action, and every sentence adds value (edit mechanism, return value, dry_run, directory restriction). No fluff.
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?
Given 100% schema coverage and no output schema, the description explains the return type (git-style diff) and directory restrictions. It could mention error cases or handling of multiple edits, but it is complete enough for typical use.
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. The description adds meaning about matching strategy (exact or whitespace-normalized) and that newlines must be included in old_text and new_text, which goes beyond the schema's generic descriptions.
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 clearly states it makes selective edits to a text file using exact line matches or whitespace-normalized matching, distinguishing it from write_file (which overwrites or appends) and read_file. The verb 'edit' and resource 'file' are specific, and the mechanism of replacing old_text with new_text is explained.
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?
The description advises using dry_run to preview changes, which is practical. However, it does not explicitly state when not to use this tool (e.g., for creating new files) or compare to alternatives like write_file. The context is clear enough for an AI agent to infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
execute_commandA
Execute a shell command in the current shell working directory or a specified one. Command execution context is limited to: /app
Available commands: cat, echo, ls, pwd Available flags: --help, -a, -h, -l
Note: Shell operators (&&, |, >, etc.) are NOT supported. Paths in arguments are validated against the primary directory context.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The command string to execute (e.g., 'ls -l') | |
| working_dir | No | Optional directory path to run the command in (must be within primary allowed dir) |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses allowed commands, unsupported operators, path validation, and restricted context. However, it does not mention the return format (stdout), which is a minor gap.
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?
The description is brief, front-loaded with purpose, and contains no redundant sentences. Every sentence provides essential information.
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?
Given no output schema, the description covers input and behavioral constraints well. It lacks explicit mention of return values, but for a command execution tool, stdout output is often implicit.
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?
The description adds significant meaning beyond the input schema by specifying allowed commands, flags, and path validation. Schema coverage is 100%, but the description enriches understanding of how parameters interact.
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 clearly states the tool executes shell commands, specifies the context (/app), and lists available commands and flags. It distinguishes from sibling file operations by focusing on command execution.
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?
The description explicitly states when to use by listing allowed commands and disallowed operators, and implies not to use for complex scripting. It provides clear constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_file_infoA
Retrieve detailed metadata about a file or directory (size, dates, type, permissions). Only works within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file or directory |
TDQS
A4.2/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. It discloses the directory limitation and implies a read-only operation. While it doesn't explicitly state no side effects, the verb 'Retrieve' and metadata focus are sufficient for this context.
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?
The description is extremely concise: one sentence with the core purpose, followed by a clear directory restriction. No superfluous words or repetition.
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?
Given a single required parameter and no output schema, the description adequately covers the purpose, the allowed directory, and a preview of returned metadata. It is complete enough for an agent to understand the tool's functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'path' is fully described in the input schema (100% coverage), and the description reiterates the directory constraint already present in the schema. No additional meaning is added beyond what the schema provides.
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 clearly states the verb 'Retrieve' and the resource 'metadata about a file or directory', listing specific attributes (size, dates, type, permissions). It distinguishes well from sibling tools like list_directory (list contents) and read_file (read content).
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?
The description explicitly notes the constraint 'Only works within allowed directories: /app', which guides when the tool can be used. However, it does not mention when not to use it or suggest alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_allowed_directoriesA
List all directories the server's FileSystem module is allowed to access.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must convey behavioral traits. It states the tool lists allowed directories but does not explicitly mention that it is a read-only, non-destructive operation. While implied, it lacks explicit disclosure of side effects or safety.
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?
The description is a single, direct sentence with 11 words. It is appropriately concise with no unnecessary information.
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?
Given the tool has no parameters and no output schema, the description is mostly complete. It clearly states the tool's function. However, it does not specify the format of the returned list or any security context, which might be useful for an agent.
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?
The tool has zero parameters, so the description carries no parameter-specific burden. The schema coverage is 100% (empty), and according to guidelines, 0 parameters yields a baseline of 4.
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 clearly states the tool lists allowed directories, using a specific verb ('List') and resource ('directories the server's FileSystem module is allowed to access'). It distinguishes from siblings like list_directory which likely lists directory contents, not access permissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 vs alternatives like show_security_rules or list_directory. Usage is implied, but no exclusions or context on prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_directoryA
List directory contents with [FILE] or [DIR] prefixes. Only works within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Path to the directory to list (default: current shell directory) |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries burden; it mentions prefixes and allowed directories but omits behaviors like recursion depth, hidden files handling, error cases, or read-only nature. It implies non-destructiveness but doesn't state it.
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?
Two concise sentences with no filler. Critical constraint (allowed directories) is front-loaded. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output sample or details on error handling (e.g., invalid path). With no output schema, description should clarify expected result format beyond prefixes. Adequate for a simple list but not fully complete.
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 covers path parameter fully (100%). Description adds value by specifying output formatting with [FILE]/[DIR] prefixes, which is not in schema. Could be slightly more explicit about path format, but overall good.
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?
Clearly states action (list directory contents) and output format (prefixes [FILE] or [DIR]), and distinguishes from siblings like directory_tree by implying a flat list. The scope restriction to /app further clarifies purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies the allowed directory constraint, which is useful context. However, no guidance on when to use this vs siblings like directory_tree or get_file_info, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
move_fileA
Move or rename files and directories. Fails if the destination already exists.Both source and destination must resolve within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Source path | |
| destination | Yes | Destination path |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It correctly notes failure if destination exists and path restrictions, but omits other important traits such as atomicity, whether overwrite is possible under any condition, permissions required, or return value.
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?
Two sentences, no wasted words. Front-loaded with the primary action. Efficiently conveys core information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is adequate for a simple move operation but lacks details on error conditions (e.g., source not found, permissions), return values, or confirmation. Completeness is moderate.
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?
Although the input schema already describes both parameters as paths, the description adds the valuable constraint that both must resolve within allowed directories, which is not explicit in 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?
The description clearly states the verb 'move' and 'rename' with 'files and directories', and specifies a key condition (fails if destination exists) and path restriction, distinguishing it from siblings like copy or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for moving/renaming but provides no explicit guidance on when to use this tool over alternatives like copy (for duplication) or write (for new files), nor does it mention prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_fileA
Read the complete contents of a file from the file system. Handles UTF-8 encoding. Fails if the path is not a file or not accessible. Only works within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file to read |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses UTF-8 handling, failure conditions, and directory restrictions, but omits return format (e.g., content as string) and behavior on large files.
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?
Description is short, front-loaded with purpose, and every sentence adds value. No wasted words.
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 a simple single-param tool with no output schema, the description covers purpose, encoding, failure modes, and restrictions. Slightly lacking return type info, but generally complete given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage and the parameter description is clear. The overall description adds the allowed directories constraint, but no additional semantics beyond schema are provided.
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?
Description clearly states it reads the complete contents of a file from the file system, specifying UTF-8 encoding and constraints like failing on non-file or inaccessible paths. It distinguishes from siblings like write_file, get_file_info, and read_multiple_files.
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?
Description implies when to use (reading a single file's full content) and when not (fail conditions), but lacks explicit when-not statements or alternatives. However, the allowed directories and failure conditions guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_multiple_filesA
Read the contents of multiple files simultaneously.Returns results separated by '---'.Individual file read errors are reported inline.Only works within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | List of file paths to read |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behaviors: return format ('---' separators), inline error reporting, and allowed directory restrictions. No annotations present, so description carries the burden well.
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 concise sentences, each adding essential info. No wasted words, front-loaded with main action.
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?
Adequate for a simple tool with one parameter and no output schema. Covers functionality, formatting, errors, and restrictions. Could mention max file count or ordering, but not critical.
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% with parameter description. Description adds value by explaining simultaneous reading and error handling, beyond the schema's basic type info.
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?
Clearly states verb 'Read' and resource 'multiple files'. Distinguishes from sibling 'read_file' by specifying 'simultaneously' and 'multiple'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage when multiple files need reading, but no explicit comparison to alternatives like 'read_file' or context on when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_filesA
Recursively search for files/directories matching a pattern (case-insensitive). Use exclude_patterns (glob format relative to search path) to ignore paths. Only searches within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Base directory to search in (default: current shell directory) | |
| pattern | Yes | Search pattern (substring match) | |
| exclude_patterns | No | List of glob patterns to exclude (relative to search path) |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Reveals key behaviors: recursive search, case-insensitive matching, allowed directories restricted to /app. No annotations are provided, so description carries the burden and does well.
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 concise sentences, front-loaded with main purpose, no fluff. Every sentence adds value.
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?
Adequately covers search behavior and constraints, but lacks mention of output format (e.g., list of paths) which is reasonable given the context.
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%, but description adds meaning beyond schema by specifying pattern as 'substring match', path default, and exclude patterns as glob relative to search path. Also adds case-insensitivity not in 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?
Description clearly states a specific verb ('Recursively search') and resource ('files/directories'), and distinguishes from siblings like list_directory or directory_tree by emphasizing recursion and case-insensitive matching.
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?
Provides usage hints for exclude_patterns and restricts scope to /app, but no explicit when to use vs. alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
show_security_rulesA
Show security configuration for command execution (allowed commands, flags, primary directory context).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description implies a read-only operation (show) without destructive effects. However, it does not disclose permissions needed, performance characteristics, or whether certain configurations are excluded.
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?
Single, front-loaded sentence that immediately communicates the tool's purpose. No redundant or extraneous words.
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 a simple no-parameter tool without an output schema, the description adequately explains what is shown. However, it lacks details on the output format or structure, which would be helpful for an agent.
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?
No parameters exist, so schema coverage is 100% automatically. Description adds meaning by specifying the content of the output (allowed commands, flags, primary directory context). Baseline for zero params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it shows security configuration for command execution, listing allowed commands, flags, and primary directory context. It distinguishes from siblings like list_allowed_directories by specifying command execution security, though could be more explicit about differences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 list_allowed_directories or execute_command. No when-not-to-use or prerequisite information provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
write_fileB
Create a new file or completely overwrite an existing file with new content. Use with caution. Creates parent directories if needed. Only works within allowed directories:
/app
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file to write | |
| content | Yes | Content to write |
TDQS
B3.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description provides some behavioral details: it creates parent directories if needed, overwrites completely, and only works within allowed directories. It does not mention error handling, permissions, or return values.
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?
The description is short and front-loaded with key information. It efficiently conveys the tool's action and constraints in two sentences plus a list, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a potentially destructive write operation with no output schema, the description is incomplete. It does not explain return values, success/failure indicators, or error conditions, which are important for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters (path and content) with full coverage. The description does not add substantial meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates or overwrites a file with new content. The verb 'create' and 'overwrite' are specific, but it does not differentiate from sibling tool 'edit_file' which might partially modify a file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description cautions 'Use with caution' and specifies allowed directories, which gives some usage context. However, it does not explicitly state when to use this tool versus alternatives like 'edit_file' for partial modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
14 tool updates
v0.1.0- First observed
change_directory - First observed
create_directory - First observed
directory_tree - First observed
edit_file - First observed
execute_command - First observed
get_file_info - First observed
list_allowed_directories - First observed
list_directory - First observed
move_file - First observed
read_file - First observed
read_multiple_files - First observed
search_files - First observed
show_security_rules - First observed
write_file
TDQS
A3.9/5.0
Scored across 14 tools
Disambiguation5/5
Each tool has a clearly distinct purpose: navigation, reading, writing, editing, searching, moving, listing, and command execution. No overlap or ambiguity between tools.
Naming Consistency4/5
Most tools follow a verb_noun pattern (e.g., create_directory, read_file). The only slight inconsistency is 'directory_tree' which lacks a verb, but it remains clear.
Tool Count5/5
14 tools is appropriate for a file system MCP server, covering essential operations without being excessive.
Completeness3/5
Covers most CRUD-like operations but lacks a delete/remove file tool, which is a notable gap for file system tasks. Also missing copy functionality.
Maintenance
ActivityInactive
ResponsivenessNo issues
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
A Model Context Protocol server for Wix AI tools
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that allows secure execution of pre-approved commands, enabling AI assistants to safely interact with the user's system.12 npm22ISC
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables remote execution of shell commands across different operating systems, automatically handling platform-specific differences between Windows and Unix-like systems.1MIT
- AlicenseCqualityDmaintenanceA secure server that implements the Model Context Protocol (MCP) to enable controlled execution of authorized shell commands with stdin support.1MIT