# Core Agent MCP

**Remote execution layer for agentic systems.** Expose 64 stable tools via [Model Context Protocol](https://modelcontextprotocol.io/) — Hermes, OpenClaw, Claude Code, atau MCP client lain bisa pakai ini remote atau lokal.

## Kenapa?

Agentic systems butuh remote execution layer yang reliable — bukan cuma shell access, tapi tools terstruktur, typed, dan terdefinisi yang return hasil konsisten. `core-agent-mcp` solusinya:

- 🛠 **64 production tools** — file, network, system, text, git, crypto, monitoring
- 🔌 **Dual transport** — stdio (local) atau HTTP SSE (remote)
- 🎯 **Stable output** — setiap tool return `{success: bool, data: ..., error?: str}`
- 🧩 **Hermes-ready** — drop-in via `mcp_servers` config

## Quick Start

```bash
# Install
pip install core-agent-mcp

# Run stdio (local agent)
core-agent-mcp

# Run HTTP (remote agent)
core-agent-mcp --transport sse --host 0.0.0.0 --port 8931
```

## Integrasi Hermes

Tambah ke `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  core-agent:
    command: "core-agent-mcp"
    timeout: 120
```

Remote:

```yaml
mcp_servers:
  core-agent:
    url: "http://your-server:8931/mcp"
    timeout: 120
    connect_timeout: 30
```

`/reset` sesi Hermes — semua tool muncul sebagai `mcp_core_agent_*`.

## Integrasi OpenClaw / Claude Code

### Claude Code (`claude_code.json`)
```json
{
  "mcpServers": {
    "core-agent": { "command": "core-agent-mcp" }
  }
}
```

### OpenClaw
```yaml
mcp_servers:
  core-agent:
    command: "core-agent-mcp"
```

## Tools (64 tools)

### System (11)
| Tool | Description |
|------|-------------|
| `system_info` | OS, kernel, hostname, CPU, Python |
| `exec_command` | Execute shell command (timeout, cwd, env) |
| `get_env` | Get env var value |
| `list_env` | List env vars (keys atau key=value) |
| `which` | Locate binary in PATH |
| `disk_usage` | Disk space per partition |
| `memory_info` | RAM + swap usage |
| `cpu_load` | Load avg + per-core usage |
| `uptime` | System uptime |
| `list_users` | User accounts (UID>=1000 + root) |
| `hostname` | System hostname |

### Filesystem (16)
| Tool | Description |
|------|-------------|
| `read_text` | Read file (line range, max 1MB) |
| `write_text` | Write/overwrite file (auto mkdir) |
| `append_text` | Append to file |
| `list_dir` | Dir listing with metadata |
| `file_info` | File/dir metadata detail |
| `find_files` | Find by glob pattern |
| `grep_files` | Search content via regex |
| `copy_path` | Copy file/dir (recursive) |
| `move_path` | Move/rename file/dir |
| `delete_path` | Delete file/dir (safe: need recursive flag) |
| `create_dir` | mkdir -p |
| `download_url` | Download URL to file |
| `checksum_file` | MD5/SHA1/SHA256/SHA512 |
| `tree` | Directory tree (depth-limited) |
| `tail_file` | Last N lines |
| `head_file` | First N lines |

### Network (7)
| Tool | Description |
|------|-------------|
| `http_request` | Full HTTP (GET/POST/PUT/DELETE/PATCH) |
| `dns_lookup` | DNS A/AAAA/MX/NS/TXT/CNAME |
| `tcp_check` | TCP port open check |
| `whois` | Domain WHOIS lookup |
| `ssl_cert` | SSL certificate details |
| `public_ip` | Detect public IP |
| `ping_host` | ICMP ping (count-based) |

### Text & Data (20)
| Tool | Description |
|------|-------------|
| `grep` | Regex search in text |
| `count` | Words/lines/chars/bytes |
| `diff` | Unified diff text A vs B |
| `json_parse` | Validate & parse JSON |
| `json_format` | Pretty-print JSON |
| `base64_encode` | Base64 encode |
| `base64_decode` | Base64 decode |
| `url_encode` | URL percent-encode |
| `url_decode` | URL percent-decode |
| `hash` | MD5/SHA1/SHA256/SHA512 |
| `uuid_v4` | Random UUID v4 |
| `uuid_v7` | Time-ordered UUID v7 |
| `timestamp` | ISO/Unix/RFC2822 now |
| `hex_encode` | Text to hex |
| `hex_decode` | Hex to text |
| `unixtime_to_iso` | Unix sec → ISO 8601 |
| `iso_to_unixtime` | ISO 8601 → Unix sec |
| `csv_parse` | CSV text → JSON array |
| `json_to_yaml` | JSON → YAML |
| `yaml_to_json` | YAML → JSON |

### Development (7)
| Tool | Description |
|------|-------------|
| `git_status` | Working tree status |
| `git_log` | Commit log (N entries, filter author) |
| `git_diff` | Diff unstaged/staged/refs |
| `git_branches` | List local branches |
| `git_commit_count` | Count commits (branch/all) |
| `git_show` | Commit detail + diffstat |
| `format_json` | Pretty-print JSON |

### Meta (2)
| Tool | Description |
|------|-------------|
| `ping` | Health check → pong + version |
| `help` | List all tools with descriptions |

## CLI

```
core-agent-mcp [OPTIONS]

Options:
  --transport TEXT    stdio (default) atau sse
  --host TEXT         HTTP host (default: 0.0.0.0)
  --port INTEGER      HTTP port (default: 8931)
  --timeout INTEGER   Tool timeout (default: 120s)
  --max-output INTEGER  Max output bytes (default: 51200)
  --workdir TEXT      Working directory
  --help
```

## Env Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CORE_AGENT_TIMEOUT` | 120 | Default tool timeout |
| `CORE_AGENT_MAX_OUTPUT` | 51200 | Max output bytes |
| `CORE_AGENT_WORKDIR` | $PWD | Working directory |
| `CORE_AGENT_PATH_ALLOWLIST` | - | Comma-separated allowed paths |

## Dev

```bash
git clone https://github.com/jefripunza/core-agent-mcp
cd core-agent-mcp
uv venv && source .venv/bin/activate
uv pip install -e .
core-agent-mcp

# Test via MCP inspector
npx @modelcontextprotocol/inspector core-agent-mcp
```

## License

MIT