From 38edc4ac3676df6607640de644a8530d97f95782 Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Sat, 20 Jun 2026 18:05:05 -0500 Subject: [PATCH] vscode config improvements --- docs/skills/vscode-configuration/SKILL.md | 9 ++ .../references/debug-launch-configurations.md | 19 ++- .../references/fastapi-debugpy-launch.md | 13 +- .../references/mcp-server-configuration.md | 123 ++++++++++++++++++ .../references/tasks-json-configuration.md | 19 ++- 5 files changed, 169 insertions(+), 14 deletions(-) create mode 100644 docs/skills/vscode-configuration/references/mcp-server-configuration.md diff --git a/docs/skills/vscode-configuration/SKILL.md b/docs/skills/vscode-configuration/SKILL.md index 70f5d46..47d93bc 100644 --- a/docs/skills/vscode-configuration/SKILL.md +++ b/docs/skills/vscode-configuration/SKILL.md @@ -22,12 +22,20 @@ x-personal-mcp: Use this skill to design or repair repeatable VS Code workspace configuration for local development workflows. +Primary VS Code source docs: + +- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging) +- [Debug configuration (`launch.json`)](https://code.visualstudio.com/docs/debugtest/debugging-configuration) +- [Tasks (`tasks.json`)](https://code.visualstudio.com/docs/editor/tasks) +- [MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers) + ## When to Use - You need to create or fix `.vscode/launch.json` debug profiles. - You need robust Python debugging with `debugpy`. - You need FastAPI-specific launch profiles (app module, host/port, reload options, env files). - You need `.vscode/tasks.json` build/test/run tasks and optional debug pre-launch integration. +- You need `.vscode/mcp.json` workspace or user profile MCP server configuration. - You need consistent workspace onboarding where users can run and debug from VS Code with minimal manual setup. ## Progressive References @@ -37,6 +45,7 @@ Load only the page that matches the current request: - Launch profile mechanics and debugpy patterns: [debug launch configurations](./references/debug-launch-configurations.md) - FastAPI-focused debug profiles using debugpy: [FastAPI + debugpy launch patterns](./references/fastapi-debugpy-launch.md) - Task runner setup in VS Code: [tasks.json project tasks](./references/tasks-json-configuration.md) +- MCP server setup in VS Code: [mcp.json MCP server configuration](./references/mcp-server-configuration.md) ## Procedure diff --git a/docs/skills/vscode-configuration/references/debug-launch-configurations.md b/docs/skills/vscode-configuration/references/debug-launch-configurations.md index f702dc4..298616f 100644 --- a/docs/skills/vscode-configuration/references/debug-launch-configurations.md +++ b/docs/skills/vscode-configuration/references/debug-launch-configurations.md @@ -1,6 +1,6 @@ # Debug Launch Configurations in VS Code -This reference focuses on Python debugging through `debugpy` using `.vscode/launch.json`. +This reference focuses on Python debugging through [`debugpy`](https://github.com/microsoft/debugpy) using [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration). ## Core Structure @@ -15,15 +15,15 @@ A minimal launch file: Useful fields for Python configs: -- `type`: Use `debugpy`. +- `type`: Use [`debugpy`](https://code.visualstudio.com/docs/python/debugging). - `request`: Usually `launch`, sometimes `attach`. - `name`: Friendly profile name shown in the Run and Debug panel. - `program`: Script path for script-based entry. - `module`: Module name for `python -m ...` style launches. - `args`: CLI arguments. -- `cwd`: Working directory. -- `env` / `envFile`: Environment variables. -- `console`: `integratedTerminal` is usually most practical. +- `cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)). +- `env` / `envFile`: Environment variables (commonly from [environment variable definitions files](https://code.visualstudio.com/docs/python/environments#_environment-variable-definitions-file)). +- `console`: `integratedTerminal` is usually most practical ([launch options](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes)). - `justMyCode`: `true` by default; set `false` when stepping into dependencies. ## Launch vs Attach @@ -46,7 +46,7 @@ Attach profile example: } ``` -Remote process side command example: +Remote process side command example (from [debugpy CLI usage](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging)): ```bash python -m debugpy --listen 5678 -m your_package.main @@ -90,6 +90,13 @@ Prefer module mode when imports depend on package layout. - Keep secrets out of committed launch configs. - Ensure the selected VS Code interpreter matches project tooling. +## Source Documentation + +- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging) +- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration) +- [Variables reference](https://code.visualstudio.com/docs/editor/variables-reference) +- [debugpy project](https://github.com/microsoft/debugpy) + ## Troubleshooting If breakpoints do not hit: diff --git a/docs/skills/vscode-configuration/references/fastapi-debugpy-launch.md b/docs/skills/vscode-configuration/references/fastapi-debugpy-launch.md index 1d53785..11cb23a 100644 --- a/docs/skills/vscode-configuration/references/fastapi-debugpy-launch.md +++ b/docs/skills/vscode-configuration/references/fastapi-debugpy-launch.md @@ -1,6 +1,6 @@ # FastAPI Debug Launch with debugpy -This reference provides practical `.vscode/launch.json` patterns for FastAPI applications started with uvicorn. +This reference provides practical [`.vscode/launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration) patterns for [FastAPI](https://fastapi.tiangolo.com/) applications started with [uvicorn](https://www.uvicorn.org/). ## Launch FastAPI via Module @@ -57,9 +57,11 @@ If app is created via factory function: } ``` +Factory mode is powered by uvicorn's [`--factory`](https://www.uvicorn.org/settings/#application) option. + ## Attach to an Existing FastAPI Process -If the app is launched externally, start with debugpy: +If the app is launched externally, start with [`debugpy`](https://code.visualstudio.com/docs/python/debugging#_command-line-debugging): ```bash python -m debugpy --listen 5678 -m uvicorn your_package.main:app --host 127.0.0.1 --port 8000 --reload @@ -96,3 +98,10 @@ A profile is considered valid when: 2. A breakpoint inside an endpoint is hit on request. 3. A breakpoint in startup/lifespan logic is hit at app boot. 4. Terminal output appears in integrated terminal with expected log level. + +## Source Documentation + +- [FastAPI docs](https://fastapi.tiangolo.com/) +- [Uvicorn settings and CLI options](https://www.uvicorn.org/settings/) +- [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging) +- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration) diff --git a/docs/skills/vscode-configuration/references/mcp-server-configuration.md b/docs/skills/vscode-configuration/references/mcp-server-configuration.md new file mode 100644 index 0000000..35540af --- /dev/null +++ b/docs/skills/vscode-configuration/references/mcp-server-configuration.md @@ -0,0 +1,123 @@ +# Configure MCP Servers in VS Code + +Use this reference to configure MCP servers for GitHub Copilot chat in VS Code with `.vscode/mcp.json` (workspace) or profile-level `mcp.json` (user scope). + +## Where Configuration Lives + +VS Code supports two MCP configuration locations: + +- Workspace scope: `.vscode/mcp.json` in the repository. +- User profile scope: open with the `MCP: Open User Configuration` command. + +Use workspace scope for shared team configuration, and user scope for personal or machine-specific servers. + +## Minimal mcp.json + +```json +{ + "servers": { + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp" + }, + "playwright": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@microsoft/mcp-server-playwright"] + } + } +} +``` + +The `servers` object keys are logical server names shown in VS Code MCP management surfaces. + +## Add Servers Through VS Code UI + +1. Run `MCP: Add Server` from the Command Palette. +2. Choose Workspace or Global target. +3. Review generated config in `mcp.json`. +4. Start or restart the server from `MCP: List Servers`. + +This guided flow is usually safer than manual edits when onboarding teammates. + +## Security and Secrets + +1. Do not hardcode tokens or API keys in `mcp.json`. +2. Prefer input variables or environment-file patterns supported by the MCP configuration schema. +3. Start only trusted servers, because local servers can execute code on your machine. +4. Use trust prompts as a checkpoint instead of bypassing review. + +## Security Best Practices + +1. Apply least privilege by default. +2. Keep workspace `mcp.json` limited to team-safe, non-secret configuration. +3. Keep personal credentials and machine-specific settings in user-scope configuration, not repository files. +4. Prefer explicit allowlists for filesystem writes and outbound network access when sandboxing is enabled. +5. Use one server per trust boundary instead of one large multi-purpose server. +6. Review server `command` and `args` as code during pull requests. +7. Disable or uninstall unused MCP servers to reduce attack surface. +8. Use HTTPS endpoints for remote MCP servers whenever available. +9. Pin server packages or versions where practical to avoid accidental supply-chain drift. +10. Reset trust and re-review configuration after major server changes. + +### Operational Guardrails + +1. Treat MCP resources as publishable unless an explicit access control layer exists. +2. Capture server logs during onboarding so failures and suspicious behavior are easier to detect. +3. Define ownership for each server entry, including who approves changes and who rotates secrets. +4. Document upgrade triggers: if a server starts reading private data or executing side-effectful actions, require stronger access controls before rollout. + +### Team Review Checklist + +Use this checklist before merging workspace MCP configuration changes: + +1. No plaintext secrets in `mcp.json`. +2. `command` and `args` are from trusted publishers and expected binaries. +3. Server scope is correct (workspace vs user profile). +4. Sandboxing is enabled for local `stdio` servers when supported. +5. Sandbox allowlists are narrow (minimum paths and domains). +6. The change includes an owner and rollback path. + +## Sandbox Local stdio Servers (Linux/macOS) + +For local `stdio` servers, enable sandboxing when possible: + +```json +{ + "servers": { + "myServer": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@example/mcp-server"], + "sandboxEnabled": true + } + }, + "sandbox": { + "filesystem": { + "allowWrite": ["${workspaceFolder}"] + }, + "network": { + "allowedDomains": ["api.example.com"] + } + } +} +``` + +Sandboxing is currently available on Linux and macOS, not Windows. + +## Troubleshooting Checklist + +1. Open server logs from `MCP: List Servers` -> `Show Output`. +2. Confirm trust state (or run `MCP: Reset Trust` if needed). +3. Confirm server command and arguments run outside VS Code. +4. Confirm workspace-vs-user scope matches where you expect the server to run. +5. If using remote development, configure the server in the remote scope when needed. + +## Source Documentation + +- [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers) +- [MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) +- [Input variables for sensitive data](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_input-variables-for-sensitive-data) +- [Sandbox configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration#_sandbox-configuration) +- [AI security guidance in VS Code](https://code.visualstudio.com/docs/agents/security) +- [Model Context Protocol overview](https://modelcontextprotocol.io/docs/getting-started/intro) diff --git a/docs/skills/vscode-configuration/references/tasks-json-configuration.md b/docs/skills/vscode-configuration/references/tasks-json-configuration.md index 2d51bcb..67acb28 100644 --- a/docs/skills/vscode-configuration/references/tasks-json-configuration.md +++ b/docs/skills/vscode-configuration/references/tasks-json-configuration.md @@ -1,6 +1,6 @@ # Configure Project Tasks in tasks.json -Use `.vscode/tasks.json` to define repeatable project commands and optional hooks for debugging. +Use [`.vscode/tasks.json`](https://code.visualstudio.com/docs/editor/tasks) to define repeatable project commands and optional hooks for debugging. ## Minimal File @@ -14,12 +14,12 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook ## Task Fields You Will Use Most - `label`: Task name shown in VS Code. -- `type`: Usually `shell`. +- `type`: Usually [`shell`](https://code.visualstudio.com/docs/editor/tasks#_custom-tasks). - `command`: Executable to run. - `args`: Command arguments. -- `options.cwd`: Working directory. -- `group`: Mark default build or test tasks. -- `problemMatcher`: Parse errors into the Problems panel. +- `options.cwd`: Working directory (supports [variable substitution](https://code.visualstudio.com/docs/editor/variables-reference)). +- `group`: Mark default build or test tasks ([task groups](https://code.visualstudio.com/docs/editor/tasks#_grouping-tasks)). +- `problemMatcher`: Parse errors into the Problems panel ([problem matchers](https://code.visualstudio.com/docs/editor/tasks#_defining-a-problem-matcher)). - `isBackground`: `true` for long-running tasks (for example dev server watch). ## Python Project Example @@ -56,7 +56,7 @@ Use `.vscode/tasks.json` to define repeatable project commands and optional hook ## Connect Tasks to Debug Profiles -In `launch.json`, you can run a task first: +In [`launch.json`](https://code.visualstudio.com/docs/debugtest/debugging-configuration), you can run a task first with [`preLaunchTask`](https://code.visualstudio.com/docs/debugtest/debugging-configuration#_launchjson-attributes): ```json { @@ -90,3 +90,10 @@ If a task fails unexpectedly: 3. Confirm tool availability in environment path. 4. Confirm quoting and argument boundaries in `args`. 5. Confirm the task is not blocked by an outdated background process. + +## Source Documentation + +- [VS Code Tasks (official)](https://code.visualstudio.com/docs/editor/tasks) +- [Tasks Appendix (schema and interfaces)](https://code.visualstudio.com/docs/reference/tasks-appendix) +- [Variables Reference](https://code.visualstudio.com/docs/editor/variables-reference) +- [Debug configuration and launch.json](https://code.visualstudio.com/docs/debugtest/debugging-configuration)