feat(cli): add secure login and tool listing

.github/workflows/ci.yml

@@ -8,6 +8,20 @@ on:
   workflow_dispatch:
 
 jobs:
+  cli:
+    name: CLI (test, build)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm test -w packages/cli
+      - run: npm run build -w packages/cli
+      - run: test ! -e packages/cli/dist/cli.test.js
+
   backend:
     name: Backend (lint, typecheck, test, build)
     runs-on: ubuntu-latest

Dockerfile

@@ -26,6 +26,7 @@ WORKDIR /app
 COPY package.json package-lock.json ./
 COPY packages/backend/package.json ./packages/backend/
 COPY packages/frontend/package.json ./packages/frontend/
+COPY packages/cli/package.json ./packages/cli/
 
 # Install all workspace dependencies
 # Extended timeout for ARM64 QEMU emulation in CI
@@ -44,6 +45,10 @@ COPY packages/backend/package.json ./packages/backend/
 RUN mkdir -p packages/frontend && \
     echo '{"name":"@anythingmcp/frontend","version":"0.1.1","private":true}' > packages/frontend/package.json
 
+# The CLI is a workspace but does not ship in the server image.
+RUN mkdir -p packages/cli && \
+    echo '{"name":"@anythingmcp/cli","version":"0.1.0","private":true}' > packages/cli/package.json
+
 RUN npm install --omit=dev --network-timeout=600000 && \
     rm -rf node_modules/typescript node_modules/react-dom node_modules/react
 

docs/api-reference.md

@@ -324,6 +324,21 @@ with that server's tools. Other servers answer `403`. The server must be one of
 an organization you belong to, and deleting it deactivates its keys. A key
 created without `mcpServerId` reaches every server of your organization.
 
+### CLI
+
+The repository includes the [`amcp` CLI](../packages/cli/README.md) for logging
+in with an MCP API key and listing tools on a specific server. Build it with
+`npm run build -w packages/cli`, then run:
+
+```bash
+node packages/cli/dist/index.js login --url http://localhost:4000 --server YOUR_SERVER_ID
+node packages/cli/dist/index.js tools ls
+```
+
+The CLI constructs `/mcp/<serverId>` from the instance URL and server ID.
+The `/api/*` endpoints in this reference use a JWT, while the CLI connects to
+MCP with an MCP API key.
+
 ---
 
 ## Site Settings (Admin)

package.json

@@ -9,7 +9,8 @@
   },
   "workspaces": [
     "packages/backend",
-    "packages/frontend"
+    "packages/frontend",
+    "packages/cli"
   ],
   "scripts": {
     "dev": "concurrently \"npm run dev:backend\" \"npm run dev:frontend\"",

packages/cli/README.md

@@ -0,0 +1,43 @@
+# AnythingMCP CLI
+
+The `amcp` command connects to one AnythingMCP MCP server from your terminal.
+This first version supports login, logout, profile inspection and tool listing.
+
+From the repository root:
+
+```bash
+npm install
+npm run build -w packages/cli
+node packages/cli/dist/index.js login --url http://localhost:4000 --server YOUR_SERVER_ID
+node packages/cli/dist/index.js tools ls
+```
+
+`login` prompts for an MCP API key without displaying it. For scripts, use
+`--key-stdin` or the `AMCP_API_KEY` environment variable. Never put the key in
+a command argument. The CLI verifies the key by requesting `tools/list` before
+saving it. It always connects to `/mcp/<serverId>`, including on Cloud, because
+the bare `/mcp` endpoint exposes a different tool set there. Pass the instance
+base URL to `--url`, without `/mcp/<serverId>`. HTTPS is required except for
+`localhost`, `127.0.0.0/8`, and `::1` during local development. Redirects are
+refused so the API key cannot follow a request to another origin.
+
+```bash
+printf '%s\n' "$AMCP_API_KEY" | amcp login --url https://cloud.anythingmcp.com \
+  --server YOUR_SERVER_ID --key-stdin --profile cloud
+amcp tools ls --profile cloud --filter customer
+amcp whoami --profile cloud
+amcp logout --profile cloud
+```
+
+For CI, `AMCP_URL`, `AMCP_SERVER` and `AMCP_API_KEY` can provide connection
+details without saving a profile. `--url` and `--server` take precedence over
+their matching environment variables. If a URL is supplied by `--url` or
+`AMCP_URL`, supply `AMCP_API_KEY` too; a saved profile key is used only with its
+saved origin. Profiles live in
+`$XDG_CONFIG_HOME/amcp/config.json` or `~/.config/amcp/config.json`, with file
+mode `0600` on Unix. Relative `XDG_CONFIG_HOME` values are ignored. `whoami`
+shows only a key prefix.
+
+`tools ls` shows each tool's name, read-only/destructive hint, and the first
+line of its description. Tool execution and JSON output are planned for the
+next phase of [issue #1009](https://github.com/HelpCode-ai/anythingmcp/issues/1009).

packages/cli/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@anythingmcp/cli",
+  "version": "0.1.0",
+  "private": true,
+  "description": "AnythingMCP command-line client",
+  "license": "AGPL-3.0-only",
+  "bin": { "amcp": "dist/index.js" },
+  "engines": { "node": ">=22.12" },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "test": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node --test dist/cli.test.js"
+  },
+  "dependencies": { "@modelcontextprotocol/client": "^2.2.0" },
+  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.9.0" }
+}