AICoreUtils

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 →):

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

• Documentation Index

• Current Project Status ← Authoritative status source

• Agent Protocol and Examples

• Security Model

• Chinese/English User Guide

• GNU Coreutils Compatibility Audit

• Testing Instructions

• WSL Local CI

• Documentation Governance Rules

• Fact Propagation Matrix

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 →):

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

• Documentation index

• Current project status ← authoritative status source

• Agent protocol and examples

• Security model

• Chinese/English user guide

• GNU Coreutils compatibility audit

• Testing guide

• WSL local CI

• Documentation governance rules

• Fact propagation matrix

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.