Skip to main content
Glama

AICoreUtils

AI-CLI MCP server Glama Score PyPI

CI LTS

Glama 92% | TDQS A-grade (mean 4.6) | All 114 tools A-grade | CI passed on all platforms

⚠️ Stability: This project is actively evolving. While the JSON output schema and MCP tool interface are stable, internal CLI argument parsing and per-command flags may change. Read Stability Notes for details.

🤖 MCP directory listed: Glama · ModelScope · awesome-mcp-servers

Chinese Description

AICoreUtils is a JSON-first command-line toolkit prototype for LLM Agents. It is inspired by common GNU Coreutils commands, but it is not a complete GNU-compatible replacement.

The project goal is to provide deterministic, low-noise, and easy-to-parse CLI interfaces for machine callers:

  • Default JSON output

  • Errors written to stderr as JSON

  • Stable exit code semantics

  • --dry-run support for file modification commands

  • Explicit use of --raw when pipeline composition is required

Quick Start

pip install aicoreutils
aicoreutils schema --pretty
aicoreutils ls . --limit 20
aicoreutils rm build --recursive --dry-run

🤖 Claude Desktop / MCP Integration

One-line configuration to let Claude operate your filesystem directly:

Edit the Claude Desktop configuration file (detailed instructions →):

System

Config File

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aicoreutils": {
      "command": "python",
      "args": ["-m", "aicoreutils.mcp_server"]
    }
  }
}

Restart Claude Desktop, then ask it:

"List all Python files in the project and count the lines of code"

Claude automatically calls aicoreutils ls + aicoreutils wc, with JSON interaction throughout.

For more integration methods: aicoreutils tool-list --format openai outputs in OpenAI Function Calling format, which can be used directly in any Agent framework. If you need to retain risk tags for schedulers or audit systems, you can append --include-risk.

⚠️ Security Note: It is recommended to run with minimum privileges in production environments.

aicoreutils-mcp --profile readonly         # 推荐:只读工具
aicoreutils-mcp --profile workspace-write  # 仅允许低风险 cwd 内写入

See Production Security Deployment Guide →

🤖 AI IDE Integration

Use aicoreutils directly in Cursor / Windsurf / Continue.dev: AI IDE Integration Guide →

// ~/.cursor/mcp.json
{ "mcpServers": { "aicoreutils": { "command": "python", "args": ["-m", "aicoreutils.mcp_server"] } } }

🔗 More: Claude Desktop Integration | AI IDE Integration | Agent Task Examples | LangChain Wrapper

Run Tests

# 推荐主入口(pytest,含 Hypothesis property-based 测试和 GNU 对照测试)
uv run pytest tests/ -v --tb=short

# Legacy 入口(unittest,部分运行器)
uv run python -m unittest discover -s tests -v

Project Structure

.
|-- src/aicoreutils/        # Python 包源码
|-- docs/                   # 文档入口
|   |-- reference/          # 协议、命令面和安全生产契约
|   |-- guides/             # 使用指南
|   |-- architecture/       # 架构决策记录 (ADR) 和 AI 代理规则
|   |-- development/        # 测试和开发说明
|   |-- status/             # 当前项目状态(唯一权威来源)
|   |-- audits/             # 兼容性和质量审计
|   |-- analysis/           # 项目分析日志(历史归档)
|   `-- reports/            # 测试报告等生成/归档文档
|-- tests/                  # 测试套件
|-- examples/               # 示例
|-- scripts/                # CI/审计/发布脚本
|-- .github/                # CI workflows 和 issue 模板
`-- vendor/                 # 本地上游源码缓存

Documentation

Release Status

Current implementation: 114 CLI commands registered in aicoreutils schema (including agent meta-commands like tool-list).

Important limitation: This project is an agent-friendly subset inspired by GNU Coreutils, not a full GNU Coreutils clone.


Related MCP server: nexus-mcp

English

AICoreUtils is a JSON-first command-line toolkit prototype for LLM agents. It is inspired by common GNU Coreutils commands, but it is not a complete GNU-compatible replacement.

The goal is a deterministic, low-noise interface for machine callers:

  • JSON output by default

  • JSON errors on stderr

  • Stable semantic exit codes

  • --dry-run for mutation commands

  • Explicit --raw output for pipeline composition

Quick Start

pip install aicoreutils
aicoreutils schema --pretty
aicoreutils ls . --limit 20
aicoreutils rm build --recursive --dry-run

🤖 Claude Desktop / MCP Integration

One config line to let Claude operate your filesystem:

Edit Claude Desktop config (full guide →):

OS

Config File

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aicoreutils": {
      "command": "python",
      "args": ["-m", "aicoreutils.mcp_server"]
    }
  }
}

Restart Claude Desktop, then ask:

"List all Python files in the project and count lines of code"

Claude calls aicoreutils ls + aicoreutils wc automatically.

For other frameworks: aicoreutils tool-list --format openai outputs OpenAI Function Calling format directly. Add --include-risk when an orchestrator or audit system needs machine-readable risk metadata.

⚠️ Security: Run with least privilege in production.

aicoreutils-mcp --profile readonly         # Recommended: read-only tools
aicoreutils-mcp --profile workspace-write  # Low-risk cwd-local writes only

See Production Security Guide →

Run tests

# Recommended primary entry (pytest, includes Hypothesis property-based and GNU differential tests)
uv run pytest tests/ -v --tb=short

# Legacy entry (unittest, partial runner)
uv run python -m unittest discover -s tests -v

Project Layout

.
|-- src/aicoreutils/        # Python package
|-- docs/                   # documentation index
|   |-- reference/          # protocol, command-surface and security contracts
|   |-- guides/             # usage guides
|   |-- architecture/       # ADRs and AI agent governance rules
|   |-- development/        # testing and development notes
|   |-- status/             # current project status (single authoritative source)
|   |-- audits/             # compatibility and quality audits
|   |-- analysis/           # project analysis logs (historical archive)
|   `-- reports/            # test reports and archived generated docs
|-- tests/                  # test suite
|-- examples/               # examples
|-- scripts/                # CI/audit/release scripts
|-- .github/                # CI workflows and issue templates
`-- vendor/                 # local upstream source cache

