🐺 Initial commit - Lupul Augmentat MCP Server

- MCP server cu stdio transport pentru performanță maximă
- Tool-uri pentru file operations, HTTP requests, system commands
- Suport NATS pentru comunicare inter-module
- Configurare nginx cu API key auth și SSL
- Arhitectură modulară și extensibilă

🤖 Generated with Claude Code

docs/tools/README.md

@@ -0,0 +1,182 @@
+# 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