diff --git a/dtwo/.claude-plugin/plugin.json b/dtwo/.claude-plugin/plugin.json index 8f84a9d..219db18 100644 --- a/dtwo/.claude-plugin/plugin.json +++ b/dtwo/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dtwo", - "version": "1.3.2", + "version": "1.3.3", "description": "Manage Dtwo gateways, policies, and Rego with the Dtwo MCP server.", "author": { "name": "Dtwo", diff --git a/dtwo/.codex-plugin/plugin.json b/dtwo/.codex-plugin/plugin.json index 5ad050d..5fc7624 100644 --- a/dtwo/.codex-plugin/plugin.json +++ b/dtwo/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dtwo", - "version": "1.3.2", + "version": "1.3.3", "description": "Manage Dtwo gateways, policies, and Rego with the Dtwo MCP server.", "author": { "name": "Dtwo", diff --git a/dtwo/.cursor-plugin/plugin.json b/dtwo/.cursor-plugin/plugin.json index 4567c69..a622a38 100644 --- a/dtwo/.cursor-plugin/plugin.json +++ b/dtwo/.cursor-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dtwo", - "version": "1.3.2", + "version": "1.3.3", "description": "Manage Dtwo gateways, policies, and Rego with the Dtwo MCP server.", "author": { "name": "Dtwo", diff --git a/dtwo/skills/dtwo-gateway-config/SKILL.md b/dtwo/skills/dtwo-gateway-config/SKILL.md index d2be53e..cbf59bb 100644 --- a/dtwo/skills/dtwo-gateway-config/SKILL.md +++ b/dtwo/skills/dtwo-gateway-config/SKILL.md @@ -486,12 +486,31 @@ mcp_servers: - chat:write ``` +### Setup guides for specific servers + +The Dtwo docs have a setup guide for many MCP servers. Each one covers the vendor-side setup (an OAuth app or API key, and the gateway's callback URL registered with the vendor) and gives a ready-made `mcp_servers` entry. When the user asks to add a server, look for its guide before writing the entry: + +1. Fetch `https://docs.dtwo.ai/llms.txt`. It lists every guide as a Markdown link with a one-line description, for example `[Configure the HubSpot MCP Server](https://docs.dtwo.ai/docs/mcp-server-hubspot.md)`. Match the server or vendor the user named against the titles and descriptions; a product can sit under its vendor's guide, as Jira does under Atlassian. If more than one guide could fit, ask which. Use only links the list contains, and never build a guide URL from a server's name. +2. If there's a guide, fetch its `.md` link. Take `url`, `transport_type`, the authentication type, `scopes`, and the OAuth endpoints from the YAML entry in it. If it offers more than one route (OAuth or a token, a hosted server or a self-hosted one), ask which the user wants. +3. Give the user the guide's web page, which is the same link without `.md`, for the vendor-side steps. The rest of the guide (pasting the entry into the Hub, deploying) is what you do here with the tools, so point them at the vendor section only. +4. Where the guide says to register the gateway's OAuth callback URL, give the user the real value so they don't have to look it up: `callbackUrl` from `dtwo-get-gateway`, or `/oauth/callback` when that's empty. Use the same value for `redirect_uri`. A self-hosted gateway with no URL yet has no callback to register, so that step waits until its URL is set. + +The guides are written for someone pasting YAML into the Hub, so their placeholders are not config values, and the rules in this skill win where they differ: + +- A client secret, API key, or token (`""`, `""` and the like) becomes a Vault reference that is the whole field value, such as `client_secret: <>`. The user enters the value through the Hub link (see Secrets and the Vault), never in the chat. +- A client ID isn't secret, so ask the user for it once they've created the app. Never save a draft with any of the guide's `<…>` placeholders left in it: they deploy as literal text. +- Validate before saving, as always. If the validator rejects a field the guide uses, the validator is right; fix the entry and tell the user what changed. + +**No guide for the server.** Say so, give the user the guide for any MCP server, `https://docs.dtwo.ai/docs/mcp-server-custom`, which covers the vendor-side checks and how to tell which authentication type applies, and carry on with the URL, transport, and authentication they give you. + +**You can't fetch web pages.** Don't guess a guide's address. Give the user the guide index, `https://docs.dtwo.ai/docs/mcp-servers`, so they can open the one for their server, and carry on with the details they give you. + ## Configuration Workflow ### Editing Configuration 1. Fetch the current draft with `dtwo-get-gateway-config` -2. Edit the YAML (add/modify MCP servers, change gateway settings). Put every credential in as a Vault reference, and get the user a Hub link for any secret that isn't in the Vault yet (see Secrets and the Vault) +2. Edit the YAML (add/modify MCP servers, change gateway settings). For a new server, start from its Dtwo setup guide when there is one (see Setup guides for specific servers). Put every credential in as a Vault reference, and get the user a Hub link for any secret that isn't in the Vault yet (see Secrets and the Vault) 3. Validate with `dtwo-validate-gateway-config`, passing `gatewayUid`. It also lists the Vault entries the config uses and reports any that are missing 4. Save with `dtwo-save-gateway-draft-config` 5. Deploy with `dtwo-deploy-gateway` to test the draft configuration diff --git a/dtwo/skills/setup/SKILL.md b/dtwo/skills/setup/SKILL.md index a9a977d..b3e0b87 100644 --- a/dtwo/skills/setup/SKILL.md +++ b/dtwo/skills/setup/SKILL.md @@ -298,7 +298,9 @@ MCP servers are the tools the gateway fronts. Start with the fastest path, then For each one the user picks, add an `mcp_servers` entry with just three fields: `name`, `url` (the table URL), and `transport_type: streamable_http` (the value the Dtwo Hub writes for these same servers; the schema also accepts `streamablehttp`, `http`, and `sse`, and the underscore form and the one-word form reach the gateway identically). Do not add an `authentication` block at all. These are public, anonymous servers, so they need no authentication, and leaving the block off is deliberate: writing `authentication: type: none` tells the gateway to forward your access token to the upstream, which public servers reject and which needlessly exposes your token. Omitting authentication is optional in the schema and validates cleanly. Use a kebab-cased id as the entry `name` (`context7`, `deepwiki`, `microsoft-learn`, `hugging-face`, `cloudflare-docs`, `gitmcp`), matching the Dtwo Hub. -**Custom servers (anything else).** Any MCP server can go behind the gateway; this is the normal path for real usage. Collect its URL and transport from the user. When the upstream needs credentials, add an `authentication` block; the **dtwo-gateway-config** skill owns the supported types (bearer token, basic, custom headers, query parameter, OAuth, certificate) and how to author them, including how credentials go in. The short version: the config holds a Vault reference such as `<>`, and the user types the credential itself into the Dtwo Hub through a link you give them, never into the chat. Tell them the gateway can't deploy until that value is saved. For a public or no-auth upstream, omit the block entirely, the same as the quick-start entries above. One caveat to state plainly: some servers, for example Slack, GitHub, or Jira, assume the user has the right access and need extra configuration on the app side (OAuth apps, API tokens, workspace approval) before the gateway can reach them, so they take a few more steps than the quick-start list. +**Custom servers (anything else).** Any MCP server can go behind the gateway; this is the normal path for real usage. Start with Dtwo's setup guide for the server: fetch `https://docs.dtwo.ai/llms.txt` and match the server or vendor the user named against the guide titles and descriptions. When there's a guide, take the URL, transport, and authentication settings from its YAML entry, and give the user its web page (the link without `.md`) for the steps on the vendor's side, along with the gateway's actual callback URL to register there (Phase 3 covers what it is) rather than the guide's placeholder. When there isn't one, give them `https://docs.dtwo.ai/docs/mcp-server-custom`, the guide for any MCP server, and collect the URL and transport from them. If you can't fetch web pages, give them the guide index, `https://docs.dtwo.ai/docs/mcp-servers`, instead of guessing a guide's address. The **dtwo-gateway-config** skill has the full lookup. + +When the upstream needs credentials, add an `authentication` block; the **dtwo-gateway-config** skill owns the supported types (bearer token, basic, custom headers, query parameter, OAuth, certificate) and how to author them, including how credentials go in. The short version: the config holds a Vault reference such as `<>`, and the user types the credential itself into the Dtwo Hub through a link you give them, never into the chat. A guide's entry follows the same rule: its `""`-style placeholders become Vault references and never go into a saved config as text. Tell them the gateway can't deploy until that value is saved. For a public or no-auth upstream, omit the block entirely, the same as the quick-start entries above. One caveat to state plainly: many servers need setup on the vendor's side (an OAuth app, an API token, workspace approval) before the gateway can reach them, so they take a few more steps than the quick-start list. The server's guide covers that part. Offer to add more than one server, from either group. Load the **dtwo-gateway-config** skill and follow its flow to edit `mcp_servers`, then `dtwo-save-gateway-draft-config` + `dtwo-validate-gateway-config`. Do not restate the config schema here, that skill owns it (including transport type, outbound auth variants, and Vault references for credentials). If the user has no server in mind yet, it's fine to save an empty `mcp_servers` and add one later, but tell them the gateway won't front anything until a server is added.