Skip to content

Commit 5a98b64

Browse files
author
LittleCoinCoin
committed
docs: update CLI reference for MCP host configuration integration
- Document new conversion report output showing field-by-field changes - Add examples demonstrating user feedback display for local/remote servers - Document dry-run mode with conversion report preview - Explain host-specific field support and automatic filtering - Add detailed behavior section explaining UPDATED/UNSUPPORTED/UNCHANGED fields All documentation changes reflect Phase 4 implementation
1 parent d59fc6a commit 5a98b64

File tree

1 file changed

+72
-0
lines changed

1 file changed

+72
-0
lines changed

docs/articles/users/CLIReference.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -361,6 +361,78 @@ Syntax:
361361
| `--auto-approve` | flag | Skip confirmation prompts | false |
362362
| `--no-backup` | flag | Skip backup creation before configuration | false |
363363

364+
**Behavior**:
365+
366+
The command now displays a **conversion report** showing exactly what fields will be configured on the target host. This provides transparency about which fields are supported by the host and what values will be set.
367+
368+
The conversion report shows:
369+
- **UPDATED** fields: Fields being set with their new values (shown as `None --> value`)
370+
- **UNSUPPORTED** fields: Fields not supported by the target host (automatically filtered out)
371+
- **UNCHANGED** fields: Fields that already have the specified value (update operations only)
372+
373+
**Example - Local Server Configuration**:
374+
375+
```bash
376+
$ hatch mcp configure my-server --host claude-desktop --command python --args server.py --env API_KEY=secret
377+
378+
Server 'my-server' created for host 'claude-desktop':
379+
name: UPDATED None --> 'my-server'
380+
command: UPDATED None --> 'python'
381+
args: UPDATED None --> ['server.py']
382+
env: UPDATED None --> {'API_KEY': 'secret'}
383+
url: UPDATED None --> None
384+
385+
Configure MCP server 'my-server' on host 'claude-desktop'? [y/N]: y
386+
[SUCCESS] Successfully configured MCP server 'my-server' on host 'claude-desktop'
387+
```
388+
389+
**Example - Remote Server Configuration**:
390+
391+
```bash
392+
$ hatch mcp configure api-server --host claude-desktop --url https://api.example.com --headers Auth=token
393+
394+
Server 'api-server' created for host 'claude-desktop':
395+
name: UPDATED None --> 'api-server'
396+
command: UPDATED None --> None
397+
args: UPDATED None --> None
398+
env: UPDATED None --> {}
399+
url: UPDATED None --> 'https://api.example.com'
400+
headers: UPDATED None --> {'Auth': 'token'}
401+
402+
Configure MCP server 'api-server' on host 'claude-desktop'? [y/N]: y
403+
[SUCCESS] Successfully configured MCP server 'api-server' on host 'claude-desktop'
404+
```
405+
406+
**Example - Dry Run Mode**:
407+
408+
```bash
409+
$ hatch mcp configure my-server --host gemini --command python --args server.py --dry-run
410+
411+
[DRY RUN] Would configure MCP server 'my-server' on host 'gemini':
412+
[DRY RUN] Command: python
413+
[DRY RUN] Args: ['server.py']
414+
[DRY RUN] Backup: Enabled
415+
[DRY RUN] Preview of changes for server 'my-server':
416+
name: UPDATED None --> 'my-server'
417+
command: UPDATED None --> 'python'
418+
args: UPDATED None --> ['server.py']
419+
env: UPDATED None --> {}
420+
url: UPDATED None --> None
421+
422+
No changes were made.
423+
```
424+
425+
**Host-Specific Field Support**:
426+
427+
Different MCP hosts support different configuration fields. The conversion report automatically filters unsupported fields:
428+
429+
- **Claude Desktop / Claude Code**: Supports universal fields only (command, args, env, url, headers, type)
430+
- **Cursor / LM Studio**: Supports universal fields + envFile
431+
- **VS Code**: Supports universal fields + envFile, inputs
432+
- **Gemini CLI**: Supports universal fields + 14 additional fields (cwd, timeout, trust, OAuth settings, etc.)
433+
434+
When configuring a server with fields not supported by the target host, those fields are marked as UNSUPPORTED in the report and automatically excluded from the configuration.
435+
364436
### `hatch mcp sync`
365437

366438
Synchronize MCP configurations across environments and hosts.

0 commit comments

Comments
 (0)