Neural Cortex CLI

🧠 Secure MCP CLI tools for AI-powered development

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

# 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

# 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

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

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

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

Context & Progress

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

System Operations

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

Advanced Workflows

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

⚙️ Configuration

Environment Variables

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)

{
  "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

# 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

# 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 file for details.

🔗 Links

• Documentation: https://docs.neural-cortex.ai
• Repository: https://github.com/neural-cortex/cli
• Issues: https://github.com/neural-cortex/cli/issues
• Security: SECURITY.md
• MCP Protocol: 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
• Questions: Use GitHub Discussions for community support

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