npm package: @neural-cortex/cli
Description: MCP CLI tools for Neural Cortex - Secure modular package following 2025 security best practices
Author: Neural Cortex Team
Latest version: 1.0.0

# Neural Cortex CLI

🧠 **Secure MCP CLI tools for AI-powered development**

[![NPM Version](https://img.shields.io/npm/v/@neural-cortex/cli)](https://npmjs.com/package/@neural-cortex/cli)
[![Security](https://img.shields.io/badge/security-2025%20best%20practices-green)](https://github.com/neural-cortex/cli/security)
[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-blue)](https://modelcontextprotocol.io)

Neural Cortex CLI provides secure, feature-rich command-line tools for interacting with the Model Context Protocol (MCP) server, managing Memory Bank documents, handling tasks, and orchestrating AI-powered development workflows.

## 🚀 Features

### 🔐 Security First (2025 Best Practices)

- **Enhanced Input Validation**: Multi-layer validation with pattern matching
- **Sandboxed Execution**: Resource-limited command execution
- **Path Traversal Protection**: Prevents unauthorized file access
- **Shell Injection Prevention**: Comprehensive metacharacter filtering
- **Resource Monitoring**: Memory and execution time limits
- **Secure Error Handling**: Sanitized error messages in production

### 🧠 MCP Integration

- **Dual Connectivity**: Auto-detection between local and remote MCP servers
- **16 Neural Intelligence Tools**: Complete access to Cortex capabilities
- **Connection Management**: Robust connection handling with fallbacks
- **Health Monitoring**: Real-time server status and reconnection logic

### 📚 Memory Bank Operations

- **Document Management**: Read, write, and search Memory Bank files
- **Cross-Reference Tracking**: Find links between documents
- **Content Synchronization**: Automated sync with TaskMaster
- **Pattern Recognition**: Add architectural patterns and insights

### 📋 Task Management

- **Task Creation**: AI-powered task generation from descriptions
- **Status Tracking**: Update and monitor task progress
- **Dependency Management**: Handle task relationships
- **Progress Logging**: Timestamped accomplishment tracking

## 📦 Installation

```bash
# Install from npm (when published)
npm install -g @neural-cortex/cli

# Or install locally in project
npm install @neural-cortex/cli

# Verify installation
neural-cortex --version
```

## 🔧 Quick Start

```bash
# Show help and available commands
neural-cortex help

# Check CLI status
neural-cortex status

# Connect to MCP server
neural-cortex connection connect

# List available MCP tools
neural-cortex connection list-tools

# Read Memory Bank document
neural-cortex memory read projectBrief.md

# Search Memory Bank
neural-cortex memory search "API design patterns"

# Add a new task
neural-cortex task add "Implement user authentication" -p high

# Update task status
neural-cortex task status 1.0 in-progress

# Get comprehensive project status
neural-cortex system status --details

# Force neural synchronization
neural-cortex system sync --direction bidirectional
```

## 📋 Command Reference

### Connection Management

```bash
neural-cortex connection status          # Show connection status
neural-cortex connection connect         # Connect to MCP server
neural-cortex connection disconnect      # Disconnect gracefully
neural-cortex connection list-tools      # List available tools
```

### Memory Bank Operations

```bash
neural-cortex memory read <file>         # Read Memory Bank file
neural-cortex memory write <file>        # Write to Memory Bank
neural-cortex memory search <query>      # Search documents
```

### Task Management

```bash
neural-cortex task add <title>           # Create new task
neural-cortex task status <id> <status>  # Update task status
```

### Context & Progress

```bash
neural-cortex context update <text>      # Update work context
neural-cortex context log <achievement>  # Log progress
```

### System Operations

```bash
neural-cortex system status             # Project status
neural-cortex system sync               # Force synchronization
neural-cortex system time               # Current system time
```

### Advanced Workflows

```bash
neural-cortex workflow archive          # Archive completed tasks
neural-cortex workflow ingest <prd>     # Ingest PRD file
```

## ⚙️ Configuration

### Environment Variables

```bash
export NODE_ENV=production              # Production mode
export NEURAL_CORTEX_DEBUG=true         # Debug mode
export MCP_SERVER_URL=localhost:3000    # Custom MCP server
```

### Config File (`cortex-config.json`)

```json
{
  "connection": {
    "type": "auto",
    "local": {
      "host": "localhost",
      "port": 3000,
      "timeout": 30000
    },
    "remote": {
      "url": "https://api.neural-cortex.ai",
      "timeout": 60000
    }
  },
  "security": {
    "maxMemoryMB": 500,
    "maxExecutionTimeMs": 60000,
    "enableSandbox": true
  },
  "logging": {
    "level": "info",
    "format": "json"
  }
}
```

## 🔒 Security Features

### Input Validation

- **Pattern Matching**: Regex-based validation for all input types
- **Length Limits**: Configurable limits for arguments and options
- **Type Checking**: Strict type validation for all parameters
- **Encoding Validation**: UTF-8 encoding verification

### Execution Security

- **Sandboxing**: Isolated execution environment
- **Resource Limits**: Memory and CPU usage constraints
- **Timeout Protection**: Prevents long-running operations
- **Privilege Dropping**: Minimal privilege execution

### Network Security

- **TLS/SSL**: Encrypted connections to remote servers
- **Authentication**: Token-based authentication for remote access
- **Certificate Validation**: SSL certificate verification
- **Rate Limiting**: Request throttling and backoff

## 🧪 Testing

```bash
# Run comprehensive test suite
npm test

# Run CLI validation tests
node test/cli-validation.js

# Test specific functionality
npm run test:security
npm run test:integration
npm run test:mcp
```

## 🛠️ Development

### Local Setup

```bash
# Clone repository
git clone https://github.com/neural-cortex/cli.git
cd cli

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build
```

### Project Structure

```
cli/
├── bin/cortex-cli.js           # CLI entry point
├── src/
│   ├── cli/
│   │   ├── handler.js          # Main CLI handler
│   │   ├── commands.js         # Command implementations
│   │   ├── parser.js           # Argument parsing
│   │   └── router.js           # Command routing
│   ├── core/
│   │   ├── connection-manager.js # MCP connection management
│   │   ├── mcp-interface.js    # MCP protocol interface
│   │   └── config.js           # Configuration management
│   └── index.js               # Public API
├── test/
│   ├── cli-validation.js      # CLI test suite
│   └── integration/           # Integration tests
├── .npmrc                     # NPM security config
├── SECURITY.md               # Security documentation
└── README.md                 # This file
```

## 🤝 Contributing

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Follow** security guidelines and coding standards
4. **Test** thoroughly with `npm test`
5. **Commit** changes (`git commit -m 'Add amazing feature'`)
6. **Push** to branch (`git push origin feature/amazing-feature`)
7. **Create** a Pull Request

### Security Guidelines

- All inputs must be validated and sanitized
- Follow 2025 security best practices
- Include security tests for new features
- Document security implications

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🔗 Links

- **Documentation**: [https://docs.neural-cortex.ai](https://docs.neural-cortex.ai)
- **Repository**: [https://github.com/neural-cortex/cli](https://github.com/neural-cortex/cli)
- **Issues**: [https://github.com/neural-cortex/cli/issues](https://github.com/neural-cortex/cli/issues)
- **Security**: [SECURITY.md](SECURITY.md)
- **MCP Protocol**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)

## 🆘 Support

- **Bug Reports**: Create an issue with detailed reproduction steps
- **Feature Requests**: Open an issue with clear use case description
- **Security Issues**: Follow responsible disclosure in [SECURITY.md](SECURITY.md)
- **Questions**: Use GitHub Discussions for community support

---

**Neural Cortex CLI** - Secure, intelligent command-line tools for the future of AI development.