feat: add USER-tier MCP shortcut/description overrides in pai.ts

[jacobo-ortiz]

Summary

• Adds loadUserConfig() to pai.ts that reads PAI/USER/MCP_SHORTCUTS.json and PAI/USER/PROFILE_DESCRIPTIONS.json, merging USER keys over SYSTEM defaults
• Users can now add custom MCP shortcuts without modifying pai.ts (system-tier file)
• Follows the SYSTEM/USER two-tier pattern documented in SYSTEM_USER_EXTENDABILITY.md
• Adds TODO(#901) comment documenting the known settings.json vs .mcp.json config mismatch

Problem

MCP_SHORTCUTS and PROFILE_DESCRIPTIONS are hardcoded constants in pai.ts. Users who add custom MCP servers (Telegram, Affine, Cloudflare, etc.) must either:

1. Modify pai.ts directly — breaks on every PAI update
2. Skip shortcuts entirely — lose the ergonomic k -m name CLI experience

This violates PAI's own SYSTEM/USER extensibility pattern, which already works for security patterns (PAISECURITYSYSTEM/), skills (SKILLCUSTOMIZATIONS/), and response formats.

Related issues: #901, #646, #650

Implementation

1 file changed, 48 insertions, 4 deletions.

loadUserConfig(filename, systemDefaults) (~25 lines)

• Reads PAI/USER/{filename} JSON
• Merges via { ...systemDefaults, ...parsed } — USER keys win on collision, SYSTEM keys persist
• ENOENT (no file): silent fallback — this is the common case
• Parse error: console.error warning + fallback to SYSTEM defaults
• Non-object JSON (array, null): warning + fallback

getMcpShortcuts() / getProfileDescriptions()

• Accessor functions replacing 4 direct constant accesses
• Hoisted before loops to avoid repeated file reads

Design decisions

• Merge, not replace: Shortcuts are additive lookup tables. A user adding tg: Telegram-MCP.json shouldn't lose 13 SYSTEM shortcuts. This is a documented exception to the "USER replaces SYSTEM" convention — additive maps deserve additive semantics.
• JSON format: Zero dependency (JSON.parse built-in). Consistent with *.mcp.json files already in MCPs/.
• PAI/USER/ location: Consistent with all other USER overrides in the codebase.
• Scope: Does NOT bundle the PAI repeatedly writes MCP config to settings.json instead of ~/.claude.json #901 settings.json mismatch fix — separate concern, different risk surface. Adds a TODO(#901) comment instead.

User experience

# Create PAI/USER/MCP_SHORTCUTS.json:
echo '{"tg": "Telegram-MCP.json", "atlas": "atlas.mcp.json"}' > ~/.claude/PAI/USER/MCP_SHORTCUTS.json

# Now works:
k -m tg          # Resolves to Telegram-MCP.json from MCPs/
k mcp set atlas  # Resolves atlas.mcp.json from MCPs/

# SYSTEM shortcuts unaffected:
k -m bd          # Still resolves Brightdata-MCP.json

Test plan

Tested on WSL2 (Ubuntu, Linux 6.6.87.2) with Bun runtime.

• USER shortcuts resolve via k -m <name> and k mcp set <profile>
• USER descriptions display in k mcp list and k profiles
• Missing USER file: silent fallback, 0 warnings, SYSTEM shortcuts work
• Malformed USER JSON: warning printed, falls back to SYSTEM defaults
• Array JSON ([1,2,3]): warning + fallback (not a valid object)
• SYSTEM shortcuts persist when USER file adds new keys (merge, not replace)
• Zero breaking changes to existing CLI behavior

# Verification commands:
bun PAI/Tools/pai.ts mcp list           # Should show USER + SYSTEM entries
bun PAI/Tools/pai.ts mcp set <profile>  # Should resolve USER profiles

# Error handling:
echo "broken" > ~/.claude/PAI/USER/MCP_SHORTCUTS.json
bun PAI/Tools/pai.ts mcp list 2>&1      # Should show warning + SYSTEM defaults

Generated with Claude Code