1  # EasyShell MCP Tool Catalog
  2  
  3  This catalog covers all 19 tools exposed by `@easyshell/mcp-server`, grouped by capability tier.
  4  
  5  ## Tier 1 — Core (6 tools)
  6  
  7  ### 1) `list_hosts`
  8  List managed hosts with status, identity, and summary metrics.
  9  
 10  | Parameter | Type | Required | Description |
 11  |---|---|---:|---|
 12  | `status` | `"online" \| "offline" \| "all"` | No | Filters hosts by connectivity state. |
 13  
 14  **Example**
 15  ```json
 16  {"tool":"list_hosts","arguments":{"status":"online"}}
 17  ```
 18  
 19  **Expected response**
 20  - Array of host objects (`id`, `hostname`, `ip`, `status`, `os`, usage metrics).
 21  
 22  ### 2) `get_host_detail`
 23  Get detailed host information, including tags and runtime details.
 24  
 25  | Parameter | Type | Required | Description |
 26  |---|---|---:|---|
 27  | `hostId` | `string` | Yes | Unique host/agent ID. |
 28  
 29  **Example**
 30  ```json
 31  {"tool":"get_host_detail","arguments":{"hostId":"host-001"}}
 32  ```
 33  
 34  **Expected response**
 35  - Single host detail object with metadata, labels, and health fields.
 36  
 37  ### 3) `execute_script`
 38  Execute shell content on one or more target hosts.
 39  
 40  | Parameter | Type | Required | Description |
 41  |---|---|---:|---|
 42  | `hostIds` | `string[]` | Yes | Target host IDs for execution. |
 43  | `script` | `string` | Yes | Shell script content to run. |
 44  | `timeoutSec` | `number` | No | Execution timeout in seconds. |
 45  | `name` | `string` | No | Friendly task name. |
 46  
 47  **Example**
 48  ```json
 49  {
 50    "tool":"execute_script",
 51    "arguments":{
 52      "hostIds":["host-001","host-002"],
 53      "script":"df -h && free -m",
 54      "timeoutSec":120,
 55      "name":"capacity-check"
 56    }
 57  }
 58  ```
 59  
 60  **Expected response**
 61  - Task creation result (`taskId`, state, queued targets).
 62  
 63  ### 4) `get_task_detail`
 64  Fetch per-host execution output and status for a task.
 65  
 66  | Parameter | Type | Required | Description |
 67  |---|---|---:|---|
 68  | `taskId` | `string` | Yes | Task identifier returned by execution APIs. |
 69  
 70  **Example**
 71  ```json
 72  {"tool":"get_task_detail","arguments":{"taskId":"task-abc123"}}
 73  ```
 74  
 75  **Expected response**
 76  - Task object with aggregate status plus per-host logs/exit codes.
 77  
 78  ### 5) `list_scripts`
 79  List reusable scripts in the script library.
 80  
 81  | Parameter | Type | Required | Description |
 82  |---|---|---:|---|
 83  | `keyword` | `string` | No | Search by script name/content hint. |
 84  | `page` | `number` | No | Page number for pagination. |
 85  | `pageSize` | `number` | No | Items per page. |
 86  
 87  **Example**
 88  ```json
 89  {"tool":"list_scripts","arguments":{"keyword":"disk","page":1,"pageSize":20}}
 90  ```
 91  
 92  **Expected response**
 93  - Paginated script list with IDs, names, tags, and updated timestamps.
 94  
 95  ### 6) `ai_chat`
 96  Send a natural-language operations goal to EasyShell AI orchestration.
 97  
 98  | Parameter | Type | Required | Description |
 99  |---|---|---:|---|
