# 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**](./file-operations.md#filereadtool) - Read file contents
- [**FileWriteTool**](./file-operations.md#filewritetool) - Write content to files
- [**FileListTool**](./file-operations.md#filelisttool) - List directory contents

### 💻 System Operations
Execute system commands with security restrictions.

- [**SystemCommandTool**](./system-command.md) - Execute whitelisted system commands

### 🌐 Network Operations
Make HTTP requests to external services.

- [**HttpRequestTool**](./http-request.md) - 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:

```javascript
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
```javascript
const config = await mcp.callTool('file_read', {
  path: './config.json'
});
const parsedConfig = JSON.parse(config.content);
```

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

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

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

### Making API Requests
```javascript
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](../modules/development.md) 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