Documentation

Installation

Two recommended options: AppImage for any Linux system, or Nix for reproducible builds.

# Install to ~/.local/bin (user)
curl -fsSL https://raw.githubusercontent.com/NacoSolutions/modern-cli-mcp/main/install.sh | sh

# Install to /usr/local/bin (system-wide)
curl -fsSL https://raw.githubusercontent.com/NacoSolutions/modern-cli-mcp/main/install.sh | sh -s -- --system

# Run from GitHub (latest)
nix run github:NacoSolutions/modern-cli-mcp

# Run from FlakeHub (versioned)
nix run "https://flakehub.com/f/NacoSolutions/modern-cli-mcp/0.4.tar.gz"

# flake.nix
{
  inputs.modern-cli-mcp.url = "github:NacoSolutions/modern-cli-mcp";
  # or FlakeHub: "https://flakehub.com/f/NacoSolutions/modern-cli-mcp/*.tar.gz"
}

nix-build https://github.com/NacoSolutions/modern-cli-mcp/archive/main.tar.gz -A defaultNix.default
./result/bin/modern-cli-mcp

cargo install --git https://github.com/NacoSolutions/modern-cli-mcp

Configuration

Add to your MCP client's config file:

{
  "mcpServers": {
    "modern-cli": {
      "command": "~/.local/bin/modern-cli-mcp",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "modern-cli": {
      "command": "nix",
      "args": ["run", "github:NacoSolutions/modern-cli-mcp", "--"]
    }
  }
}

Config File Locations

• ~/.claude/settings.json — Claude Code
• ~/.config/claude/claude_desktop_config.json — Claude Desktop
• ~/.cursor/mcp.json — Cursor
• ~/.config/cline/mcp_settings.json — Cline

Agent Profiles

Profiles pre-expand relevant tool groups for specific agent roles, reducing cognitive load and improving response latency. Use the --profile flag to select a profile.

Usage

# Run with a specific profile
nix run github:NacoSolutions/modern-cli-mcp -- --profile explore

# List available profiles
nix run github:NacoSolutions/modern-cli-mcp -- --list-profiles

# List tool groups
nix run github:NacoSolutions/modern-cli-mcp -- --list-groups

MCP Configuration with Profile

{
  "mcpServers": {
    "modern-cli": {
      "command": "nix",
      "args": ["run", "github:NacoSolutions/modern-cli-mcp", "--", "--profile", "explore"]
    }
  }
}

Available Profiles

Tool Discovery

Even with a limited profile, agents can discover additional tools:

• list_tool_groups — List all 15 tool groups with descriptions
• expand_tools <group> — Show all tools in a specific group

Dynamic Toolsets (Beta)

Start with minimal tools and enable groups on demand. Reduces cognitive load for AI agents by exposing only relevant tools.

Enable Dynamic Mode

{
  "mcpServers": {
    "modern-cli": {
      "command": "nix",
      "args": ["run", "github:NacoSolutions/modern-cli-mcp", "--", "--dynamic-toolsets"]
    }
  }
}

Pre-enable Specific Toolsets

{
  "mcpServers": {
    "modern-cli": {
      "command": "nix",
      "args": ["run", "github:NacoSolutions/modern-cli-mcp", "--", "--dynamic-toolsets", "--toolsets=filesystem,git"]
    }
  }
}

Meta-tools

In dynamic mode, these tools are always available:

• list_available_toolsets — Show all toolsets and their enabled status
• get_toolset_tools — Preview tools in a toolset before enabling
• enable_toolset — Activate a toolset (use "all" for everything)

Available Toolsets

.agentignore

Control which files AI agents can access using .agentignore files. Uses gitignore syntax but operates independently—tools respect .agentignore only, not .gitignore.

Pattern Sources

Patterns are loaded from (in order of precedence):

1. ~/.config/agent/ignore — Global patterns for all projects
2. .agentignore — Per-directory patterns (walked up from working directory)

Example

# Secrets and credentials
*.secret
.env*
secrets/
credentials.json

# Large generated files
node_modules/
target/
*.min.js

# Sensitive data
*.pem
*.key

Behavior

• Blocked paths return an error: Path is blocked by .agentignore
• Search tools (fd, rg, ast-grep) automatically apply ignore patterns
• Patterns in child directories extend (not replace) parent patterns

Usage

Once configured, the tools are available to your AI assistant. Example prompts:

Environment Variables