100  | `message` | `string` | Yes | Task goal in plain language. |
101  | `contextHostIds` | `string[]` | No | Scope AI execution to selected hosts. |
102  | `stream` | `boolean` | No | Request streaming response when supported. |
103  
104  **Example**
105  ```json
106  {
107    "tool":"ai_chat",
108    "arguments":{
109      "message":"Check disk usage on all production hosts and flag anything above 80%"
110    }
111  }
112  ```
113  
114  **Expected response**
115  - AI plan + execution summary + findings/recommendations.
116  
117  ## Tier 2 — Management (8 tools)
118  
119  ### 7) `list_recent_tasks`
120  List recently executed tasks across hosts.
121  
122  | Parameter | Type | Required | Description |
123  |---|---|---:|---|
124  | `status` | `"running" \| "success" \| "failed" \| "all"` | No | Filter by task status. |
125  | `limit` | `number` | No | Maximum task count. |
126  
127  **Example**
128  ```json
129  {"tool":"list_recent_tasks","arguments":{"status":"failed","limit":20}}
130  ```
131  
132  **Expected response**
133  - Array of task summaries (`taskId`, type, status, createdAt, targets).
134  
135  ### 8) `create_script`
136  Create and save a reusable script in the library.
137  
138  | Parameter | Type | Required | Description |
139  |---|---|---:|---|
140  | `name` | `string` | Yes | Script name. |
141  | `content` | `string` | Yes | Shell script content. |
142  | `description` | `string` | No | Script purpose/notes. |
143  | `tags` | `string[]` | No | Classification tags. |
144  
145  **Example**
146  ```json
147  {
148    "tool":"create_script",
149    "arguments":{
150      "name":"Disk Usage Check",
151      "content":"df -h",
152      "description":"Quick filesystem usage check",
153      "tags":["ops","disk"]
154    }
155  }
156  ```
157  
158  **Expected response**
159  - Created script metadata with assigned `scriptId`.
160  
161  ### 9) `list_clusters`
162  List host clusters/groups used for logical targeting.
163  
164  | Parameter | Type | Required | Description |
165  |---|---|---:|---|
166  | `keyword` | `string` | No | Filter clusters by name. |
167  
168  **Example**
169  ```json
170  {"tool":"list_clusters","arguments":{"keyword":"production"}}
171  ```
172  
173  **Expected response**
174  - Cluster list with IDs, names, and host counts.
175  
176  ### 10) `get_dashboard_stats`
177  Get platform-level metrics and operating overview.
178  
179  | Parameter | Type | Required | Description |
180  |---|---|---:|---|
181  | `window` | `string` | No | Time window (for example `24h`, `7d`). |
182  
183  **Example**
184  ```json
185  {"tool":"get_dashboard_stats","arguments":{"window":"24h"}}
186  ```
187  
188  **Expected response**
189  - Aggregate KPIs: host totals, online rate, task volume, failure rate, load trends.
190  
191  ### 11) `get_host_metrics`
192  Retrieve CPU, memory, and disk history for one host.
193  
194  | Parameter | Type | Required | Description |
195  |---|---|---:|---|
196  | `hostId` | `string` | Yes | Target host ID. |
197  | `from` | `string` | No | Start time (ISO-8601). |
198  | `to` | `string` | No | End time (ISO-8601). |
199  | `interval` | `string` | No | Sampling interval (`1m`, `5m`, `1h`). |
200  
201  **Example**
202  ```json
203  {
204    "tool":"get_host_metrics",
205    "arguments":{
206      "hostId":"host-001",
207      "from":"2025-01-01T00:00:00Z",
208      "to":"2025-01-01T06:00:00Z",
209      "interval":"5m"
210    }
211  }
212  ```
213  
214  **Expected response**
215  - Time-series metric arrays for CPU, memory, and storage utilization.
216  
217  ### 12) `list_scheduled_tasks`
218  List configured cron inspections and automation jobs.
219  
220  | Parameter | Type | Required | Description |
221  |---|---|---:|---|
222  | `enabledOnly` | `boolean` | No | Return only active schedules. |
223  
224  **Example**
225  ```json
226  {"tool":"list_scheduled_tasks","arguments":{"enabledOnly":true}}
227  ```
228  
229  **Expected response**
230  - Schedule list with cron, script target, status, and next run time.
231  
232  ### 13) `trigger_inspection`
233  Manually trigger a scheduled inspection immediately.
234  
235  | Parameter | Type | Required | Description |
236  |---|---|---:|---|
237  | `scheduleId` | `string` | Yes | Scheduled inspection ID. |
238  
239  **Example**
240  ```json
241  {"tool":"trigger_inspection","arguments":{"scheduleId":"sched-001"}}
242  ```
243  
244  **Expected response**
245  - Trigger result with generated run/task ID and initial status.
246  
247  ### 14) `get_inspect_reports`
248  Read AI analysis reports from inspection runs.
249  
250  | Parameter | Type | Required | Description |
251  |---|---|---:|---|
252  | `scheduleId` | `string` | No | Filter by schedule. |
253  | `limit` | `number` | No | Number of reports to return. |
254  
255  **Example**
256  ```json
257  {"tool":"get_inspect_reports","arguments":{"scheduleId":"sched-001","limit":10}}
258  ```
259  
260  **Expected response**
261  - Inspection reports containing findings, severity, and remediation advice.
262  
263  ## Tier 3 — Advanced (5 tools)
264  
265  ### 15) `manage_tags`
266  Create, update, assign, or remove host tags for targeting.
267  
268  | Parameter | Type | Required | Description |
269  |---|---|---:|---|
270  | `action` | `"create" \| "delete" \| "assign" \| "unassign"` | Yes | Tag operation type. |
271  | `tag` | `string` | Yes | Tag label. |
272  | `hostIds` | `string[]` | No | Hosts for assign/unassign actions. |
273  
274  **Example**
275  ```json
276  {
277    "tool":"manage_tags",
278    "arguments":{"action":"assign","tag":"production","hostIds":["host-001"]}
279  }
280  ```
281  
282  **Expected response**
283  - Operation result with affected tags/hosts and status.
284  
285  ### 16) `query_audit_logs`
286  Query operation audit trails for security and compliance.
287  
288  | Parameter | Type | Required | Description |
289  |---|---|---:|---|
290  | `actor` | `string` | No | Filter by username/operator. |
291  | `action` | `string` | No | Filter by action type. |
292  | `from` | `string` | No | Start time (ISO-8601). |
293  | `to` | `string` | No | End time (ISO-8601). |
294  | `limit` | `number` | No | Max record count. |
295  
296  **Example**
297  ```json
298  {
299    "tool":"query_audit_logs",
300    "arguments":{"action":"execute_script","limit":50}
301  }
302  ```
303  
304  **Expected response**
305  - Audit event list with actor, action, target, timestamp, and outcome.
306  
307  ### 17) `approve_task`
308  Approve or reject a blocked high-risk operation.
309  
310  | Parameter | Type | Required | Description |
311  |---|---|---:|---|
312  | `approvalId` | `string` | Yes | Pending approval ID. |
313  | `decision` | `"approve" \| "reject"` | Yes | Approval decision. |
314  | `comment` | `string` | No | Optional reason or note. |
315  
316  **Example**
317  ```json
318  {
319    "tool":"approve_task",
320    "arguments":{"approvalId":"apr-1001","decision":"approve","comment":"Reviewed by ops lead"}
321  }
322  ```
323  
324  **Expected response**
325  - Approval update result and downstream task state.
326  
327  ### 18) `send_notification`
328  Send messages to configured notification channels.
329  
330  | Parameter | Type | Required | Description |
331  |---|---|---:|---|
332  | `channel` | `string` | Yes | Channel key (Discord, Telegram, Slack, etc.). |
333  | `title` | `string` | Yes | Notification title. |
334  | `message` | `string` | Yes | Notification body content. |
335  | `severity` | `"info" \| "warning" \| "critical"` | No | Message severity level. |
336  
337  **Example**
338  ```json
339  {
340    "tool":"send_notification",
341    "arguments":{
342      "channel":"discord",
343      "title":"Disk Alert",
344      "message":"host-001 disk usage reached 91%",
345      "severity":"warning"
346    }
347  }
348  ```
349  
350  **Expected response**
351  - Delivery result with channel status and provider response summary.
352  
353  ### 19) `search_knowledge`
354  Search internal runbooks, notes, and operational knowledge.
355  
356  | Parameter | Type | Required | Description |
357  |---|---|---:|---|
358  | `query` | `string` | Yes | Search query text. |
359  | `limit` | `number` | No | Maximum result entries. |
360  
361  **Example**
362  ```json
363  {"tool":"search_knowledge","arguments":{"query":"nginx 502 troubleshooting","limit":5}}
364  ```
365  
366  **Expected response**
367  - Ranked knowledge entries with title, snippet, and source references.