remote-access-mcp 1.0.6 → 1.1.0

package/README.fa.md

@@ -1,11 +1,12 @@
 # remote-access-mcp
 
 [![npm version](https://img.shields.io/npm/v/remote-access-mcp.svg)](https://www.npmjs.com/package/remote-access-mcp)
+[![CI](https://github.com/AmirAliManzar/remote-access-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/AmirAliManzar/remote-access-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 هر سرور لینوکسی رو با MCP ([Model Context Protocol](https://modelcontextprotocol.io)) به ماشینی تبدیل کن که هوش مصنوعی بهش وصل بشه.
 
-ChatGPT (حالت Developer)، Claude، Grok و هر کلاینت MCP-دیگه از طریق HTTPS وصل میشن و به‌صورت امن سرورت رو کنترل می‌کنن: خواندن و نوشتن فایل، اجرای دستورات شل، وضعیت سیستم، دیتابیس SQLite و کار با گیت — همه پشت یک توکن.
+ChatGPT (حالت Developer)، Claude، Grok و هر کلاینت MCP-دیگه از طریق HTTPS وصل میشن و به‌صورت امن سرورت رو کنترل می‌کنن — همه پشت دسترسی‌های per-token.
 
 **بدون پایتون. بدون داکر. فقط Node.js.**
 
@@ -14,96 +15,54 @@ npm install -g remote-access-mcp
 ramcp init
 ```
 
-## فلسفه
-
-دستیارهای هوش مصنوعی قوی‌ان ولی از زیرساخت شما دورن. این گیت‌وی اون رو برعکس می‌کنه: چت‌بات شما خودش مهندس DevOps میشه. «ببین چرا دیسک سرور پر میشه» یا «برنچ جدید رو دیپلوی کن و لاگ‌ها رو نگاه کن» تبدیل به گفتگوهای واقعی میشن.
-
-سرور فقط روی `127.0.0.1` گوش میده. پشت nginx/Caddy (با Cloudflare یا هر لبه TLS دیگه) قرارش میدی و دقیقاً یک endpoint HTTPS به دنیا ارائه میشه. هر درخواست باید توکن داشته باشه — یا به‌صورت هدر `Authorization: Bearer` یا داخل مسیر URL (`/<token>/mcp`) برای کلاینت‌هایی مثل کانکتور ChatGPT که نمی‌تونن هدر سفارشی ست کنن.
-
 ## نصب
 
-### یک خطی (هر سرور اوبونتو/دبیان)
-
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AmirAliManzar/remote-access-mcp/main/install.sh | bash
-```
-
-سپس:
-
-```bash
 ramcp init
 ```
 
-### دستی
+## شروع سریع
 
 ```bash
-npm install -g remote-access-mcp
-ramcp init
+ramcp init                          # کانفیگ + اولین توکن
+ramcp policy allow /srv/myapp       # چه مسیرهایی رو AI ببینه
+ramcp policy shell on               # اجازه اجرای دستور (اختیاری)
+ramcp service install --domain mcp.example.com   # systemd + nginx
+ramcp doctor                        # بررسی سلامت همه‌چیز
+ramcp url                           # URL کانکتور برای چت‌بات
 ```
 
-## دستورات
-
-| دستور | توضیح |
-|---|---|
-| `ramcp init` | ساخت کانفیگ + توکن. اجرای مجدد امنه. |
-| `ramcp start` | اجرا در foreground. |
-| `ramcp url` | چاپ URL کانکتور برای چت‌بات. |
-| `ramcp token rotate` | تولید توکن جدید (قبلی فوراً باطل میشه). |
-| `ramcp policy` | نمایش مسیرهای مجاز. |
-| `ramcp policy allow <path>` | دادن دسترسی AI به یک دایرکتوری. |
-| `ramcp policy deny <path>` | سلب دسترسی از یک دایرکتوری. |
-| `ramcp policy shell on/off` | فعال/غیرفعال کردن اجرای شل. |
-| `ramcp service install` | نصب سرویس systemd + vhostnginx. |
-| `ramcp service uninstall` | حذف سرویس و کانفیگ nginx. |
-| `ramcp status` | وضعیت سرویس. |
-
-## اتصال چت‌بات
-
-### ChatGPT (Developer Mode → Connectors)
-
-از فرمت URL استفاده کن (ChatGPT نمی‌تونه هدر سفارشی ست کنه):
-
-```
-https://دامنه.com/<token>/mcp
-```
-
-آماده‌ش رو بگیر:
+## توکن‌های چندگانه — کمترین دسترسی به‌صورت پیش‌فرض
 
 ```bash
-$ ramcp url
-https://mcp.example.com/6kX9mQf2.../mcp
-```
-
-### Claude و هر کلاینت MCP با پشتیبانی هدر
-
-Endpoint: `https://دامنه.com/mcp`
-هدر: `Authorization: Bearer <token>`
+# توکن فقط-خواندنی برای ممیزی
+ramcp token add --name auditor --paths /srv --scopes filesystem --read-only
 
-## ابزارها
-
-**فایل‌سیستم** (۷) — `list_directory`, `read_file`, `write_file`, `edit_file`, `delete_path`, `search_code`, `file_info`
-
-**شل** (۳) — `run_command`, `process_list`, `kill_process`
-
-**سیستم** (۳) — `system_info`, `disk_usage`, `network_interfaces`
-
-**HTTP** (۲) — `http_request`, `port_check`
+# توکن دیپلوی: فایل + گیت + شل، با محدودیت نرخ و انقضا
+ramcp token add --name deploy --paths /srv/app --scopes filesystem,git,shell --shell --rpm 30 --expires 2026-12-31
+```
 
-**گیت** (۱) — `git`
+هر توکن خودش داره: مسیرهای مجاز/غیرمجاز، گروه ابزارها (scopes)، فلگ شل، حالت فقط-خواندنی، محدودیت نرخ، و تاریخ انقضا.
 
-**SQLite** (۲) — `sqlite_query`, `sqlite_schema`
+## ۳۸ ابزار در ۱۵ گروه
 
-**سیاست دسترسی** (۴) — `list_allowed_paths`, `allow_path`, `deny_path`, `shell_enabled`
+فایل‌سیستم (۷)، شل (۳)، سیستم (۳)، HTTP با محافظ SSRF (۳)، گیت با whitelist فعل‌ها (۱)، SQLite تک-دستوره (۲)، لاگ/journalctl (۳)، سرویس‌های systemd (۲)، پکیج‌ها apt/npm (۳)، زمان‌بند (۳)، اسکن امنیتی (۲)، تحلیل پروژه (۲)، پلنینگ + اسنپ‌شات/rollback (۴)، مدیریت پالیسی (۴).
 
 ## مدل امنیتی
 
-- **فقط loopback.** گیت‌وی روی `127.0.0.1:8765` گوش میده — از شبکه مستقیم قابل دسترسی نیست.
-- **احراز هویت توکنی روی هر درخواست.** دو فرمت: هدر bearer یا مسیر URL.
-- **موتور سیاست مسیر.** ابزارهای فایل‌سیستم symlinkها رو resolve و `..` رو قبل از چک allow/deny نرمال‌سازی می‌کنن. deny همیشه برنده‌ست.
-- **شل پشت فلگ.** تا صریحاً فعالش نکنی خاموشه.
-- **بدون لو رفتن رازها در لاگ‌ها.**
+- **فقط loopback** — سرور روی `127.0.0.1` گوش میده
+- **توکن timing-safe** روی هر درخواست — در لاگ‌ها فقط fingerprint ذخیره میشه
+- **Sandbox per-token** — resolve سیم‌لینک و `..` قبل از چک؛ deny همیشه برنده‌ست
+- **محدوده‌های SSRF بسته** — AI نمیتونه به metadata کلود یا سرویس‌های داخلی برسه
+- **ضد injection** — فعل‌های git whitelist، SQL تک-دستوره، ATTACH بسته
+- **لاگ audit ضد-دستکاری** — hash chain؛ `ramcp audit --verify` هر حذف/ویرایش رو لو میده؛ رازهای داخل آرگومان‌ها redact میشن
+- **Hot-reload** — تغییر پالیسی از درخواست بعدی اعمال میشه، بدون ریستارت
+- **کلید-کشِ حالت فقط-خواندن** — `ramcp policy readonly on` همه ابزارهای تغییردهنده رو قفل می‌کنه
+
+## دستورات کامل
 
-انتظار اینه که TLS جلوش باشه (nginx + Let's Encrypt یا لبه CDN). خود گیت‌وی HTTP ساده روی loopback حرف می‌زنه.
+`init` `start` `url` `doctor` `status` `token list|add|show|rotate|revoke` `policy [token] allow|deny|shell|readonly` `audit [--verify]` `service install|uninstall|logs|status` `schedule list` — جزئیات: [README انگلیسی](README.md)
 
 ## مجوز
 

package/README.md

@@ -1,11 +1,12 @@
 # remote-access-mcp
 
 [![npm version](https://img.shields.io/npm/v/remote-access-mcp.svg)](https://www.npmjs.com/package/remote-access-mcp)
+[![CI](https://github.com/AmirAliManzar/remote-access-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/AmirAliManzar/remote-access-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 Turn any Linux server into an AI-agent-accessible machine via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP).
 
-ChatGPT (Developer Mode), Claude, Grok, and any MCP-compatible client connect over HTTPS and securely control your server: read/write files, run shell commands, inspect system state, query SQLite databases, work with git — all behind a single bearer token.
+ChatGPT (Developer Mode), Claude, Grok, and any MCP-compatible client connect over HTTPS and securely control your server: read/write files, run shell commands, manage services, query databases, audit everything — all behind per-token permissions.
 
 **Zero Python. Zero Docker. Just Node.js.**
 
@@ -16,9 +17,9 @@ ramcp init
 
 ## Why
 
-AI assistants are great, but they're sandboxed away from your infrastructure. This gateway flips that: your chatbot *becomes* the ops engineer. "Check why the disk is filling up on the server" or "deploy the new branch and tail the logs" become actual conversations.
+AI assistants are great, but they're sandboxed away from your infrastructure. This gateway flips that: your chatbot *becomes* the ops engineer. "Check why the disk is filling up, fix it, and show me the logs" becomes an actual conversation.
 
-The server binds to `127.0.0.1` only. You put it behind nginx/Caddy (with Cloudflare or any TLS edge in front) and expose exactly one HTTPS endpoint to the world. Every request must carry your token — either as `Authorization: Bearer <token>` header or embedded in the URL path (`/<token>/mcp`) for clients like ChatGPT's custom connectors that can't set custom headers.
+The server binds to `127.0.0.1` only. You put it behind nginx (with Cloudflare or any TLS edge in front) and expose exactly one HTTPS endpoint to the world. Every request carries a token — as an `Authorization: Bearer` header or embedded in the URL path (`/<token>/mcp`) for clients like ChatGPT's connectors that can't set custom headers.
 
 ## Install
 
@@ -26,11 +27,6 @@ The server binds to `127.0.0.1` only. You put it behind nginx/Caddy (with Cloudf
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/AmirAliManzar/remote-access-mcp/main/install.sh | bash
-```
-
-Installs Node.js (if missing) via NodeSource, then the package globally. Then run:
-
-```bash
 ramcp init
 ```
 
@@ -44,100 +40,131 @@ ramcp init
 ## Quick start
 
 ```bash
-$ ramcp init
-
-  ___                        _____
- | _ \__ _ __ _ ___ _ _   |_   _|__ _ _ _ __ _ ___
- |   / _` / _` / -_) '_|    | |/ - \ '_| '_/ _` / -_)
- |_|_\__,_\__, \___|_|      |_|\___/_| |_| \__,_\___|
-          |___/         remote-access-mcp v1.0.0
-
-✔ Config written to /root/.config/remote-access-mcp/config.json
-✔ Token generated: 6kX9mQ... (stored in config, never shown again in full)
-✔ Test the server:  ramcp start --dry-run
-
-Next steps:
-  1. ramcp start                      # run in foreground
-  2. ramcp service install            # systemd unit + nginx vhost (recommended)
-  3. ramcp url                        # show the connector URL for your chatbot
+ramcp init                          # config + first token
+ramcp policy allow /srv/myapp       # what the AI may touch
+ramcp policy shell on               # let it run commands (optional)
+ramcp service install --domain mcp.example.com   # systemd + nginx
+ramcp doctor                        # verify everything end-to-end
+ramcp url                           # connector URL for your chatbot
 ```
 
 ## Commands
 
 | Command | Description |
 |---|---|
-| `ramcp init` | Generate config + token. Safe to re-run. |
-| `ramcp start` | Run the gateway in the foreground. |
-| `ramcp url` | Print the MCP endpoint URL for chatbot connectors. |
-| `ramcp token rotate` | Generate a new token (old one stops working immediately). |
-| `ramcp policy` | Show which paths the AI may access. |
-| `ramcp policy allow <path>` | Allow the AI access to a directory. |
-| `ramcp policy deny <path>` | Revoke access to a directory. |
-| `ramcp policy shell on/off` | Enable/disable shell command execution. |
-| `ramcp service install` | Install systemd service + nginx reverse-proxy vhost. |
-| `ramcp service uninstall` | Remove service + nginx vhost. |
-| `ramcp status` | Check if the service is running. |
+| `ramcp init` | Generate config + first token. Safe to re-run. |
+| `ramcp start [--read-only]` | Run in the foreground. |
+| `ramcp url [token]` | Connector URL for a chatbot. |
+| `ramcp doctor` | One-pass diagnosis: tokens, port, gateway, nginx, public URL, audit chain. |
+| `ramcp status` | Service + config summary. |
+| `ramcp token list [--json]` | All tokens (fingerprints only). |
+| `ramcp token add --name N` | Create a scoped token — see options below. |
+| `ramcp token rotate [name]` | Rotate a token (old one dies instantly). |
+| `ramcp token revoke name` | Delete a token. |
+| `ramcp policy [token]` | Show/set path policy, shell flag. |
+| `ramcp policy readonly on` | Global kill-switch for ALL mutating tools. |
+| `ramcp audit [--tool T]` | Query the audit log. `--verify` checks the hash chain. |
+| `ramcp service install` | systemd unit (+ nginx vhost with `--domain`). |
+| `ramcp service logs -f` | Tail gateway logs. |
+| `ramcp schedule list` | List scheduled tasks. |
+
+### `token add` options
+
+```bash
+ramcp token add --name chatgpt \
+  --paths /srv/app \        # allowed directories (symlink-safe)
+  --deny /srv/app/.env \    # explicitly denied (deny always wins)
+  --shell \                 # allow shell commands (default: off)
+  --scopes filesystem,git \ # limit to tool groups (default: all)
+  --read-only \             # refuse every mutating tool
+  --rpm 30 \                # max requests per minute
+  --expires 2026-12-31      # auto-expiry
+```
+
+Example — a token that can only read files, never write or execute:
+
+```bash
+ramcp token add --name auditor --paths /srv --scopes filesystem --read-only
+```
 
 ## Connecting your chatbot
 
 ### ChatGPT (Developer Mode → Connectors)
 
-Use the URL form (ChatGPT can't set custom headers):
-
 ```
 https://your-domain.com/<token>/mcp
 ```
 
-Get it ready-made:
-
-```bash
-$ ramcp url
-https://mcp.example.com/6kX9mQf2.../mcp
-```
+Get it ready-made: `ramcp url`
 
 ### Claude / any MCP client with header support
 
-Endpoint: `https://your-domain.com/mcp`
-Header: `Authorization: Bearer <token>`
+Endpoint `https://your-domain.com/mcp` + header `Authorization: Bearer <token>`
+
+## Tools (38 across 15 suites)
+
+**Filesystem** (7) `list_directory` `read_file` (offset/limit) `write_file` `edit_file` `delete_path` `search_code` `file_info`
+
+**Shell** (3) `run_command` (opt-in, timeout, output cap) `process_list` `kill_process` (refuses gateway/PID 1)
+
+**System** (3) `system_info` `disk_usage` `network_interfaces`
+
+**HTTP** (3) `http_request` `port_check` `web_fetch` — all SSRF-guarded: loopback, private ranges, and cloud metadata endpoints are refused
 
-## Tools exposed
+**Git** (1) `git` — verb-whitelisted; option injection (`--upload-pack`) and shell metacharacters blocked
 
-**Filesystem** (7) — `list_directory`, `read_file`, `write_file`, `edit_file`, `delete_path`, `search_code`, `file_info`
+**SQLite** (2) `sqlite_query` `sqlite_schema` — single-statement, ATTACH blocked
 
-**Shell** (3) — `run_command`, `process_list`, `kill_process`
+**Logs** (3) `tail_logs` `search_logs` `journal` (unit name validated)
 
-**System** (3) — `system_info`, `disk_usage`, `network_interfaces`
+**Services** (2) `service_status` `service_action` — protected units (ssh, gateway itself, targets) refused
 
-**HTTP** (2) — `http_request`, `port_check`
+**Packages** (3) `package_list` `package_install` `package_remove` (refuses nodejs/nginx/ssh)
 
-**Git** (1) — `git` (status, diff, log, add, commit, push, pull…)
+**Scheduler** (3) `schedule_command` `list_scheduled_tasks` `cancel_scheduled_task` — min 60s intervals, shell-token-gated
 
-**SQLite** (2) — `sqlite_query`, `sqlite_schema`
+**Security** (2) `secret_scan` (10 credential patterns, masked output) `port_scan_local`
 
-**Policy** (4) — `list_allowed_paths`, `allow_path`, `deny_path`, `shell_enabled`
+**Project** (2) `analyze_project` `project_health_check`
 
-Filesystem tools are sandboxed by an allow/deny policy (`ramcp policy`). By default nothing is allowed — you decide what the AI can touch. Shell is off by default too.
+**Planning** (4) `create_task_plan` `task_status` `workspace_snapshot` `rollback_changes` — snapshot before risky edits, roll back atomically
+
+**Policy** (4) `list_allowed_paths` `allow_path` `deny_path` `shell_enabled` — each token manages only its own sandbox
 
 ## Security model
 
-- **Bind-local only.** The gateway listens on `127.0.0.1:8765` — unreachable from the network directly.
-- **Token auth on every request.** Two forms supported: bearer header or URL path.
-- **Path policy engine.** Filesystem tools resolve symlinks and normalize `..` traversal before checking allow/deny lists. Deny always wins.
-- **Shell behind a flag.** Off until you explicitly turn it on.
-- **No secrets in logs.** The token is never printed to stdout in full after generation.
+- **Loopback only.** The gateway listens on `127.0.0.1` — unreachable directly from the network.
+- **Timing-safe token auth** on every request; tokens never appear in logs (audits store fingerprints).
+- **Per-token sandbox.** Path policy resolves symlinks and collapses `..` before checking; deny always wins.
+- **Per-token scopes + read-only + rate limit + expiry.** Least privilege by construction.
+- **SSRF guards** on all outbound fetch tools — the AI can't reach your metadata endpoints or internal services.
+- **Injection guards.** git verbs whitelisted, SQL single-statement, ATTACH blocked, unit names validated.
+- **Tamper-evident audit.** Every tool invocation → SQLite with a hash chain; `ramcp audit --verify` detects deletions/edits. Secrets in arguments are redacted before storage.
+- **Hot-reload.** Policy edits apply on the next request — no restart, no downtime.
+- **Global read-only** kill-switch: `ramcp policy readonly on`.
 
-You are expected to put TLS in front (nginx + Let's Encrypt, or your CDN edge). The gateway itself speaks plain HTTP on loopback — same pattern as phpMyAdmin, Redis, and every other loopback service.
+You provide TLS (nginx + Cloudflare/Let's Encrypt). The gateway speaks plain HTTP on loopback, like every other loopback service.
 
 ## FAQ
 
 **Is exposing a shell to an AI safe?**
-It's exposing a shell to *you*, via the AI as the interface. The token gates everything; shell is opt-in; filesystem is policy-sandboxed. If you wouldn't give an intern SSH access, don't give them this token.
+It's exposing a shell to *you*, via the AI as the interface. Least-privilege tokens, scoped tools, off-by-default shell, tamper-evident audit, and a read-only mode give you dials that raw SSH doesn't.
+
+**Stateless sessions?**
+Each request builds a fresh MCP transport. No session state to corrupt, trivially scalable, and it's the mode ChatGPT's connector flow works best with.
+
+**Where does config live?**
+`~/.config/remote-access-mcp/config.json` (0600) + `audit.db` + `schedule.json` alongside it.
 
-**Why stateless mode?**
-Each request creates a fresh MCP transport. No session state to corrupt, trivially horizontal-scalable, and it's what ChatGPT's connector flow works best with.
+## Development
+
+```bash
+git clone https://github.com/AmirAliManzar/remote-access-mcp
+cd remote-access-mcp
+npm ci && npm run build && npm test
+```
 
-**Does it run as root?**
-It can, and on a dedicated server that's often simplest — the tools need broad access to be useful. The policy engine is the guardrail, not the UID.
+42 tests: policy engine, auth matrix, tools-over-MCP integration, full v2 security matrix (scopes, read-only, SSRF, injection, audit chain), CLI lifecycle. CI runs on Node 18/20/22.
 
 ## License
 

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAqXA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBxD"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAqlBA,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBxD"}