feat: add tools for discovering MCP client configs

Add comprehensive tooling to help discover and add new MCP clients:

Tools:
- mcp-client-sniffer.cjs: Minimal MCP server to capture clientInfo
- verify-client-configs.js: Check which clients are installed
- npm run verify-clients: Convenience script

Documentation:
- docs/discovering-new-clients.md: Complete guide for adding clients
  - How to capture clientInfo.name
  - How to find config paths
  - Testing and validation steps
  - Examples with Cursor and Enconvo

These tools enable contributors to easily add support for new MCP
clients by discovering their handshake details and config locations.

Author: Arul-

docs/discovering-new-clients.md

@@ -0,0 +1,377 @@
+# Discovering New MCP Clients
+
+This guide explains how to add support for new MCP clients to NCP's auto-import feature.
+
+## Overview
+
+To support a new MCP client, we need two key pieces of information:
+1. **Client Name**: What `clientInfo.name` the client sends during MCP handshake
+2. **Config Path**: Where the client stores its MCP server configurations
+
+## Step 1: Capture Client Name
+
+### Method A: Use the MCP Client Sniffer (Recommended)
+
+The sniffer is a minimal MCP server that logs initialization requests.
+
+1. **Add sniffer to client config**:
+
+   ```json
+   {
+     "mcpServers": {
+       "client-sniffer": {
+         "command": "node",
+         "args": ["/path/to/ncp/scripts/mcp-client-sniffer.cjs"]
+       }
+     }
+   }
+   ```
+
+2. **Restart the client** or reload MCP connections
+
+3. **Check the output**:
+   - Console will show: `✨ CLIENT DETECTED!`
+   - Details saved to: `client-info-log.json`
+
+4. **Review captured data**:
+   ```bash
+   cat client-info-log.json
+   ```
+
+   Example output:
+   ```json
+   [
+     {
+       "timestamp": "2025-10-31T12:00:00.000Z",
+       "clientInfo": {
+         "name": "cursor",
+         "version": "0.42.0"
+       },
+       "protocolVersion": "2024-11-05"
+     }
+   ]
+   ```
+
+### Method B: Check Client Documentation
+
+Some clients document their `clientInfo.name`:
+- Claude Desktop: `claude-desktop` or `claude-ai`
+- Cursor: `cursor`
+- Cline: `cline`
+- Continue: `continue`
+
+### Method C: Monitor MCP Logs
+
+If the client creates logs, check for initialization messages:
+
+```bash
+# Example: Check Windsurf logs
+find ~/Library/Application\ Support/Windsurf/logs -name "*mcp*" | head -5
+```
+
+## Step 2: Find Config Path
+
+### Search Strategy
+
+1. **Check home directory**:
+   ```bash
+   ls -la ~ | grep -i <client-name>
+   ```
+
+2. **Check .config directory**:
+   ```bash
+   ls -la ~/.config | grep -i <client-name>
+   ```
+
+3. **Check Application Support** (macOS):
+   ```bash
+   ls -la ~/Library/Application\ Support/ | grep -i <client-name>
+   ```
+
+4. **Check AppData** (Windows):
+   ```powershell
+   ls $env:APPDATA | Select-String <client-name>
+   ```
+
+5. **Search for MCP-related files**:
+   ```bash
+   find ~ -name "*mcp*.json" 2>/dev/null | grep -i <client-name>
+   ```
+
+### Common Patterns
+
+| Location | Example |
+|----------|---------|
+| Home dotfiles | `~/.cursor/mcp.json` |
+| .config | `~/.config/enconvo/mcp_config.json` |
+| Application Support | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| VSCode-like | `~/Library/Application Support/<IDE>/User/globalStorage/<extension>/settings/*.json` |
+
+### Verify Config Format
+
+Once you find the config file:
+
+```bash
+cat <config-path> | jq '.mcpServers'
+```
+
+Check:
+- ✅ Is it JSON or TOML?
+- ✅ Where are MCP servers stored? (root level? nested path?)
+- ✅ What's the structure? (object with MCP names as keys?)
+
+Example structures:
+
+**Standard format** (Claude Desktop, Cursor):
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
+    }
+  }
+}
+```
+
+**Nested format** (Continue):
+```json
+{
+  "experimental": {
+    "modelContextProtocolServers": {
+      "filesystem": { ... }
+    }
+  }
+}
+```
+
+**Array format** (Perplexity):
+```json
+{
+  "servers": [
+    { "name": "filesystem", "command": "..." }
+  ]
+}
+```
+
+## Step 3: Add to Client Registry
+
+Update `src/utils/client-registry.ts`:
+
+```typescript
+'<client-id>': {
+  displayName: '<Client Name>',
+  configPaths: {
+    darwin: '~/path/to/config.json',           // macOS
+    win32: '%APPDATA%/path/to/config.json',    // Windows
+    linux: '~/.config/path/to/config.json'     // Linux
+  },
+  configFormat: 'json',  // or 'toml'
+  mcpServersPath: 'mcpServers'  // JSON path to servers object
+}
+```
+
+### Important Notes
+
+1. **Client ID normalization**: NCP normalizes client names by:
+   - Converting to lowercase
+   - Removing spaces and dashes
+   - Example: `"Claude Desktop"` → `"claudedesktop"`
+
+2. **Add all aliases**: Some clients send different names:
+   ```typescript
+   'claude-desktop': { ... },
+   'claude-ai': { ... },  // Alias pointing to same paths
+   ```
+
+3. **Platform-specific paths**: Only include paths for supported platforms
+
+## Step 4: Test Auto-Import
+
+### Build and Verify
+
+```bash
+# 1. Build
+npm run build
+
+# 2. Check detection
+node scripts/verify-client-configs.js
+
+# Expected output:
+# ✅ INSTALLED CLIENTS (Can Test Auto-Import)
+# 📦 <Your Client>
+#    Client ID: <client-id>
+#    Config: /actual/path/to/config.json
+```
+
+### Manual Test
+
+```bash
+# 1. Clear NCP profile
+rm ~/.ncp/profiles/all.json
+
+# 2. Start NCP with client's name
+# (or configure client to use NCP and restart)
+
+# 3. Check if MCPs were imported
+cat ~/.ncp/profiles/all.json | jq '.mcpServers'
+```
+
+### Integration Test
+
+Add test to `tests/integration/comprehensive-dxt-test.cjs`:
+
+```javascript
+const id = test.sendRequest('initialize', {
+  protocolVersion: '2024-11-05',
+  clientInfo: {
+    name: '<client-id>',
+    version: '1.0.0'
+  }
+});
+```
+
+## Step 5: Document
+
+Update docs:
+1. **docs/testing-client-auto-import.md** - Add config path reference
+2. **README.md** - Add client to supported list
+3. **docs/clients/<client>.md** - Create setup guide (optional)
+
+## Examples
+
+### Example 1: Cursor
+
+**Discovery**:
+```bash
+# Found config
+ls ~/.cursor/
+# Output: mcp.json
+
+# Verified format
+cat ~/.cursor/mcp.json
+# Shows: { "mcpServers": { ... } }
+```
+
+**Captured clientInfo** (using sniffer):
+```json
+{
+  "clientInfo": {
+    "name": "cursor",
+    "version": "0.42.0"
+  }
+}
+```
+
+**Added to registry**:
+```typescript
+'cursor': {
+  displayName: 'Cursor',
+  configPaths: {
+    darwin: '~/.cursor/mcp.json',
+    win32: '%USERPROFILE%/.cursor/mcp.json',
+    linux: '~/.cursor/mcp.json'
+  },
+  configFormat: 'json',
+  mcpServersPath: 'mcpServers'
+}
+```
+
+### Example 2: Enconvo
+
+**Discovery**:
+```bash
+# Search for config
+find ~ -name "*enconvo*" -type d
+# Found: ~/.config/enconvo
+
+# Check contents
+ls ~/.config/enconvo/
+# Found: mcp_config.json
+
+# Verify format
+cat ~/.config/enconvo/mcp_config.json
+# Shows: { "mcpServers": {} }
+```
+
+**Added to registry**:
+```typescript
+'enconvo': {
+  displayName: 'Enconvo',
+  configPaths: {
+    darwin: '~/.config/enconvo/mcp_config.json'
+  },
+  configFormat: 'json',
+  mcpServersPath: 'mcpServers'
+}
+```
+
+## Troubleshooting
+
+### Client not detected
+
+1. **Check client name normalization**:
+   ```javascript
+   // In src/utils/client-registry.ts
+   export function normalizeClientName(name: string): string {
+     return name.toLowerCase().replace(/[\s-]/g, '');
+   }
+   ```
+
+2. **Verify config exists**:
+   ```bash
+   ls -la <config-path>
+   ```
+
+3. **Check NCP logs**:
+   ```bash
+   export NCP_DEBUG=true
+   cat ~/.ncp/debug.log | grep -i "client"
+   ```
+
+### MCPs not imported
+
+1. **Check mcpServersPath**: Verify JSON path is correct
+   ```bash
+   cat <config> | jq '.<mcpServersPath>'
+   ```
+
+2. **Test config parsing**:
+   ```javascript
+   import { importFromClient } from './dist/utils/client-importer.js';
+   const result = await importFromClient('<client-id>');
+   console.log(result);
+   ```
+
+### Config format issues
+
+1. **TOML support**: Use `configFormat: 'toml'` and install parser
+2. **Custom format**: Add custom parser in `client-importer.ts`
+3. **Array format**: Update `mcpServersPath` to handle arrays
+
+## Tools Reference
+
+### Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/mcp-client-sniffer.cjs` | Capture clientInfo from any MCP client |
+| `scripts/verify-client-configs.js` | Check which clients are installed and detectable |
+| `scripts/capture-client-info.js` | Advanced monitoring with NCP server |
+
+### Files to Update
+
+| File | What to Add |
+|------|-------------|
+| `src/utils/client-registry.ts` | Client definition with paths |
+| `src/utils/client-importer.ts` | Custom parsers (if needed) |
+| `docs/testing-client-auto-import.md` | Testing instructions |
+| `tests/integration/comprehensive-dxt-test.cjs` | Integration test |
+
+## Best Practices
+
+1. **Test on actual installations** - Don't guess paths
+2. **Document platform differences** - Note any OS-specific quirks
+3. **Handle edge cases** - Client might not have MCPs configured yet
+4. **Validate data** - Ensure MCPs have required `command` field
+5. **Preserve user data** - Don't overwrite existing configs during import

package.json

@@ -41,6 +41,7 @@
     "test:client-registry": "node scripts/test-client-registry.js",
     "test:registry-security": "node scripts/test-registry-security.js",
     "test:http-auth": "node scripts/test-http-auth.js",
+    "verify-clients": "npm run build && node scripts/verify-client-configs.js",
     "build:dxt": "bash scripts/build-dxt-clean.sh",
     "build:dxt:patched": "npm run build:dxt && ./scripts/patch-dxt-zip.sh",
     "build:dxt:signed": "npm run build:dxt:patched && npx @anthropic-ai/mcpb sign ncp.dxt --self-signed && npm run test:dxt",