diff --git a/skills/onboarding/SKILL.md b/skills/onboarding/SKILL.md index 1643fc7..1ce801b 100644 --- a/skills/onboarding/SKILL.md +++ b/skills/onboarding/SKILL.md @@ -159,12 +159,16 @@ Perform these in **order** in the **same assistant turn**, then proceed directly 2. **Roadmap:** Give the user a brief, friendly preview of what you are about to do. Keep it conversational -- a short paragraph or a compact list is fine. Do not render a large table by default (the table below is your internal reference). The user should understand the arc (explore the project, set up tooling, install the SDK, create a first flag) without seeing step numbers or internal labels. 3. **Begin Steps 0-3 immediately.** These steps do not require a LaunchDarkly account or any user action. Run them in the background and surface only the results: what you found (language, framework, agent) and what you installed (companion skills). Do not narrate each step as a separate heading -- summarize them together when presenting findings to the user. Account status is inferred later (see [Prerequisites](#prerequisites)). -- **Resuming:** If `LAUNCHDARKLY_ONBOARDING.md` already exists, read it first per [Steps 0-3](#steps-0-3-setup-run-silently----do-not-narrate-each-step). Show a shorter "where we are" summary. Refresh the task list to match the log; continue from the log's **Next step**. +- **Resuming:** When the user says "continue LaunchDarkly onboarding" (or similar), **always check for `LAUNCHDARKLY_ONBOARDING.md` first**. If it exists: + 1. Read the log to understand current state (completed steps, blockers, next step) + 2. Show a brief "where we are" summary (e.g. "I see we finished MCP setup — next is SDK installation") + 3. Refresh your task list to match the log's checklist + 4. Continue from the log's **Next step** — do not restart from Step 0 | Step | What happens | You get | |------|--------------|---------| | **0-3** -- Setup | Create onboarding log, explore project, detect agent, install companion skills (`npx skills add` from `launchdarkly/ai-tooling`) | Stack summary, agent ID, `launchdarkly-flag-*` skills available | -| **4** -- MCP | Configure LaunchDarkly MCP; user restarts; agent auto-verifies on next turn | MCP tools (or ldcli/API fallback); account confirmed via OAuth | +| **4** -- MCP | Configure LaunchDarkly MCP; user enables server; agent probes for tools | MCP tools (or ldcli/API fallback); account confirmed via OAuth | | **5** -- SDK install | detect -> plan -> apply ([sdk-install](sdk-install/SKILL.md)) | Packages + init wired to env vars | | **6** -- First flag | Create boolean flag, evaluate, toggle, add interactive demo ([first-flag](first-flag/SKILL.md)) | End-to-end proof + visible "wow" moment | | **Follow-through** | `LAUNCHDARKLY.md`, editor rules ([1.8-summary](references/1.8-summary.md), [1.9-editor-rules](references/1.9-editor-rules.md)) | Durable docs for the repo | @@ -232,9 +236,9 @@ Replace `` with the value from Step 2. Confirm success; skip ski Hand off to [mcp-configure/SKILL.md](mcp-configure/SKILL.md) for setup (hosted MCP, quick install, manual JSON, agent authorization). -MCP setup requires the user to act outside the agent (clicking a quick-install link, completing OAuth, enabling the server in editor settings). After presenting the instructions, **tell the user to restart or refresh the agent** so MCP tools become available. Then continue to Step 5 — do not block here with a confirmation question. +MCP setup requires the user to act outside the agent (clicking a quick-install link, completing OAuth, enabling the server in editor settings). After presenting the instructions, **tell the user to enable the server and complete OAuth**. Then probe for MCP tools immediately — a restart may not be required in Cursor or Claude Code. -**Auto-verify on next turn:** When the conversation resumes (after the user restarts or sends a message), probe for MCP by calling a lightweight MCP tool such as `list-feature-flags` with the known project key. If the tool responds normally, MCP is live — note it in the onboarding log and use MCP tools for later steps. If the call fails or no MCP tools are visible, fall back silently to ldcli/API for Steps 5-6 and note the fallback in the onboarding log. **Do not ask** the user whether MCP is working — find out by trying it. +**Auto-verify:** After the user confirms they've enabled the server, probe for MCP by calling a lightweight MCP tool such as `list-feature-flags` with the known project key. If the tool responds normally, MCP is live — note it in the onboarding log and use MCP tools for later steps. If the call fails or no MCP tools are visible, **update the onboarding log first** (so a new session can resume), then suggest a restart with clear instructions: tell the user to say **"continue LaunchDarkly onboarding"** when they come back. If restart doesn't help, fall back to ldcli/API for Steps 5-6 and note the fallback in the onboarding log. **Do not ask** the user whether MCP is working — find out by trying it. Do not duplicate MCP procedures in this file. Do not block Step 5 indefinitely on MCP. diff --git a/skills/onboarding/mcp-configure/SKILL.md b/skills/onboarding/mcp-configure/SKILL.md index ccc4b32..803eb37 100644 --- a/skills/onboarding/mcp-configure/SKILL.md +++ b/skills/onboarding/mcp-configure/SKILL.md @@ -19,14 +19,13 @@ This skill is nested under [LaunchDarkly onboarding](../SKILL.md); the parent sk - A LaunchDarkly account (sign up at the resolved signup URL — see [Source Attribution](../SKILL.md#source-attribution) in the parent skill; default: `https://app.launchdarkly.com/signup?source=agent`) - An MCP-compatible coding agent -## Hosted MCP Servers +## Hosted MCP Server -LaunchDarkly provides two hosted MCP servers. For onboarding, only the feature management server is required. +LaunchDarkly provides a unified hosted MCP server that handles feature management, AgentControl, and other LaunchDarkly capabilities. -| Server | URL | Purpose | -| ------------------ | -------------------------------------------- | -------------------- | -| Feature management | `https://mcp.launchdarkly.com/mcp/fm` | Manage feature flags | -| AI Configs | `https://mcp.launchdarkly.com/mcp/aiconfigs` | Manage AI Configs | +| Server | URL | Purpose | +| ----------- | ------------------------------------------------ | -------------------------------------------- | +| LaunchDarkly | `https://mcp.launchdarkly.com/mcp/launchdarkly` | Feature flags, AgentControl, and more | ## Workflow @@ -38,9 +37,7 @@ If the parent onboarding skill already identified the agent, use that context. O The fastest path is the quick install link. Present it to the user: -**Feature management:** [https://mcp.launchdarkly.com/mcp/fm/install](https://mcp.launchdarkly.com/mcp/fm/install) - -**AI Configs (optional):** [https://mcp.launchdarkly.com/mcp/aiconfigs/install](https://mcp.launchdarkly.com/mcp/aiconfigs/install) +**LaunchDarkly MCP:** [https://mcp.launchdarkly.com/mcp/launchdarkly/install](https://mcp.launchdarkly.com/mcp/launchdarkly/install) **Important: tell the user what to expect after clicking the link.** The install link may open in the browser, but the authorization or "add server" prompt typically appears **back in the coding environment** (the editor or host app where the agent runs), not in the browser. Immediately after presenting the link, include guidance like: @@ -61,7 +58,7 @@ Locate the MCP config file for the detected agent and add the hosted server entr | GitHub Copilot | Repo **Settings** on GitHub.com → Copilot → Cloud agent → MCP (see [MCP UI links](references/mcp-ui-links.md)) | | Windsurf | Agent-specific MCP config | -**Only add the feature management server for onboarding.** Add the AI Configs server only if the user explicitly needs it. +The unified server handles both feature management and AgentControl, so only one server entry is needed. ### Step 4: Agent-Specific Authorization @@ -70,7 +67,7 @@ After writing the config, some agents need extra steps. **Do not** send users th **Cursor:** 1. Open MCP in Cursor using the [Cursor MCP doc link and in-app shortcuts](references/mcp-ui-links.md#clients) (e.g. Settings search via `command:` link when clickable). -2. Toggle on **LaunchDarkly feature management** (or the name from your config). +2. Toggle on **LaunchDarkly** (or the name from your config). 3. Click **Connect** to authorize with the LaunchDarkly account. **VS Code (when applicable):** @@ -85,15 +82,16 @@ After writing the config, some agents need extra steps. **Do not** send users th - Click **Save** after adding the MCP configuration in repo settings. Use the [GitHub Copilot MCP doc](https://docs.github.com/en/copilot/customizing-copilot/extending-copilot-coding-agent-with-mcp) for the exact **Settings** path on github.com. -### Step 5: Restart and Auto-Verify +### Step 5: Enable and Verify -MCP tools are only available to the agent after a restart or refresh — newly added MCP servers do not appear mid-session. +After adding the config, the user needs to enable and authorize the server. MCP tools may become available immediately in some agents (Cursor, Claude Code) without a restart. -1. **Tell the user to enable the server and restart.** Before restarting, they need to make sure the MCP server is toggled on and authorized in their editor's MCP settings (e.g. in Cursor: toggle on the LaunchDarkly server and click **Connect**). Then restart or refresh the agent — be specific about how: "Restart Cursor" / "reload Claude Code" / "refresh the Copilot agent" depending on what you detected in Step 1. After the user restarts, the conversation will resume in a new turn. -2. **On the next turn, probe silently.** Call a lightweight MCP tool (e.g. `list-feature-flags` with the user's project key). Do not ask the user whether MCP is working — just try it. +1. **Tell the user to enable the server.** They need to toggle on the LaunchDarkly server and complete OAuth in their editor's MCP settings (e.g. in Cursor: toggle on the server and click **Connect**). +2. **Probe immediately.** After the user confirms they've enabled the server, call a lightweight MCP tool (e.g. `list-feature-flags` with the known project key). Do not ask the user whether MCP is working — just try it. - **Success** (normal response, even an empty flag list): MCP is live. Note it in the onboarding log and continue. - - **Failure** (tool not found, auth error, timeout): fall back to ldcli/API. Note the fallback in the onboarding log. Do **not** block the rest of onboarding — Steps 5-6 must still be completable without MCP. -3. **If the probe fails**, briefly tell the user MCP isn't available yet and that you'll use ldcli/API instead. Offer a one-liner they can try later to re-enable MCP (e.g. "You can set up MCP anytime by clicking [quick install link] and restarting"). + - **Failure** (tool not found, auth error, timeout): **update the onboarding log first** (set Step 4 to "in progress - pending restart", Next step to "Step 4: Verify MCP after restart"), then suggest a restart with clear resume instructions: + > "MCP tools aren't available yet. Try restarting your editor. When you come back, just say **'continue LaunchDarkly onboarding'** — I'll pick up where we left off using the onboarding log." +3. **If restart doesn't help**, fall back to ldcli/API for Steps 5-6. Note the fallback in the onboarding log. Do **not** block the rest of onboarding. 4. If the failure looks like a config issue (wrong file path, missing OAuth, server not enabled), mention the likely cause so the user can fix it on their own time — but do not block progress. For **local `npx` server** verification, see [MCP Config Templates — Verify (local server)](references/mcp-config-templates.md#verify-local-server). @@ -119,27 +117,38 @@ Then ask how they want to add the token to the MCP config: 1. Tell them the config file path for their agent (see [MCP Config Templates](references/mcp-config-templates.md)) 2. Tell them to set `LAUNCHDARKLY_ACCESS_TOKEN` as the value — either as an environment variable or directly in the config file 3. Remind them to add the config file to `.gitignore` if the token is inline -4. Wait for them to confirm, then proceed to Step 5 (Restart and Auto-Verify) +4. Wait for them to confirm, then proceed to Step 5 (Enable and Verify) **If the user wants agent-assisted setup:** 1. Ensure the config file is in `.gitignore` before writing 2. Write the config per [MCP Config Templates](references/mcp-config-templates.md) 3. Remind the user that the token will be visible in the config file and conversation history -4. Proceed to Step 5 (Restart and Auto-Verify) +4. Proceed to Step 5 (Enable and Verify) ## Edge Cases -- **User already has MCP configured:** Verify by checking for existing LD MCP entries in the config. If present and working, skip configuration. -- **User has the old npx-based local server:** Migrate them. Remove the old `npx @launchdarkly/mcp-server` entry and any `LD_ACCESS_TOKEN` env vars. Replace with the hosted server config. +- **User already has MCP configured:** Verify by checking for existing LD MCP entries in the config. + - `mcp/launchdarkly` or `mcp/fm` → working, skip configuration (both point to the unified server) + - `mcp/aiconfigs` → deprecated, ask before migrating: + + **D-MIGRATE -- BLOCKING:** Call your structured question tool now. + - question: "I see you have the old AgentControl MCP server configured (`mcp/aiconfigs`). That endpoint is deprecated — the unified server at `mcp/launchdarkly` now handles both feature management and AgentControl. Want me to update your config?" + - options: + - "Yes, update my config to use the unified server" + - "No, leave it as is for now" + - STOP. Do not modify the MCP config before the user selects an option. + + If they agree, remove the `mcp/aiconfigs` entry and ensure the unified `mcp/launchdarkly` (or `mcp/fm`) config is present. See [MCP Config Templates](references/mcp-config-templates.md). If they decline, note the deprecation and continue. +- **User has the old npx-based local server:** Migrate them. Remove the old `npx @launchdarkly/mcp-server` entry and any `LD_ACCESS_TOKEN` env vars. Replace with the hosted server config. See [MCP Config Templates — Migration](references/mcp-config-templates.md#migrating-from-old-configurations). - **Federal or EU instances:** The hosted MCP server is not available for federal or EU environments. Use [local MCP server docs](https://launchdarkly.com/docs/home/getting-started/mcp-local) and the **Local server via `npx`** section in [MCP Config Templates](references/mcp-config-templates.md). Follow the [Local MCP: Access Token Setup](#local-mcp-access-token-setup) flow for token handling. -- **Agent not in known list:** Provide the generic pattern: the user needs to add an MCP server entry pointing to `https://mcp.launchdarkly.com/mcp/fm` using whatever format their agent expects. +- **Agent not in known list:** Provide the generic pattern: the user needs to add an MCP server entry pointing to `https://mcp.launchdarkly.com/mcp/launchdarkly` using whatever format their agent expects. - **User opts out of MCP during onboarding:** Document that choice and continue with the parent skill's ldcli/API fallbacks for environments and flags; do not block SDK work. ## What NOT to Do - Don't configure the old npx-based local server by default. Prefer the hosted server for standard regions. - Don't ask for or store API keys for the hosted server. The hosted server uses OAuth. -- Don't add both servers by default. Only add AI Configs if the user asks for it. +- Don't configure the old separate FM/AgentControl servers. Use the unified `mcp/launchdarkly` server. - Don't handle the access token for local MCP without asking the user first via the D4-LOCAL decision point. ## References diff --git a/skills/onboarding/mcp-configure/references/mcp-config-templates.md b/skills/onboarding/mcp-configure/references/mcp-config-templates.md index e4f462a..484ebbb 100644 --- a/skills/onboarding/mcp-configure/references/mcp-config-templates.md +++ b/skills/onboarding/mcp-configure/references/mcp-config-templates.md @@ -1,6 +1,6 @@ # MCP Config Templates -Per-agent JSON snippets for configuring the LaunchDarkly hosted MCP server. All configurations use OAuth -- no API keys required. +Per-agent JSON snippets for configuring the LaunchDarkly hosted MCP server. All configurations use OAuth — no API keys required. Source: https://launchdarkly.com/docs/home/getting-started/mcp-hosted @@ -8,67 +8,29 @@ Source: https://launchdarkly.com/docs/home/getting-started/mcp-hosted Config file: `.cursor/mcp.json` in the project root. -### Feature management only - -```json -{ - "mcpServers": { - "LaunchDarkly feature management": { - "url": "https://mcp.launchdarkly.com/mcp/fm", - "headers": {} - } - } -} -``` - -### Both servers - ```json { "mcpServers": { - "LaunchDarkly feature management": { - "url": "https://mcp.launchdarkly.com/mcp/fm", - "headers": {} - }, - "LaunchDarkly AI Configs": { - "url": "https://mcp.launchdarkly.com/mcp/aiconfigs", + "LaunchDarkly": { + "url": "https://mcp.launchdarkly.com/mcp/launchdarkly", "headers": {} } } } ``` -**After adding the config:** enable the servers and complete OAuth in Cursor's MCP UI. Use [MCP UI links — Cursor](mcp-ui-links.md#clients) (HTTPS doc + optional `command:` links); do not rely only on nested Settings menu paths. +**After adding the config:** enable the server and complete OAuth in Cursor's MCP UI. Use [MCP UI links — Cursor](mcp-ui-links.md#clients) (HTTPS doc + optional `command:` links); do not rely only on nested Settings menu paths. ## Claude Code Config file: `.mcp.json` in the project root, or `~/.claude.json` for global config. -### Feature management only - ```json { "mcpServers": { - "LaunchDarkly feature management": { - "type": "http", - "url": "https://mcp.launchdarkly.com/mcp/fm" - } - } -} -``` - -### Both servers - -```json -{ - "mcpServers": { - "LaunchDarkly feature management": { - "type": "http", - "url": "https://mcp.launchdarkly.com/mcp/fm" - }, - "LaunchDarkly AI Configs": { + "LaunchDarkly": { "type": "http", - "url": "https://mcp.launchdarkly.com/mcp/aiconfigs" + "url": "https://mcp.launchdarkly.com/mcp/launchdarkly" } } } @@ -87,8 +49,8 @@ Configured via the GitHub web UI, not a local config file. ```json { "mcpServers": { - "LaunchDarkly feature management": { - "url": "https://mcp.launchdarkly.com/mcp/fm", + "LaunchDarkly": { + "url": "https://mcp.launchdarkly.com/mcp/launchdarkly", "headers": {} } } @@ -104,8 +66,8 @@ Windsurf uses a similar MCP configuration format. Add to the agent's MCP config: ```json { "mcpServers": { - "LaunchDarkly feature management": { - "url": "https://mcp.launchdarkly.com/mcp/fm" + "LaunchDarkly": { + "url": "https://mcp.launchdarkly.com/mcp/launchdarkly" } } } @@ -113,7 +75,9 @@ Windsurf uses a similar MCP configuration format. Add to the agent's MCP config: Consult Windsurf's documentation for the exact config file location. -## Migrating from the Old Local Server +## Migrating from Old Configurations + +### From the old local npx-based server If the user has the old npx-based server configured, replace it: @@ -138,6 +102,27 @@ If the user has the old npx-based server configured, replace it: Also remove any `LD_ACCESS_TOKEN` or `LAUNCHDARKLY_API_KEY` environment variables that were used for the local server. The hosted server handles authentication via OAuth. +### From the deprecated AgentControl server + +The `mcp/aiconfigs` endpoint is deprecated. The unified server (`mcp/launchdarkly`) and its mirror (`mcp/fm`) both handle AgentControl now. + +If the user has `mcp/aiconfigs` configured, **ask before removing** — see the edge case flow in [SKILL.md](../SKILL.md#edge-cases). The user should confirm the migration. + +**Entry to remove (after user confirms):** + +```json +{ + "mcpServers": { + "LaunchDarkly AgentControl": { + "url": "https://mcp.launchdarkly.com/mcp/aiconfigs", + "headers": {} + } + } +} +``` + +**Ensure the unified server is present** (see sections above). If they already have `mcp/fm` configured, that works — it mirrors `mcp/launchdarkly`. + ## Local server via `npx` Use the local MCP server when hosted MCP is not available — for example, **EU or Federal** environments — or when your setup requires it. See [local MCP server docs](https://launchdarkly.com/docs/home/getting-started/mcp-local). This path uses **`LAUNCHDARKLY_ACCESS_TOKEN`** (API access token) instead of OAuth. @@ -228,9 +213,9 @@ Claude Desktop config is user-level (not in repos), so token exposure risk is lo } ``` -Replace `YOUR_ACCESS_TOKEN` with the user’s LaunchDarkly API access token. After editing, restart the editor or reload MCP. +Replace `YOUR_ACCESS_TOKEN` with the user’s LaunchDarkly API access token. After editing, enable the server in the editor's MCP settings. A restart may be required if tools don't appear. ### Verify (local server) 1. If you have MCP tool access, call **`list-feature-flags`** with the user’s `projectKey` (e.g. `request: { "projectKey": "YOUR_PROJECT_KEY" }`). A normal response confirms the server and token. -2. If MCP tools are not visible yet, have the user run **`ldcli flags list`** (or curl the REST API) to validate credentials independently while MCP reloads. +2. If MCP tools are not visible yet, have the user run **`ldcli flags list`** (or curl the REST API) to validate credentials independently while waiting for MCP tools to appear.