From 8af4956951703a50c91d71d1aada2ebcb30bb84c Mon Sep 17 00:00:00 2001
From: Hein <hein.puth@gmail.com>
Date: Sun, 5 Apr 2026 11:45:07 +0200
Subject: [PATCH] docs(cli): add CLI client details and configuration
 instructions

---
 README.md     | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 llm/memory.md |  6 ++++++
 2 files changed, 53 insertions(+)

diff --git a/README.md b/README.md
index 50a66ae..3b256f4 100644
--- a/README.md
+++ b/README.md
@@ -525,6 +525,53 @@ Recommended Apache settings:
 - `ProxyTimeout 600` and `ProxyPass ... timeout=600` give Apache enough time to wait for the Go backend.
 - If another proxy or load balancer sits in front of Apache, align its size and timeout settings too.
 
+## CLI
+
+`amcs-cli` is a pre-built CLI client for the AMCS MCP server. Download it from https://git.warky.dev/wdevs/amcs/releases
+
+The primary purpose is to give agents and MCP clients a ready-made bridge to the AMCS server so they do not need to implement their own HTTP MCP client. Configure it once and any stdio-based MCP client can use AMCS immediately.
+
+### Commands
+
+| Command | Purpose |
+|---|---|
+| `amcs-cli tools` | List all tools available on the remote server |
+| `amcs-cli call <tool>` | Call a tool by name with `--arg key=value` flags |
+| `amcs-cli stdio` | Start a stdio MCP bridge backed by the remote server |
+
+`stdio` is the main integration point. It connects to the remote HTTP MCP server, discovers all its tools, and re-exposes them over stdio. Register it as a stdio MCP server in your agent config and it proxies every tool call through to AMCS.
+
+### Configuration
+
+Config file: `~/.config/amcs/config.yaml`
+
+```yaml
+server: https://your-amcs-server
+token: your-bearer-token
+```
+
+Env vars override the config file: `AMCS_URL`, `AMCS_TOKEN`. Flags `--server` and `--token` override env vars.
+
+### stdio MCP client setup
+
+#### Claude Code
+
+```bash
+claude mcp add --transport stdio amcs amcs-cli stdio
+```
+
+With inline credentials (no config file):
+
+```bash
+claude mcp add --transport stdio amcs amcs-cli stdio \
+  --env AMCS_URL=https://your-amcs-server \
+  --env AMCS_TOKEN=your-bearer-token
+```
+
+#### Output format
+
+`call` outputs JSON by default. Pass `--output yaml` for YAML.
+
 ## Development
 
 Run the SQL migrations against a local database with:
diff --git a/llm/memory.md b/llm/memory.md
index df4bda1..7af75e3 100644
--- a/llm/memory.md
+++ b/llm/memory.md
@@ -2,6 +2,12 @@
 
 AMCS (Avalon Memory Crystal Server) is an MCP server for capturing and retrieving thoughts, memory, and project context. It is backed by Postgres with pgvector for semantic search.
 
+`amcs-cli` is a pre-built CLI that connects to the AMCS MCP server so agents do not need to implement their own HTTP MCP client. Download it from https://git.warky.dev/wdevs/amcs/releases
+
+The key command is `amcs-cli stdio`, which bridges the remote HTTP MCP server to a local stdio MCP transport. Register it as a stdio MCP server in your agent config and all AMCS tools are available immediately without any custom client code.
+
+Configure with `~/.config/amcs/config.yaml` (`server`, `token`), env vars `AMCS_URL` / `AMCS_TOKEN`, or `--server` / `--token` flags.
+
 You have access to an MCP memory server named AMCS.
 
 Use AMCS as memory with two scopes: