ai-engineer

• Built-in Tools: read_file, grep, bash, think, todo, apply_patch, write_file
• MCP Integration: Connect to any MCP server for extended capabilities
• Conversation History: Persistent sessions across runs
• Flexible Configuration: YAML-based agent specifications
• Tool Calling: Automatic tool selection and execution
• ACP Support: Full Agent Client Protocol support for IDE integration (Zed, etc.)
• AGENTS.md Support: Auto-load project-specific rules from AGENTS.md files
• Smart Context Compaction: Intelligent context management with dynamic thresholds
• Multi-Agent System: Primary/Subagent architecture with built-in agent types (coder, explorer, planner)
• Event Bus: Publish/subscribe system for agent communication and extensibility
• Hooks System: Extensible hooks for tool validation, logging, and custom behaviors

Quick Run with uvx (no install needed)

```bash

# Initialize config first (API keys, model settings)

uvx amcp-agent init

# Run the agent

uvx amcp-agent

# Run as ACP server (for IDE integration)

uvx amcp-agent acp serve

```

From PyPI

```bash

# Install from PyPI

pip install amcp-agent

# Or with uv (requires virtual environment or --system flag)

uv pip install amcp-agent # in a virtual environment

uv pip install --system amcp-agent # global install without venv

# With Anthropic Claude support

pip install amcp-agent[anthropic]

```

From Source (development)

```bash

# Clone the repository

git clone https://github.com/tao12345666333/amcp.git

cd amcp

# using uv (recommended)

uv venv && source .venv/bin/activate

uv pip install -e .

# or with pip

python -m venv .venv && source .venv/bin/activate

pip install -e .

```

```bash

# Initialize config

amcp init

# Agent with tool calling (default command)

amcp # interactive mode with conversation history

amcp --once "create a hello.py file with a hello function" # single message

amcp --list # list available agent specifications

amcp --agent path/to/agent.yaml # use custom agent spec

amcp --session my-session # use specific session ID

amcp --clear # clear conversation history

# MCP server management

amcp mcp tools --server exa

amcp mcp call --server exa --tool web_search_exa --args '{"query":"rust async"}'

# Run as ACP agent (for IDE integration)

amcp acp serve

```

AMCP fully supports the [Agent Client Protocol](https://agentclientprotocol.com/) for integration with IDEs like Zed.

Features

• Session Management: Create, load, and list sessions
• Session Modes: Switch between ask, architect, and code modes

- ask: Request permission before making changes

- architect: Design and plan without implementation

- code: Full tool access for implementation

• Slash Commands: /clear, /plan, /search, /help
• Agent Plans: Visual execution plans for complex tasks
• Permission Requests: User approval for sensitive operations
• Client Capabilities: Use client's filesystem and terminal when available

Running as ACP Agent

```bash

# Start the ACP agent server (stdio transport)

amcp acp serve

```

Zed Integration

Add to your Zed settings (~/.config/zed/settings.json):

```json

{

"agent": {

"profiles": {

"amcp": {

"name": "AMCP",

"provider": {

"type": "acp",

"command": "amcp",

"args": ["acp", "serve"]

}

}

},

"default_profile": "amcp"

}

}

```

• read_file: Read text files with two modes:

- Slice mode (default): Read specific line ranges

- Indentation mode: Intelligently read code blocks around an anchor line, automatically capturing surrounding context (functions, classes)

• grep: Search for patterns in files using ripgrep
• bash: Execute bash commands for file operations and system tasks
• think: Internal reasoning and planning
• todo: Manage a todo list to track tasks during complex operations
• apply_patch: Apply diff-based patches to files (recommended for edits, see [docs/apply-patch.md](docs/apply-patch.md))
• write_file: Write content to files (for creating new small files)
• task: Spawn sub-agents for parallel task execution

The CLI loads MCP servers from ~/.config/amcp/config.toml.

Generate a starter config:

```bash

amcp init

```

Example (OpenAI-compatible API):

```toml

[servers.exa]

url = "https://mcp.exa.ai/mcp"

[servers.custom]

command = "npx"

args = ["-y", "@some/mcp-server"]

env.API_KEY = "your-key"

[chat]

api_type = "openai" # "openai" (default) or "anthropic"

base_url = "https://api.openai.com/v1"

model = "gpt-4o"

api_key = "your-api-key"

mcp_tools_enabled = true

write_tool_enabled = true # Enable/disable built-in write_file tool

```

Example (OpenAI Responses API):

```toml

[chat]

api_type = "openai_responses"

model = "gpt-4o"

api_key = "your-api-key"

```

Example (Anthropic Claude):

```toml

[chat]

api_type = "anthropic"

model = "claude-sonnet-4-20250514"

api_key = "your-anthropic-api-key" # or set ANTHROPIC_API_KEY env var

```

To use Anthropic, install with: pip install amcp-agent[anthropic]

AMCP provides a flexible hooks system to extend and customize agent behavior. Hooks can:

• Validate and modify tool inputs before execution
• Process tool outputs after execution
• Block dangerous operations
• Log and audit agent activities

Quick Example

Create .amcp/hooks.toml in your project:

```toml

[hooks.PreToolUse]

[[hooks.PreToolUse.handlers]]

matcher = "write_file|apply_patch"

type = "python"

script = "./scripts/validate-writes.py"

timeout = 30

[[hooks.PostToolUse.handlers]]

matcher = "*"

type = "command"

command = "echo 'Tool executed' >> /tmp/tool_log.txt"

```

See [docs/hooks.md](docs/hooks.md) for full documentation.

Setup Development Environment

```bash

# Clone the repository

git clone https://github.com/tao12345666333/amcp.git

cd AMCP

# Install with development dependencies

pip install -e ".[dev]"

# Install pre-commit hooks

pre-commit install

```

Running Tests

```bash

# Run all tests

make test

# Run with coverage

make test-cov

# Run specific test

pytest tests/test_tools.py -v

```

Code Quality

```bash

# Lint code

make lint

# Format code

make format

# Type check

make type-check

```

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.

• rg (ripgrep) must be installed and on PATH for the grep tool.
• MCP servers must be installed separately and runnable (stdio transport).

Apache-2.0