Documentation

Release Status

Current implementation: 114 CLI commands in aicoreutils schema (including agent-native meta-commands like tool-list).

Important limitation: this project is an agent-friendly subset inspired by GNU Coreutils, not a full GNU Coreutils clone.

Stability and SemVer

aicoreutils uses semantic versioning starting from v1.0.0, with the following commitments:

  • Patch (1.0.x): Bug fixes, improved error messages, documentation updates. JSON output structure remains unchanged.

  • Minor (1.x.0): New commands, new parameters. JSON output structure for existing commands remains backward compatible.

  • Major (x.0.0): Breaking changes — JSON schema changes, command renaming, MCP tool schema changes.

⚠️ Current status: The project is still under active development. Internal CLI argument parsing and per-command flags may change frequently due to argparse refactoring, but the JSON envelope (ok, result, error, command, version) and MCP tool schema are stable. For production use, please pin the version number (pip install aicoreutils==1.2.0). v1.2.0 is the LTS version, and critical bug and security fixes will be backported for at least 12 months.

Available Tools

100 tools
[A
Read-only

Evaluate path predicates (file existence, type, permissions) — alias for 'test'. Read-only, no side effects. Returns JSON with predicate result and success/failure exit code. Use in scripts for conditional file checks. Not for detailed file inspection — use 'stat' for full metadata. See also 'test', 'stat'.

Inputs: tokens, exit_code, bracket_file, bracket_exists, +6 more.

archA
Read-only

Return the machine architecture string (e.g., x86_64, aarch64). Read-only, no side effects. Returns JSON with the architecture name. Use for platform-conditional logic in agent workflows. Not for full system information — use 'uname' for kernel, hostname, and OS details. See also 'uname'.

Inputs: raw.

b2sumA
Read-only

Compute BLAKE2b cryptographic hash of files or stdin as JSON. Read-only, no side effects. Returns per-file hash digests and byte counts. Use for high-speed integrity verification — faster than SHA-2/3 on 64-bit platforms. Not for security-critical contexts where SHA-256 is mandated — use 'sha256sum'. See also 'hash', 'sha256sum'.

Inputs: check, paths, encoding, show_encoding, +2 more.

base32A
Read-only

Encode or decode base32 data from files or stdin. Read-only, no side effects. Returns JSON with the result by default; use --raw for raw output on stdout. Use for human-friendly encoding (avoids ambiguous characters). Not for compact encoding — use 'base64' for smaller output size. See also 'base64', 'basenc'.

Inputs: raw, paths, decode, encoding, +4 more.

base64A
Read-only

Encode or decode base64 data from files or stdin. Read-only, no side effects. Returns JSON with the result by default; use --raw for raw output on stdout. Use for standard base64 encoding in data transfer and storage. Not for flexible multi-base handling — use 'basenc' to switch between base16/32/64/64url. See also 'base32', 'basenc'.

Inputs: raw, paths, decode, encoding, +4 more.

basenameA
Read-only

Return the final path component, stripping all directory prefixes. Read-only, no side effects. Returns JSON with the stripped filename. Use to extract filenames from full paths. Not for extracting directory portions — use 'dirname' for the inverse operation. See also 'dirname', 'realpath'.

Inputs: paths (required), raw, suffix.

basencA
Read-only

Encode or decode data in base16 (hex), base32, base64, or base64url from files or stdin. Read-only, no side effects. Returns JSON with encoded/decoded data by default; use --raw for raw bytes on stdout. Select format with --base (default base64), switch to decode mode with --decode. Use --max_output_bytes to bound output size. Use when you need flexible base selection via a single tool. Not for fixed-format needs — use 'base64' or 'base32' for dedicated encoding. See also 'base64', 'base32'.

Inputs: raw, base, paths, decode, +5 more.

catA
Read-only

Read and output file contents. Read-only, no side effects. Returns JSON by default with bounded content; use --raw for full plain-text output. Supports byte-offset and length for partial reads. Use to inspect file contents in agent workflows. Not for binary inspection — use 'od' for hex/octal dumps. See also 'head', 'tail', 'od'.

Inputs: path (required), raw, offset, encoding, +4 more.

catalogA
Read-only

List all commands organized by GNU Coreutils priority categories. Read-only, no side effects. Returns JSON with commands grouped by priority (P0=essential, P1=common, P2=useful, P3=specialized). Use to discover the full command surface by functional area. Not for LLM function-calling context — use 'tool-list' for machine-optimized output. See also 'tool-list', 'coreutils'.

Inputs: search, category.

chconA
Destructive

Plan or apply an SELinux security context to files. Destructive: may alter file security labels, affecting access control. Use --dry_run to preview without changes. Requires --allow_context for actual execution; fails safely otherwise. Use to manage SELinux contexts on labeled filesystems. Not for general permission changes — use 'chmod'. See also 'runcon', 'chmod'.

Inputs: paths (required), context (required), raw, dry_run, +3 more.

chgrpA
Destructive

Change file group ownership with dry-run support. Destructive: modifies filesystem group metadata. Use --dry_run to preview changes safely. Returns JSON with operation result. Use to reassign group ownership of files. Not for changing user ownership — use 'chown'. Not for permission changes — use 'chmod'. See also 'chown', 'chmod'.

Inputs: paths (required), group, dry_run, no_follow, +1 more.

chmodA
Destructive

Change file permissions using octal modes (e.g., 644, 755). Destructive: modifies filesystem permission bits. Use --dry_run to preview without changing. Returns JSON with old and new mode values. Use to control read/write/execute access. Not for ownership changes — use 'chown' or 'chgrp'. See also 'chown', 'chgrp'.

Inputs: paths (required), mode, dry_run, no_follow, +1 more.

chownA
Destructive

Change file user ownership with dry-run support. Destructive: modifies filesystem ownership metadata. May require elevated privileges. Use --dry_run to preview. Returns JSON with operation result. Use to transfer file ownership between users. Not for group-only changes — use 'chgrp'. Not for permission changes — use 'chmod'. See also 'chgrp', 'chmod'.

Inputs: paths (required), owner, dry_run, no_follow, +1 more.

chrootA
Destructive

Plan or run a command inside a changed root directory. Destructive: isolates command execution to a new filesystem root. May require elevated privileges. Use --dry_run to preview. Requires --allow_chroot for execution; fails safely otherwise. Use to test software in isolated environments. Not for simple directory changes — use 'cd' or path arguments on other commands. See also 'runcon'.

Inputs: root (required), dry_run, timeout, allow_chroot, +2 more.

cksumA
Read-only

Compute CRC32 checksums and byte counts for files or stdin. Read-only, no side effects. Returns JSON with checksum and byte count per file. Use for fast data-transmission integrity verification. Not for cryptographic security — use 'sha256sum' or 'b2sum'. See also 'sha256sum', 'md5sum', 'sum'.

Inputs: raw, paths, encoding, show_encoding, +2 more.

commA
Read-only

Compare two sorted files line by line, returning column-tagged records (unique to file1, unique to file2, common). Read-only, no side effects. Requires pre-sorted input — use 'sort' first. Returns JSON with structured comparison results. Use to find differences and overlaps between datasets. Not for unsorted data — results are wrong without prior sorting. See also 'join', 'uniq', 'sort'.

Inputs: paths (required), raw, encoding, max_lines, +6 more.

coreutilsA
Read-only

List all available commands as a flat text index. Read-only, no side effects. Use --list to enumerate tool names, --raw for plain text without JSON envelope. Use for quick overview of installed commands. Not for LLM tool discovery — use 'tool-list' for structured function-calling metadata. See also 'catalog', 'tool-list'.

Inputs: raw, list.

cpA
Destructive

Copy files and directories with dry-run and overwrite protection. Destructive to destination: creates new copies on the filesystem. Overwrite protection enabled by default — use --allow_overwrite to replace existing files. Use --dry_run to preview the operation safely. Returns JSON with source and destination paths. Use to duplicate files or directories. Not for moving files — use 'mv' to relocate without copying. Not for setting permissions on copy — use 'install'. See also 'mv', 'install'.

Inputs: source (required), destination (required), dry_run, parents, +2 more.

csplitA
Destructive

Split input into multiple files at regex match points with dry-run and overwrite protection. Destructive: creates output files on the filesystem. Use --dry_run to preview split points without creating files. Returns JSON with generated filenames and record counts. Use to partition data by content patterns. Not for fixed-size splitting — use 'split' for line-count or byte-size chunks. See also 'split'.

Inputs: path (required), prefix, dry_run, pattern, +8 more.

cutA
Read-only

Select specific fields, characters, or bytes from each input line. Read-only, no side effects. Returns JSON with the extracted columns by default; use --raw for plain text. Use to extract columns from tabular or delimited data. Not for replacing characters — use 'tr' for translation/deletion. Not for merging columns — use 'paste'. See also 'paste', 'tr'.

Inputs: raw, bytes, chars, paths, +8 more.

dateA
Read-only

Return current system time or parse a supplied date string as structured JSON. Read-only, no side effects. Returns JSON with ISO 8601 timestamp and timezone-aware fields. Use to query the system clock or validate date strings in agent workflows. Not for measuring elapsed time — use 'uptime' for system runtime or combine 'date' with arithmetic. See also 'uptime'.

Inputs: raw, utc, format, iso_8601, +1 more.

ddA
Destructive

Copy and convert data blocks between input and output with bounded preview and dry-run support. Destructive to output: writes data to the destination file. Use --dry_run to preview the operation. Returns JSON with bytes read/written and throughput. Use for block-level data copying and format conversion. Not for simple file copying — use 'cp' for files and directories. See also 'cp', 'truncate'.

Inputs: bs, raw, conv, seek, +9 more.

dfA
Read-only

Return disk space usage for mounted filesystems as JSON. Read-only, no side effects. Returns JSON with total, used, available, and usage percentage per filesystem. Use to check free space and monitor storage across mount points. Not for per-directory usage — use 'du' for directory-level detail. See also 'du'.

Inputs: paths.

dirA
Read-only

List directory contents in column-aligned format — alias for 'ls' producing structured JSON. Read-only, no side effects. Supports recursive depth, hidden files, symlink following, streaming (NDJSON), and result limiting. Returns per-entry metadata: type, size, permissions, modification time. Use for clean tabular directory listings. Prefer 'dir' over 'ls' when column-aligned output is desired; prefer 'ls' for default list format. Not for extended metadata — use 'vdir' for verbose output or 'stat' for single-file detail. See also 'ls', 'vdir', 'stat'.

Inputs: path, limit, stream, max_depth, +3 more.

dircolorsA
Read-only

Return LS_COLORS configuration mapping file types to ANSI color codes. Read-only, no side effects. Returns JSON with the color mapping; color output disabled by default for agent-friendly display. Use to inspect how the shell colors file listings. Not for actual directory listing — use 'ls' or 'dir'. See also 'ls'.

Inputs: raw, shell.

dirnameA
Read-only

Return the parent directory portion of file paths, stripping the final component. Read-only, no side effects. Returns JSON with the directory path. Use to extract directory prefixes from full paths. Not for extracting the filename — use 'basename' for the final component. See also 'basename', 'realpath'.

Inputs: paths (required), raw.

duA
Read-only

Estimate file and directory space usage recursively as JSON. Read-only, no side effects (stat-only, does not write). Returns JSON with per-directory byte counts. Use to find space-consuming directories and files. Not for filesystem-level overview — use 'df' for mounted filesystem totals. See also 'df', 'stat'.

Inputs: paths, max_depth, follow_symlinks.

echoA
Read-only

Output provided text as JSON. Read-only, no side effects. Returns JSON with the echoed text by default; use --raw for plain text output. Use to display values or construct output strings in agent pipelines. Not for formatted output — use 'printf' for precise format control with conversion specifiers. See also 'printf'.

Inputs: raw, words, escapes, encoding, +4 more.

envA
Read-only

Return all environment variables or filter by name pattern as structured JSON. Read-only, no side effects. Returns JSON with key-value pairs of environment variables. Use to inspect the execution context available to child processes. Not for querying a single variable by exact name — use 'printenv' for direct lookup. See also 'printenv'.

Inputs: raw, names.

expandA
Read-only

Convert tab characters to spaces in files or stdin. Read-only, no side effects (does not modify files). Returns JSON with the converted text by default; use --raw for plain output. Use configurable tab stops to control spacing. Use to normalize indentation to spaces. Not for converting spaces to tabs — use 'unexpand' for the reverse operation. See also 'unexpand'.

Inputs: raw, tabs, paths, encoding, +4 more.

exprA
Read-only

Evaluate arithmetic and string expressions in a safe, side-effect-free AST subset. Read-only, no side effects. Supports +, -, *, /, % (arithmetic), comparisons, regex matching, and string operations. Returns JSON with the computed result. Use for calculations and conditional logic in agent workflows. Not for file-based predicate tests — use 'test' or '[' for path checks. See also 'test', 'factor'.

Inputs: tokens (required), raw, exit_code.

factorA
Read-only

Compute the prime factorization of given non-negative integers. Read-only, no side effects. Returns JSON with an array of prime factors for each input number. Use to decompose integers into prime components. Not for general arithmetic — use 'expr' for calculations. See also 'expr'.

Inputs: raw, numbers, max_value.

falseA
Read-only

Exit with status 1 (failure). Idempotent: always returns code 1, takes no arguments, has zero side effects. Returns JSON error envelope indicating failure on stderr. Use to explicitly signal error or failure conditions in scripts and agent flows. Not for a no-op success — use 'true'. See also 'true'.

Inputs: no named parameters.

fmtA
Read-only

Reflow paragraphs to a target character width, preserving paragraph boundaries (blank-line separated). Read-only, no side effects. Returns JSON with reflowed text by default; use --raw for plain output. Use to reformat prose without breaking paragraph structure. Not for hard line wrapping — use 'fold' to break at exact character positions without paragraph awareness. See also 'fold'.

Inputs: raw, paths, width, encoding, +4 more.

foldA
Read-only

Wrap long input lines at a fixed character width, breaking at exact positions. Read-only, no side effects. Returns JSON with wrapped text by default; use --raw for plain output. Use for display-constrained formatting or terminal-width adaptation. Not for paragraph-aware reflowing — use 'fmt' to preserve paragraph structure. See also 'fmt'.

Inputs: raw, paths, width, encoding, +5 more.

ginstallA
Destructive

Copy files and set attributes like permissions and ownership — GNU-compatible alias for 'install'. Destructive: creates or overwrites target files, creates directories with --directory/--parents, and changes file metadata. Default mode is 755. Use --dry_run to preview without touching the filesystem. Returns JSON with installation paths and status. Use when GNU install semantics or BSD-compatible behavior is needed. Not for simple copying — use 'cp' for copying without permission setting. Not for the standard install interface — use 'install'. See also 'install', 'cp'.

Inputs: mode, paths, dry_run, parents, +2 more.

groupsA
Read-only

Return group names and IDs for a specified user or the current process. Read-only, no side effects. Returns JSON with group list. Use to verify group membership for access control decisions. Not for full user identity inspection — use 'id' for UID/GID plus all groups. Not for current username — use 'whoami'. See also 'id', 'whoami'.

Inputs: raw, user.

hashA
Read-only

Compute hash digests of files or stdin with selectable algorithm (MD5, SHA-1, SHA-2, BLAKE2b). Read-only, no side effects. Returns JSON with per-file digests and byte counts. Use when you need flexible algorithm selection from a single tool. Not for fixed-algorithm workflows — use dedicated tools ('md5sum', 'sha256sum', 'b2sum') for consistent output. See also 'md5sum', 'sha256sum', 'b2sum'.

Inputs: check, paths, encoding, algorithm, +3 more.

hostidA
Read-only

Return a deterministic host identifier in hexadecimal format. Read-only, no side effects. Returns JSON with the host ID. Use for stable machine identification. Not for the human-readable hostname — use 'hostname'. Not for full system info — use 'uname'. See also 'hostname', 'uname'.

Inputs: raw.

hostnameA
Read-only

Return the system hostname as JSON. Read-only, no side effects. Returns JSON with the hostname string. Use to identify the machine in network contexts. Not for numeric host ID — use 'hostid'. Not for full system info — use 'uname'. See also 'hostid', 'uname'.

Inputs: raw.

idA
Read-only

Return user identity information: UID, GID, username, and all group memberships as JSON. Read-only, no side effects. Returns JSON with full user identity. Use for comprehensive user identity inspection and access control auditing. Not for quick username check — use 'whoami'. Not for just group listing — use 'groups'. See also 'whoami', 'groups'.

Inputs: raw.

installA
Destructive

Copy files and set attributes (permissions, ownership) to destination. Destructive: creates files and directories, overwrites existing targets with --allow_overwrite, sets mode (default 755). Use --dry_run for safe preview. Returns JSON with installation paths and status. Use for software deployment scripts and Makefile install targets. Not for simple file copying without permission changes — use 'cp'. Not for GNU-install-compatible behavior — use 'ginstall'. See also 'cp', 'ginstall'.

Inputs: mode, paths, dry_run, parents, +2 more.

joinA
Read-only

Join two sorted files on a common field (default: first whitespace-separated field), performing an inner join. Read-only, no side effects. Requires pre-sorted input — use 'sort' first. Returns JSON with joined records. Use to combine related datasets by key. Not for unsorted input — results are wrong without prior sorting. Not for side-by-side merging without key matching — use 'paste'. See also 'paste', 'comm', 'sort'.

Inputs: paths (required), raw, field1, field2, +7 more.

killA
Destructive

Plan or send a signal to a process by PID. Potentially destructive: can terminate or alter process execution. Use --dry_run to preview the signal without sending. Requires --allow_signal for actual signal delivery; fails safely otherwise. Use to signal, terminate, or restart processes in agent workflows. Not for process listing — use 'ps' or 'pidof' externally. See also 'nohup'.

Inputs: pids (required), signal, dry_run, allow_signal.

lnA
Destructive

Create hard or symbolic links with dry-run and overwrite protection. Destructive: creates filesystem links. Use --symbolic for symlinks (cross-filesystem, can point to directories). Overwrite protection enabled by default. Use --dry_run to preview. Returns JSON with link path and type. Use for creating filesystem aliases. Not for hard-link-only operations — use 'link' for guaranteed hard links. Not for copying — use 'cp'. See also 'link', 'cp'.

Inputs: source (required), destination (required), dry_run, parents, +2 more.

lognameA
Read-only

Return the original login name of the current user (unaffected by su/sudo). Read-only, no side effects. Returns JSON with the login name. Use to determine the original session identity bypassing privilege escalation. Not for the effective user ID — use 'whoami'. See also 'whoami', 'id'.

Inputs: raw.

lsA
Read-only

List directory contents as structured JSON with per-entry metadata (type, size, permissions, modification time). Read-only, no side effects. Supports recursive depth, hidden file inclusion, symlink following, result limiting, and NDJSON streaming for large directories. Use for programmatic directory inspection. Not for column-aligned output — use 'dir'. Not for verbose metadata — use 'vdir'. Not for single-file detail — use 'stat'. See also 'dir', 'vdir', 'stat'.

Inputs: path, limit, stream, max_depth, +3 more.

md5sumA
Read-only

Compute MD5 hash digests of files or stdin. Read-only, no side effects. Returns JSON with per-file hash values and byte counts. Use for fast non-cryptographic integrity checks and data deduplication. Not for security or cryptographic verification — MD5 is collision-broken; use 'sha256sum' or 'b2sum' for security. See also 'sha256sum', 'hash'.

Inputs: check, paths, encoding, show_encoding, +2 more.

mkdirA
Destructive

Create directories with parent-directory creation and dry-run support. Destructive: creates new directories on the filesystem. Use --dry_run to preview without creating. Use --parents to auto-create intermediate directories. Use --mode to set permissions. Returns JSON with created paths. Fails safely if the path already exists (unless forced). Use to create directory structures. Not for removing directories — use 'rmdir' for empty directories or 'rm' for non-empty. Not for temporary directories — use 'mktemp' for unique temp paths. See also 'rmdir', 'mktemp', 'touch'.

Inputs: paths (required), dry_run, parents, exist_ok.

mkfifoA
Destructive

Create named pipes (FIFOs) for inter-process communication. Destructive: creates a special file that blocks readers until a writer connects (and vice versa). Fails safely if the path already exists (idempotent). Use --dry_run to preview without touching the filesystem. Use --mode to set permissions (default 666). Use --parents to auto-create missing parent directories. Returns JSON with the created path, mode, and status on success; on error, returns structured JSON with exit code and error message on stderr. Use when you need a FIFO pipe for shell-style IPC between processes. Not for creating regular files — use 'touch'. Not for regular directories — use 'mkdir'. Not for device nodes — use 'mknod'. See also 'mknod', 'mkdir', 'touch'.

Inputs: paths (required), mode, dry_run, parents.

mknodA
Destructive

Create device nodes (block or character special files) with dry-run support. Destructive: creates special device files. May require elevated privileges. Use --dry_run to preview. Returns JSON with the created node path and type. Use to create device files for hardware access. Not for FIFO pipes — use 'mkfifo' for named pipes. Not for regular files — use 'touch'. See also 'mkfifo'.

Inputs: paths (required), mode, dry_run, parents, +1 more.

mktempA
Destructive

Create temporary files or directories with unique, unpredictable names atomically to prevent race conditions. Destructive: creates files/dirs on the filesystem. Returns JSON with the created path. Supports prefix and suffix for naming control. Use for safe temporary workspace creation in agent workflows. Not for persistent directories — use 'mkdir'. See also 'mkdir'.

Inputs: prefix, suffix, tmpdir, dry_run, +1 more.

mvA
Destructive

Move or rename files and directories with dry-run and overwrite protection. Destructive: relocates files on the filesystem (or renames them). Overwrite protection enabled by default — use --allow_overwrite to replace existing targets. Use --dry_run to preview. Returns JSON with source and destination paths. Use to relocate or rename files. Not for creating copies — use 'cp' to duplicate. Not for creating links — use 'ln'. See also 'cp', 'ln'.

Inputs: source (required), destination (required), dry_run, parents, +1 more.

niceA
Destructive

Run a command with adjusted CPU scheduling priority (niceness). Executes the given command as a subprocess, captures bounded stdout/stderr, and enforces a safety timeout. Use --dry_run to preview without execution. Positive niceness lowers priority for background tasks; negative values may require elevated privileges. Use to reduce CPU impact of background work. Not for I/O buffering control — use 'stdbuf'. Not for hangup immunity — use 'nohup'. Not for time-bound execution — use 'timeout'. See also 'stdbuf', 'nohup', 'timeout'.

Inputs: dry_run, timeout, adjustment, command_args, +1 more.

nlA
Read-only

Number input lines with configurable formatting (alignment, delimiter, starting number). Read-only, no side effects. Returns JSON with numbered lines by default; use --raw for plain text. Use to add line numbers for reference or debugging. Not for simple concatenation — use 'cat'. See also 'cat'.

Inputs: raw, paths, start, width, +8 more.

nohupA
Destructive

Run a command immune to SIGHUP (hangup signals), ideal for long-running background tasks. Executes the given command and captures stdout/stderr. Requires --allow_nohup confirmation for safety. Use to run tasks that should survive terminal closure. Not for CPU priority adjustment — use 'nice'. Not for time-bounded execution — use 'timeout'. See also 'nice', 'timeout'.

Inputs: append, output, dry_run, parents, +3 more.

nprocA
Read-only

Return the number of available CPU processing units. Read-only, no side effects. Returns JSON with the core count; use --raw for plain integer. Use to make parallelism decisions in agent workflows. Not for system runtime info — use 'uptime'. Not for architecture info — use 'arch' or 'uname'. See also 'uptime', 'arch'.

Inputs: raw.

numfmtA
Read-only

Convert numbers between plain, SI (K, M, G), and IEC binary (Ki, Mi, Gi) unit systems. Read-only, no side effects. Parses human-readable strings with SI/IEC suffixes back to raw numbers. Returns JSON with the converted value by default; use --raw for plain output. Use to humanize byte counts or parse user-supplied size strings. Not for formatted string output — use 'printf' for general formatting. See also 'printf'.

Inputs: raw, numbers, to_unit, encoding, +6 more.

odA
Read-only

Dump input bytes as structured rows in hexadecimal, octal, or decimal format. Read-only, no side effects. Returns JSON with formatted dump by default; use --raw for traditional octal display. Use to inspect raw binary content. Not for plain text viewing — use 'cat'. See also 'cat'.

Inputs: raw, paths, format, offset, +6 more.

pasteA
Read-only

Merge corresponding lines from multiple files side by side, separated by a configurable delimiter (default tab). Read-only, no side effects. Returns JSON with merged lines by default; use --raw for plain output. Use to combine columns from separate files into a table. Not for key-based joining — use 'join' for field-matched merging. Not for simple concatenation — use 'cat'. See also 'join', 'cat'.

Inputs: raw, paths, encoding, delimiter, +4 more.

pathchkA
Read-only

Validate path name components for portability (length, character set, existence). Read-only, no side effects. Returns JSON with validation result. Use to verify paths before creating or using them. Not for path resolution — use 'realpath' to resolve to absolute canonical form. See also 'realpath'.

Inputs: paths (required), raw, portable, exit_code, +2 more.

pinkyA
Read-only

Print detailed user account information: login name, home directory, shell, and idle time. Read-only, no side effects. Returns JSON with user profile data. Use to inspect specific user account properties. Not for current user identity — use 'whoami' or 'id'. Not for session listing — use 'who' for active sessions. See also 'who', 'id'.

Inputs: raw, long, users.

prA
Read-only

Paginate text into deterministic pages with configurable headers, footers, and page dimensions. Read-only, no side effects. Returns JSON with paginated output by default; use --raw for plain text. Use for print-ready formatted output. Not for paragraph reflowing — use 'fmt'. Not for line wrapping — use 'fold'. See also 'fmt', 'fold'.

Inputs: raw, paths, width, header, +6 more.

printenvA
Read-only

Return the value of a specific environment variable by name, or all variables if no name given. Read-only, no side effects. Returns JSON with the variable value. Use for direct lookup of known variable names. Not for listing all variables with filtering — use 'env' for pattern-based filtering. See also 'env'.

Inputs: raw, names.

printfA
Read-only

Format and print text using printf-style conversion specifiers (%s, %d, %f, etc.). Read-only, no side effects. Returns JSON with the formatted string by default; use --raw for plain output. Use for precise control over number formatting, padding, and type conversion. Not for simple echo without formatting — use 'echo'. See also 'echo'.

Inputs: format_string (required), raw, values, encoding, +3 more.

ptxA
Read-only

Build a permuted (keyword-in-context) index from input text, showing each word in its surrounding context. Read-only, no side effects. Returns JSON with the index by default; use --raw for plain output. Use to create searchable cross-reference indices. Not for sorting or deduplication — use 'sort' and 'uniq'. See also 'sort'.

Inputs: raw, only, paths, ignore, +7 more.

pwdA
Read-only

Print the current working directory as JSON. Read-only, no side effects. Returns JSON with the absolute directory path. Use to determine the active directory context before file operations. Not for path resolution — use 'realpath' to resolve symlinks and relative paths. See also 'ls', 'realpath'.

Inputs: no named parameters.

realpathA
Read-only

Resolve file paths to their absolute canonical form, following all symlinks and resolving all relative components. Read-only, no side effects. Fails with a clear error if the target does not exist (use --no-symlinks to relax existence check). Returns JSON with the resolved absolute path. Use to normalize paths for comparison or before file operations. Not for reading symlink targets without full resolution — use 'readlink'. See also 'readlink'.

Inputs: paths (required), strict.

rmA
Destructive

Remove files or recursively delete directories with dry-run and safety protections. Destructive and irreversible: deleted data cannot be recovered. Use --dry_run to preview which files would be removed. Recursive directory removal requires --recursive. Sandbox checks prevent deletion outside the current working directory without explicit --allow_outside_cwd. Returns JSON with removed paths. Use to delete files and directories. Not for secure deletion — use 'shred' to overwrite before removal. Not for removing only empty directories — use 'rmdir'. See also 'rmdir', 'shred', 'unlink'.

Inputs: paths (required), force, dry_run, recursive, +1 more.

rmdirA
Destructive

Remove empty directories with dry-run support. Destructive: deletes directories. Fails safely on non-empty directories (use 'rm --recursive' for those). Use --dry_run to preview. Returns JSON with the removed directory paths. Use to clean up empty directory trees. Not for removing directories with contents — use 'rm --recursive'. Not for file removal — use 'unlink' or 'rm'. See also 'rm', 'unlink'.

Inputs: paths (required), dry_run.

runconA
Destructive

Plan or run a command under a specified SELinux security context. Potentially destructive: changes the security domain of the executed command. Use --dry_run to preview. Requires --allow_context confirmation. Use to test or enforce SELinux context transitions. Not for modifying file contexts — use 'chcon' for file labels. See also 'chcon'.

Inputs: context (required), dry_run, timeout, command_args, +2 more.

schemaA
Read-only

Return the full aicoreutils JSON protocol specification: envelope structure, exit codes (0-10), output conventions, and command metadata. Read-only, no side effects. Use before invoking other tools to understand the response format and error semantics. Not for tool discovery — use 'tool-list' or 'catalog'. See also 'tool-list', 'catalog'.

Inputs: no named parameters.

seqA
Read-only

Print a sequence of numbers as JSON with configurable start, increment, and end values. Read-only, no side effects. Returns JSON with the number sequence array. Use to generate numeric sequences or ranges. Not for repeating a constant string — use 'yes' for fixed repetition. See also 'yes', 'printf'.

Inputs: numbers (required), raw, format, encoding, +6 more.

sha1sumA
Read-only

Compute SHA-1 hash digests of files or stdin. Read-only, no side effects. Returns JSON with per-file hash values. Use for basic integrity verification compatible with legacy systems. Not for security-critical applications — SHA-1 is cryptographically broken; use 'sha256sum' or 'b2sum'. See also 'sha256sum', 'hash'.

Inputs: check, paths, encoding, show_encoding, +2 more.

sha224sumA
Read-only

Compute SHA-224 hash digests of files or stdin. Read-only, no side effects. Returns JSON with per-file hash values. Use for cryptographic integrity verification with smaller digest size. Not for maximum security margin — use 'sha512sum' for highest strength. See also 'sha256sum', 'hash'.

Inputs: check, paths, encoding, show_encoding, +2 more.

sha256sumA
Read-only

Compute SHA-256 hash digests of files or stdin — the standard cryptographic hash. Read-only, no side effects. Returns JSON with per-file hash values. Use for cryptographic integrity verification and content addressing. This is the recommended default for security-sensitive hashing. Not for high-speed non-security use — use 'md5sum' or 'b2sum' for speed. See also 'sha512sum', 'hash', 'md5sum'.

Inputs: check, paths, encoding, show_encoding, +2 more.

sha384sumA
Read-only

Compute SHA-384 hash digests of files or stdin. Read-only, no side effects. Returns JSON with per-file hash values. Use for cryptographic integrity verification with higher security margin than SHA-256 (192-bit collision resistance). See also 'sha256sum', 'sha512sum', 'hash'.

Inputs: check, paths, encoding, show_encoding, +2 more.

sha512sumA
Read-only

Compute SHA-512 hash digests of files or stdin — the highest-strength SHA-2 variant. Read-only, no side effects. Returns JSON with per-file hash values. Use for maximum cryptographic security margin (256-bit collision resistance). Not for performance-sensitive use on 32-bit systems — use 'sha256sum'. See also 'sha256sum', 'hash'.

Inputs: check, paths, encoding, show_encoding, +2 more.

shredA
Destructive

Overwrite file contents multiple times with random data then optionally remove. Destructive and irreversible: shredded data is unrecoverable. Requires explicit --allow_destructive confirmation. Use --dry_run to preview. Use to securely erase sensitive files beyond forensic recovery. Not for simple deletion — use 'rm' for non-sensitive files. See also 'rm'.

Inputs: paths (required), passes, remove, dry_run, +1 more.

shufA
Read-only

Randomly permute input lines with optional deterministic seeding for reproducibility. Read-only, no side effects. Returns JSON with shuffled lines by default; use --raw for plain output. Set --seed for reproducible ordering. Use to randomize line order. Not for sorting — use 'sort' for ordered output. Not for deduplication — use 'uniq'. See also 'sort', 'uniq'.

Inputs: raw, seed, count, paths, +5 more.

sleepA
Destructive

Pause execution for a specified number of seconds, bounded by an upper safety limit. Blocks the calling process. Use --dry_run to preview the duration without actually sleeping. Use to introduce delays between operations. Not for time-bounded command execution — use 'timeout' to run a command with a deadline. See also 'timeout'.

Inputs: seconds (required), dry_run, max_seconds.

sortA
Read-only

Sort text lines deterministically from files or stdin. Read-only, no side effects. Use --numeric for numerical sort, --reverse for descending order, --unique to remove duplicates, and --seed for deterministic tie-breaking. Returns JSON with sorted lines by default; use --raw for plain output. Use to order data for downstream processing. Not for deduplication of non-sorted data — pipe to 'uniq' for adjacent dedup. Not for randomizing — use 'shuf'. See also 'uniq', 'shuf'.

Inputs: raw, check, paths, stable, +9 more.

splitA
Destructive

Split input into chunked output files by line count or byte size with dry-run and overwrite protection. Destructive: creates multiple output files. Default splits at 1000 lines per chunk. Use --dry_run to preview. Returns JSON with output file list and record counts. Use to partition large datasets. Not for content-based splitting — use 'csplit' to split at regex match points. See also 'csplit'.

Inputs: path, bytes, lines, prefix, +5 more.

statA
Read-only

Return detailed file metadata: size, permissions, owner, timestamps (access, modification, change, birth), inode, and device as structured JSON. Read-only, no side effects. Use to inspect file attributes without reading file contents. Not for directory listing — use 'ls' for multi-file listings. See also 'ls', 'du'.

Inputs: paths (required).

stdbufA
Destructive

Run a command with controlled stdout/stderr/stdin buffering: 0=none (unbuffered), L=line-buffered, or a byte size. Executes as a subprocess, captures bounded stdout/stderr, and enforces a safety timeout. Use --dry_run to preview without execution. Defaults to system buffering when no mode is set. Use to diagnose buffering-related output delays or ordering issues in pipelines. Not for CPU priority control — use 'nice'. Not for time-bounded execution — use 'timeout'. See also 'nice', 'timeout'.

Inputs: error, input, output, dry_run, +3 more.

sttyA
Destructive

Inspect or modify terminal device settings (baud rate, line discipline, control characters). Can change terminal behavior if --allow_change is enabled; defaults to read-only inspection. Returns JSON with terminal configuration. Use to query terminal state before operations that depend on it. Not for simple TTY detection — use 'tty' to check if stdin is a terminal. See also 'tty'.

Inputs: raw, device, dry_run, settings, +1 more.

sumA
Read-only

Compute legacy BSD-style 16-bit checksums and block counts for files or stdin. Read-only, no side effects. Returns JSON with checksum and block count. Use for compatibility with legacy BSD systems. Not for data integrity — CRC32 ('cksum') and cryptographic hashes ('sha256sum') are far more reliable. See also 'cksum', 'sha256sum'.

Inputs: raw, paths, encoding, block_size, +3 more.

syncA
Destructive

Flush cached filesystem writes to persistent storage where supported. Read-only in interface but causes I/O: forces dirty buffers to disk. Returns JSON with sync status. Use to ensure data durability before critical operations like system shutdown. Not for general use before every file operation — most commands flush on close. See also 'dd'.

Inputs: dry_run.

tacA
Read-only

Reverse the order of input lines (last line first). Read-only, no side effects. Returns JSON with reversed lines by default; use --raw for plain output. Use to invert line order for LIFO processing. Not for sorting — use 'sort --reverse' for reverse-sorted order. See also 'sort', 'cat'.

Inputs: raw, paths, encoding, max_lines, +3 more.

tailA
Read-only

Return the last N lines (default 10) of files or stdin as JSON. Read-only, no side effects. Returns JSON with line array by default; use --raw for plain text. Supports negative-N to skip the first N lines. Use to view recent file additions or check log tails. Not for viewing file beginnings — use 'head'. See also 'head', 'cat'.

Inputs: path (required), raw, lines, encoding, +3 more.

teeA
Destructive

Read stdin and write simultaneously to files and stdout with dry-run and append support. Destructive: writes to specified output files. Use --dry_run to preview. Use --append to add to files instead of overwriting. Returns JSON with output paths and byte counts. Use to capture intermediate pipeline data while passing it through. Not for simple file writing without passthrough — use redirection or 'cp'. For secure overwriting use 'shred'. See also 'cat', 'echo'.

Inputs: raw, paths, append, dry_run, +2 more.

testA
Read-only

Evaluate file predicates (exists, is_file, is_dir, is_executable, is_symlink, is_readable, is_writable) and return structured JSON with the boolean result. Read-only, no side effects. Returns JSON indicating test result and exit code (0 for true, 1 for false). Use for conditional branching based on file properties in scripts. Not for detailed file inspection — use 'stat' for full metadata. See also 'stat', '['.

Inputs: path (required), file, empty, exists, +7 more.

timeoutA
Destructive

Run a command with a bounded time limit, automatically terminating it if it exceeds the duration. Captures stdout/stderr up to max_output_bytes. Returns JSON with command output and whether it timed out. Use to prevent runaway commands from blocking agent workflows. Not for introducing delays — use 'sleep' to pause. Not for CPU priority — use 'nice'. See also 'sleep', 'nice'.

Inputs: seconds (required), dry_run, command_args, max_output_bytes.

tool-listA
Read-only

Return a compact tool index optimized for LLM function-calling context windows. Read-only, no side effects. Returns JSON with tool names, descriptions, and parameter schemas by default. Use --format=openai for OpenAI-compatible function definitions, --format=anthropic for Anthropic tool format. Use before agent planning to discover available capabilities. Not for human browsing — use 'catalog' for category-organized listing. See also 'catalog', 'coreutils'.

Inputs: raw, format, include_risk.

touchA
Destructive

Update file access and modification timestamps to the current time, or create empty files if they do not exist. Modifies filesystem metadata (timestamps), creates files when path does not exist. Returns JSON with the touched path. Use to refresh timestamps or ensure a file exists. Not for creating directories — use 'mkdir'. Not for changing file size — use 'truncate'. See also 'mkdir', 'truncate'.

Inputs: paths (required), dry_run, parents.

trA
Read-only

Translate or delete literal characters from files or stdin — character-by-character replacement (NO regex). Read-only, no side effects (reads input, writes to stdout). Use --delete to remove specific characters, --squeeze to collapse repeats. Returns JSON by default; use --raw for plain output. Use for simple character mapping. Not for regex-based substitution — use 'sed' externally. Not for column extraction — use 'cut'. See also 'cut', 'expand'.

Inputs: set1 (required), raw, set2, input, +8 more.

trueA
Read-only

Exit with status 0 (success). Idempotent: always succeeds, takes no arguments, has zero side effects. Returns JSON success envelope. Use to signal successful completion or as a placeholder in scripts. Not for failure signaling — use 'false'. See also 'false'.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 100 tools

    Disambiguation4/5

    Tools are mostly distinct with clear descriptions, but there is slight overlap among hash tools (b2sum, sha256sum, hash) and file listing tools (ls, dir, vdir) that could cause minor confusion. Overall, each tool has a unique primary purpose.

    Naming Consistency3/5

    Most tools follow a single lowercase word naming convention (e.g., cat, sort, mkdir), but there are deviations like 'tool-list' and 'b2sum' that break the pattern. The verb_noun convention is absent, but the naming is predictable within the context of a coreutils clone.

    Tool Count1/5

    With 100 tools, the server is extremely over-scoped for an MCP server. Even though coreutils itself has many commands, exposing all of them as individual MCP tools creates an unwieldy surface that overwhelms agents and is far beyond the typical 3-15 tool range.

    Completeness5/5

    The tool surface is remarkably comprehensive for a coreutils server, covering file operations, text processing, system info, hashing, and process control. There are no obvious gaps given the domain; even standard commands like 'yes' and 'whoami' are missing but not critical. The set provides complete coverage for common CLI tasks.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A config-driven, zero-dependency MCP server with plugin architecture that enables filesystem operations, shell commands, HTTP requests, and utilities through simple JSON configuration.
      3
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Provides MCP servers that wrap common developer tools (git, npm, docker, etc.) returning structured JSON output, enabling AI agents to reliably interact with these tools without parsing fragile terminal text.
      141
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Universal MCP server that wraps any CLI tool, enabling AI assistants to run commands via natural language.
      1
      MIT