Lupul-Augmentat/docs/tools/README.md

MCP Server Built-in Tools

The MCP server comes with a comprehensive set of built-in tools for common operations. All tools include security features, permission controls, and consistent error handling.

Available Tools

📁 File Operations

Tools for reading, writing, and listing files with security controls.

• FileReadTool - Read file contents
• FileWriteTool - Write content to files
• FileListTool - List directory contents

💻 System Operations

Execute system commands with security restrictions.

• SystemCommandTool - Execute whitelisted system commands

🌐 Network Operations

Make HTTP requests to external services.

• HttpRequestTool - Make HTTP/HTTPS requests

Permission Model

Each tool requires specific permissions to execute:

Tool	Required Permission	Description
FileReadTool	file:read	Read access to files
FileWriteTool	file:write	Write access to files
FileListTool	file:read	Read access to directories
SystemCommandTool	system:exec	Execute system commands
HttpRequestTool	network:http	Make HTTP requests

Security Features

All built-in tools implement comprehensive security controls:

🛡️ Path Security

• Directory traversal prevention - Blocks .. and absolute paths outside allowed directories
• Restricted directories - Cannot access system directories like /etc, /sys, /proc
• Allowed paths - Only current working directory and system temp directory

🔒 Input Validation

• Schema validation - All inputs validated with Zod schemas
• Command whitelisting - Only safe system commands allowed
• Shell injection prevention - Blocks shell operators in arguments
• URL validation - Validates and blocks private IP ranges

⏱️ Resource Limits

• Timeouts - All operations have configurable timeouts
• Size limits - File operations limited to 10MB
• Output limits - Command output limited to 1MB

Error Handling

All tools follow consistent error handling patterns:

try {
  const result = await mcp.callTool('tool_name', params);
  // Handle success
} catch (error) {
  // Errors include:
  // - Permission denied
  // - Invalid input
  // - Resource not found
  // - Timeout exceeded
  // - Operation failed
}

Usage Examples

Reading a Configuration File

const config = await mcp.callTool('file_read', {
  path: './config.json'
});
const parsedConfig = JSON.parse(config.content);

Writing Log Data

await mcp.callTool('file_write', {
  path: './logs/app.log',
  content: `[${new Date().toISOString()}] Application started\n`,
  mode: 'append'
});

Listing Project Files

const files = await mcp.callTool('file_list', {
  path: './src',
  recursive: true,
  pattern: '*.js'
});

Running System Commands

const result = await mcp.callTool('system_command', {
  command: 'grep',
  args: ['-r', 'TODO', '.'],
  cwd: './src'
});

Making API Requests

const response = await mcp.callTool('http_request', {
  url: 'https://api.github.com/user',
  headers: {
    'Authorization': 'token YOUR_TOKEN'
  }
});

Best Practices

1. Always handle errors - Tools can fail for various reasons
2. Use appropriate timeouts - Don't let operations hang
3. Validate inputs - Even though tools validate, check your data
4. Check permissions - Ensure required permissions are granted
5. Use relative paths - More portable than absolute paths
6. Respect rate limits - Especially for HTTP requests
7. Log operations - Track what tools are doing

Extending with Custom Tools

While built-in tools cover common use cases, you can create custom tools for specific needs. See the Module Development Guide for details on creating custom tools.

Tool Lifecycle

1. Input validation - Schema validation with Zod
2. Permission check - Verify required permissions
3. Pre-execution hooks - Custom validation/preparation
4. Execution - Actual tool operation
5. Output formatting - Consistent response format
6. Error handling - Structured error responses

Performance Considerations

• File operations are synchronous within the tool
• HTTP requests use native fetch API
• System commands spawn child processes
• All operations subject to timeout limits
• Large file operations may impact performance

Troubleshooting

Permission Denied

Error: Permission denied: file:read required

Ensure the tool has required permissions in the auth context.

Invalid Path

Error: Invalid path: directory traversal not allowed

Use paths within the current directory or temp directory.

Command Not Allowed

Error: Command not allowed: rm

Only whitelisted commands can be executed.

Timeout Exceeded

Error: Request timeout after 30000ms

Increase timeout or optimize the operation.

Version History

• v0.1.0 - Initial release with basic file, system, and HTTP tools
• v0.2.0 - Added security controls and permission system
• v0.3.0 - Enhanced error handling and validation