Merge pull request #37 from Curabis/rule/mcp-config-must-not-hardcode-developer-paths

[BCQuality] Shared MCP configuration must not hardcode developer-specific paths

custom/knowledge/mcp/mcp-config-must-not-hardcode-developer-paths.md

@@ -0,0 +1,67 @@
+---
+rule: mcp-config-must-not-hardcode-developer-paths
+title: Shared MCP configuration must not hardcode developer-specific paths
+category: mcp
+severity: error
+version: 1
+---
+
+# Shared MCP configuration must not hardcode developer-specific paths
+
+## Rule
+
+A git-committed `.mcp.json` must not hardcode an absolute path that is specific to
+one developer's machine — a repository clone location on a particular drive or
+folder, or a home-directory path containing a specific username. Any such path
+must be resolved via Claude Code's built-in environment-variable expansion instead.
+
+## Why
+
+`.mcp.json` is shared and committed — every developer who clones the repository
+inherits the exact same file. A path baked in for the machine of whoever wrote the
+file (e.g. `C:\Curabis\ProjectX\...` or `C:\Users\<username>\.claude\bridge.js`)
+works only for that one person. Every other developer's MCP servers silently fail
+to start, and the failure looks like a runtime problem rather than a configuration
+one — wasting time in the wrong place (see `mcp-server-must-be-verified-at-session-start.md`,
+which detects the symptom but not this root cause).
+
+## How to fix
+
+Claude Code expands two forms of variable inside `.mcp.json`'s `command`, `args`,
+`env`, `url`, and `headers` fields:
+
+- `${VAR}` — any OS environment variable, e.g. `${USERPROFILE}` on Windows resolves
+  to the current user's home directory.
+- `${CLAUDE_PROJECT_DIR:-default}` — the project root directory that Claude Code
+  itself sets when it spawns a stdio MCP server. The `:-default` fallback is
+  required because the variable is only available in the spawned process's
+  environment, not at config-parse time.
+
+Example:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "command": "powershell",
+      "args": ["-File", "${CLAUDE_PROJECT_DIR:-.}\\.vscode\\launch-server.ps1"]
+    },
+    "bridge": {
+      "command": "node",
+      "args": ["${USERPROFILE}\\.claude\\bridge.js"]
+    }
+  }
+}
+```
+
+## What NOT to do
+
+- Do not hardcode a drive letter + folder path that reflects one developer's clone
+  location.
+- Do not hardcode `C:\Users\<name>\...` — every developer has a different username.
+- Do not "fix it locally" by editing the committed file to match your own machine —
+  that only moves the breakage to the next developer who pulls.
+
+## Applies to
+
+All CURABIS projects that configure MCP servers in `.mcp.json`.