ghcp-cli-config

# GHCP CLI Config Configure GitHub Copilot CLI (the `copilot` command) for the workflows this catalog assumes — six MCP servers, sane `settings.json` defaults, the work-iq plugin family for Microsoft staff, sensible `autoApprove` guardrails, and a fresh-machine bootstrap the agent can run end-to-end. > **Provenance.** Distilled from the live `~/.copilot/` of an active > GBB engineer working across Threadlight, Foundry, and Citadel. All > real API keys have been replaced with `<your-…-key>` placeholders. > All real folder names in `trustedFolders` have been replaced with > generic placeholders. The `m-*.json` managed files are deliberately > NOT documented as user-editable — Copilot CLI rewrites them and your > edits will be lost. --- ## When to use Invoke this skill when: - Setting up Copilot CLI on a **fresh machine** for the first time - Adding a new MCP server (`add ms learn mcp`, `add azure mcp`, …) - A teammate asks "what should my `mcp-config.json` look like?" - You want to enable `sessionSync` to roam sessions across machines - You need to whitelist `trustedFolders` so the agent stops asking on every cd into a working repo - You're enabling Microsoft staff plugins (work-iq, m365-agents-toolkit) ## When NOT to use - **Authoring a new skill** → use `skill-creator` - **Per-tenant Azure isolation** → use `azure-tenant-isolation` (sets `AZURE_CONFIG_DIR` per shell — the Azure MCP server below honors it) - **Cursor / Claude Code / Zed config** → different runtimes, different files; this skill only covers GHCP CLI --- ## File map (where everything lives) ``` ~/.copilot/ ├── settings.json ← USER-EDITABLE. Top-level prefs (model, sync, trusted folders, plugins). ├── mcp-config.json ← USER-EDITABLE. MCP server registry. ├── permissions-config.json ← AUTO-MANAGED. Per-folder "Yes, always" approvals — never edit by hand. ├── m-settings.json ← MANAGED. Auto-rewritten by the runtime. Do NOT edit. ├── m-mcp-servers.json ← MANAGED. Auto-rewritten. Do NOT edit. ├── m-preferences.json ← MANAGED. Do NOT edit. ├── skills/<skill-name>/ ← USER-SCOPE skills (this catalog's recommended install location). ├── installed-plugins/ ← Plugin cache (filled by `copilot plugin install …`). ├── session-state/<session-id>/← Per-session workspace (plan.md, checkpoints, files). └── session-store.db ← SQLite cross-session history (queryable). ``` The two files this skill writes are **`settings.json`** and **`mcp-config.json`**. Everything else is either auto-managed by the runtime or per-skill / per-session state. --- ## Quick start (5 minutes, no API keys needed) The minimum viable setup uses the three no-auth MCP servers (`mslearn`, `Azure`, `Playwright`). Drop this into `~/.copilot/mcp-config.json`: ```json { "mcpServers": { "mslearn": { "type": "http", "url": "https://learn.microsoft.com/api/mcp", "tools": ["*"], "headers": {} }, "Azure": { "type": "local", "command": "npx", "args": ["-y", "@azure/mcp@latest", "server", "start"], "tools": ["*"] }, "Playwright": { "type": "local", "command": "cmd", "args": ["/c", "npx", "-y", "@playwright/mcp@0.0.42", "--isolated", "--headless"], "tools": ["*"] } } } ``` The full version (with `context7` / `tavily` / `mem0` and placeholder keys) is in [`references/mcp-config.full.json`](references/mcp-config.full.json). Restart `copilot` after editing `mcp-config.json`. Verify with `/mcp` inside the session — the three servers should appear. > **`cmd /c` on Windows is intentional for Playwright.** `npx.cmd` isn't > always on PATH the way the runtime expects; wrapping in `cmd /c` makes > the launch reliable across PowerShell hosts. On macOS / Linux drop the > `cmd /c` prefix and call `npx` directly. --- ## Recommended MCP servers (the GBB six) | Server | Type | Auth | Why it's worth installing | |--------|------|------|--------------------------| | **mslearn** | HTTP | None | Two tools: `microsoft_docs_search` + `microsoft_docs_fetch`. Pulls authoritative Microsoft docs (Foundry, Azure, M365, .NET) directly into context. Drastically reduces hallucinated API surface. **Highest-ROI of the six.** | | **Azure** | Local stdio | `az login` | Resource management via natural language ("list my container apps in rg-foo"). Honors `AZURE_CONFIG_DIR` if set per shell — pairs cleanly with `azure-tenant-isolation`. | | **Playwright** | Local stdio | None | Headless browser automation, screenshots, page extraction, demo recording. The `--isolated` flag uses an ephemeral profile (no cookie leakage between sessions). | | **context7** | HTTP | API key | Library docs lookup (`resolve-library-id` → `get-library-docs`). Best for "what's the latest API of `@azure/identity`?" without web-fetching. Free tier sufficient for normal use. | | **tavily** | HTTP | API key | Web search alternative to fetch — better for "find articles about X" style queries that need ranked results. Free tier sufficient. | | **mem0** | Local stdio (Python) | API key | Long-term memory across sessions (separate from per-session `m_remember` and the SQL `session-store.db`). Useful for personal preferences that should follow you across all repos. | ### Per-server snippets #### mslearn (no auth) ```json "mslearn": { "type": "http", "url": "https://learn.microsoft.com/api/mcp", "tools": ["*"], "headers": {} } ``` When working on Foundry / Azure / M365, **invoke `mslearn` BEFORE falling back to web fetches**. The signal-to-noise is higher and the agent gets the canonical doc URL for citation. #### Azure (no auth — uses `az login` token cache) ```json "Azure": { "type": "local", "command": "npx", "args": ["-y", "@azure/mcp@latest", "server", "start"], "tools": ["*"] } ``` This server reads the same token cache as `az` CLI. **If you use `AZURE_CONFIG_DIR` per terminal (per `azure-tenant-isolation`), the Copilot CLI process must inherit that env var** — set it before launching `copilot`, not inside the session. #### Playwright (no auth, headless + isolated) ```json "Playwright": { "type": "local", "command": "cmd", "args": ["/c", "npx", "-y", "@playwright/mcp@0.0.42", "--isolated", "--headless"], "tools": ["*"] } ``` `--isolated` = ephemeral browser profile per session (no cookies kept). `--headless` = no visible browser window. Drop both flags if you want to watch the agent click through. #### context7 (API key required) ```json "context7": { "type": "http", "url": "https://mcp.context7.com/mcp", "tools": ["*"], "headers": { "CONTEXT7_API_KEY": "<your-context7-api-key>" } } ``` Get a free key at <https://context7.com/>. Use it when the agent needs library API surface that isn't well-covered by `mslearn` (anything non-Microsoft: `react-query`, `playwright-python`, `pandas`, etc.). #### tavily (API key required) ```json "tavily": { "type": "http", "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-tavily-api-key>", "tools": ["*"], "headers": {} } ``` Free key at <https://tavily.com/>. Two tools: `tavily_search` (ranked results) and `tavily_extract` (full-page extraction with cleanup). #### mem0 (API key + Python install required) ```json "mem0": { "type": "local", "command": "python", "args": ["-m", "mem0_mcp_server.server"], "tools": ["*"], "env": { "MEM0_API_KEY": "<your-mem0-api-key>", "MEM0_DEFAULT_USER_ID": "default" } } ``` Install once: `pip install mem0-mcp-server`. Free key at <https://mem0.ai/>. Use sparingly — broad memory across all sessions can leak project context between unrelated work. The built-in `m_remember` / SQL `session-store.db` covers most needs. --- ## `settings.json` baseline Live at `~/.copilot/settings.json`. The keys most worth setting: ```json { "model": "claude-opus-4.7", "renderMarkdown": true, "showReasoning": false, "allowedUrls": [ "https://raw.githubusercontent.com", "https://docs.github.com" ], "sessionSync": [ { "origin": "*", "level": "user" } ], "trustedFolders": [ "<absolute-path-to-your-repos-root>", "<absolute-path-to-another-trusted-folder>" ], "extraKnownMarketplaces": { "copilot-plugins": { "source": { "source": "github", "repo": "github/copilot-plugins" } } }, "telemetryEnabled": true, "sessionRetentionDays": 90, "preventSleepEnabled": true } ``` Full example: [`references/settings.example.json`](references/settings.example.json). ### Key-by-key | Key | Recommended | Why | |-----|-------------|-----| | `model` | `claude-opus-4.7` (or `gpt-5.4` for faster turns) | Default model the agent runs on. Microsoft staff: `claude-opus-4.7-xhigh` is available with extra reasoning depth. Override per session with `/model`. | | `renderMarkdown` | `true` | Pretty-prints tool output that contains markdown. Off only if you want raw bytes. | | `showReasoning` | `false` | Hides the model's chain-of-thought scratchpad. Toggle to `true` when debugging odd agent behavior. | | `allowedUrls` | `raw.githubusercontent.com`, `docs.github.com` (+ `localhost:*` while developing) | Pre-approved URLs the agent can fetch without confirmation. Keep tight — every entry is a trust grant. | | `sessionSync` | `[{"origin": "*", "level": "user"}]` | **High-value.** Roams session history across machines via your GitHub account. `level: "user"` syncs at user scope (not per-repo). | | `trustedFolders` | absolute paths to your active repos | Suppresses the "trust this folder?" prompt when you cd in. Add only folders you actually own. | | `extraKnownMarketplaces` | `copilot-plugins` (everyone), `work-iq` (Microsoft only) | Enables `copilot plugin install <name>@<marketplace>` to resolve from these GitHub repos. | | `telemetryEnabled` | `true` | Helps the team improve the runtime. Set `false` only if your org policy requires it. | | `sessionRetentionDays` | `90` | How long session-state survives. Drop to 30 if disk is tight. | | `preventSleepEnabled` | `true` | Keeps the OS awake while a long-running agent task is in flight. Off on laptops on battery. | | `disabledSkills` | `[]` | Per-skill kill switch. Use to silence a noisy auto-trigger. | ### Microsoft staff: enable the work-iq marketplace Add to `extraKnownMarketplaces` and install three plugins: ```json "extraKnownMarketplaces": { "copilot-plugins": { "source": { "source": "github", "repo": "github/copilot-plugins" } }, "work-iq": { "source": { "source": "github", "repo": "microsoft/work-iq" } } } ``` ```bash copilot plugin install workiq@work-iq copilot plugin install microsoft-365-agents-toolkit@work-iq copilot plugin install workiq-productivity@work-iq ```