feat: dual Make-CLI/MCP interface support#16
Open
JanKulhavy wants to merge 39 commits into
Open
Conversation
Designs how skills support both the Make CLI (preferred for shell-capable agents) and the Make MCP server (fallback; required for Claude Desktop and claude.ai). Renames make-mcp-reference to make-interface-reference, introduces variant markers for build-time ZIP stripping, and keeps a single source tree. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
17-task plan: stripper script with TDD, skill rename, content rewrites, preamble insertion, build integration, verification, and v0.2.0 bump. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Rename dist/make-mcp-reference.zip → dist/make-interface-reference.zip - Rebuild all skill ZIPs with CLI content stripped via variants stripper - Bundle rebuilt with stripped skill contents Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…CLAUDE.md ref count - SKILL.md metadata version 0.2.0 → 0.1.3 (matches plugin/package/other skills) - CLAUDE.md structure comment "3 reference files" → "4" (cli/mcp install, mapping, transport) - Rebuild dist/ ZIPs to reflect corrected version Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds dual-interface documentation and packaging support so the Make skills can be used via Make CLI when shell access is available, and via the Make MCP server otherwise. It also renames the reference skill to cover both interfaces and introduces a build-time “variant stripping” step to produce MCP-only ZIP downloads.
Changes:
- Introduce
make-interface-referenceskill (renamed/reworked reference) with new CLI/MCP reference docs and tool mapping. - Add
<!-- variant:cli-* -->/<!-- variant:mcp-only-* -->markers and a newscripts/strip-variants.shto generate MCP-only ZIPs duringbuild.sh. - Update README/CLAUDE/docs/config metadata to describe and route users to the correct interface and downloads.
Reviewed changes
Copilot reviewed 24 out of 31 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/make-scenario-building/SKILL.md | Adds “Interface: CLI or MCP” preamble + updates related-skill link to make-interface-reference. |
| skills/make-module-configuring/SKILL.md | Adds “Interface: CLI or MCP” preamble + updates related-skill link to make-interface-reference. |
| skills/make-interface-reference/SKILL.md | New dual-interface reference skill (CLI detection, MCP reference links, troubleshooting, resources). |
| skills/make-interface-reference/references/cli-install-and-auth.md | New CLI install/auth reference (intended to be stripped from MCP-only ZIPs). |
| skills/make-interface-reference/references/mcp-install-and-auth.md | Extracted MCP install/auth/scopes/access-control/timeout reference. |
| skills/make-interface-reference/references/tool-invocation-mapping.md | MCP tool ↔ CLI command mapping table and CLI parameter-passing patterns. |
| skills/make-interface-reference/references/transport-details.md | Transport details reference (URL patterns, suffixes, zones, timeouts guidance). |
| scripts/strip-variants.sh | New build-time stripper to remove CLI blocks and delete references/cli-*.md files. |
| scripts/test-strip-variants.sh | Test harness + fixtures validation for the stripper. |
| scripts/fixtures/strip-variants/balanced-input/skills/example/SKILL.md | Balanced marker fixture for stripper tests. |
| scripts/fixtures/strip-variants/balanced-input/skills/example/references/cli-intro.md | CLI reference fixture expected to be deleted by stripper. |
| scripts/fixtures/strip-variants/balanced-input/skills/example/references/mcp-intro.md | MCP reference fixture expected to remain after stripping. |
| scripts/fixtures/strip-variants/unbalanced-input/skills/example/SKILL.md | Unbalanced marker fixture expected to fail stripping. |
| build.sh | Integrates stripping step before zipping skills/bundle; updates skill list to make-interface-reference. |
| README.md | Adds Interfaces section, CLI + MCP setup sections, and updates download links to the renamed reference ZIP. |
| CLAUDE.md | Documents dual-interface positioning + build variants/markers and release steps. |
| index.html | Updates download URL for the renamed reference ZIP (label/count text not updated). |
| package.json | Updates description/keywords/version and switches agents.skills entry to make-interface-reference. |
| package-lock.json | Updates lockfile package version metadata to 0.1.3. |
| .versionrc.json | Updates SKILL.md bumpFile path from make-mcp-reference to make-interface-reference. |
| .claude-plugin/plugin.json | Updates plugin version/description for dual-interface positioning. |
| .claude-plugin/marketplace.json | Updates marketplace descriptions/version for dual-interface positioning. |
| CHANGELOG.md | Adds 0.1.3 changelog section (as included in this PR). |
| docs/superpowers/specs/2026-04-20-dual-cli-mcp-interface-design.md | Adds design spec for dual CLI/MCP approach and variant stripping. |
| docs/superpowers/plans/2026-04-20-dual-cli-mcp-interface.md | Adds detailed implementation plan for dual-interface and build variants. |
| docs/superpowers/plans/2026-04-12-open-agent-skills-compatibility.md | Adds prior compatibility plan (referenced/superseded by the new spec/plan). |
| dist/make-interface-reference.zip | Updated built artifact ZIP (MCP-only stripped variant). |
| dist/make-module-configuring.zip | Updated built artifact ZIP. |
| dist/make-scenario-building.zip | Updated built artifact ZIP. |
| dist/make-skills.zip | Updated built bundle ZIP. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…strip-variants script
…erface # Conflicts: # .claude-plugin/marketplace.json # .claude-plugin/plugin.json # dist/make-mcp-reference.zip # dist/make-module-configuring.zip # dist/make-scenario-building.zip # dist/make-skills.zip # package.json # skills/make-interface-reference/references/mcp-install-and-auth.md
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 23 out of 29 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…strip-variants script
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 28 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
skills/make-interface-reference/references/mcp-install-and-auth.md:61
- In this doc, the token auth section states the endpoint as
.../mcp/u/<MCP_TOKEN>/stateless, but the Claude Code configuration example uses the suffix-less.../mcp/u/<MCP_TOKEN>URL. Since both forms are presented as the “endpoint”, this is ambiguous for readers; please make the endpoint and example consistent (either both suffix-less with a note that it defaults to stateless, or both explicitly/stateless).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…kers and file deletion
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 28 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 28 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (1)
skills/make-interface-reference/references/mcp-install-and-auth.md:62
- In the MCP token section, the doc declares the token endpoint as requiring
/stateless("Endpoint:https://<MAKE_ZONE>/mcp/u/<MCP_TOKEN>/stateless"), but the Claude Code configuration example immediately below uses the suffix-less URLhttps://<MAKE_ZONE>/mcp/u/<MCP_TOKEN>. Since users will copy-paste the snippet, this mismatch is likely to confuse; either make the example use the explicit/statelessform, or add a one-line note here that omitting the suffix defaults to stateless (and is equivalent).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 22 out of 28 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…examples to CLI documentation
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 24 out of 30 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Four interface docs claimed every MCP tool has a matching CLI subcommand, contradicting cli-tool-invocation-mapping.md which defines three tiers (direct CLI, REST curl fallback, no CLI path). Reworded to reflect the subset + fallback reality and point readers at the mapping for the current tier breakdown. Resolves PR #16 review comments from @copilot-pull-request-reviewer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
strip-variants.sh scanned only SKILL.md for <!-- variant:cli-* --> and <!-- variant:mcp-only-* --> markers, so a CLI-only block added to skills/make-module-configuring/general-principles.md leaked unstripped into MCP-only ZIPs for Claude Desktop / claude.ai. Widened both the balance-check and strip loops from -name 'SKILL.md' to -type f -name '*.md'. Extended the balanced-input fixture with a CLI block inside references/mcp-intro.md plus three assertions covering strip + marker removal + surrounding-content preservation. Resolves PR #16 review comments from @copilot-pull-request-reviewer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 24 out of 30 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **Never create connections directly.** Always use credential requests. The agent should never ask the user for API keys, tokens, or passwords directly — the credential request flow handles credential entry securely. | ||
| - **Scope mismatches cause runtime failures.** A connection that authenticates successfully but lacks a required scope will fail with 403/permission errors when the module tries to perform a scoped operation. Always verify scopes match what Extract Blueprint Components specifies. | ||
| - **Scope mismatches cause runtime failures.** A connection that authenticates successfully and passes `connections_verify` can still be missing scopes — it just can't call the protected endpoints. The failure surfaces at runtime as `403 insufficient scopes` inside the affected module. Always re-read the connection's `scopes` array immediately after authorization and confirm every requested scope is present. | ||
| - **Google consent screens silently drop scopes.** On Google's OAuth consent screen each scope is a separate checkbox, and users can uncheck individual scopes before clicking Continue. The connection is then created with partial scopes and no warning. When asking the user to authorize, explicitly tell them to leave every checkbox enabled, and always verify scopes afterwards (see Step 3b.4). |
There was a problem hiding this comment.
The note references “Step 3b.4”, but the surrounding section doesn’t use a 3b.1/3b.2… numbering scheme—within Step 3b the items are numbered 1–5. This cross-reference is currently broken; please update it to point to the correct step/item (or adjust the numbering to match the reference).
Suggested change
| - **Google consent screens silently drop scopes.** On Google's OAuth consent screen each scope is a separate checkbox, and users can uncheck individual scopes before clicking Continue. The connection is then created with partial scopes and no warning. When asking the user to authorize, explicitly tell them to leave every checkbox enabled, and always verify scopes afterwards (see Step 3b.4). | |
| - **Google consent screens silently drop scopes.** On Google's OAuth consent screen each scope is a separate checkbox, and users can uncheck individual scopes before clicking Continue. The connection is then created with partial scopes and no warning. When asking the user to authorize, explicitly tell them to leave every checkbox enabled, and always verify scopes afterwards (see Step 3b, item 4). |
| - **Make CLI** (recommended) — `brew install integromat/tap/make-cli` then `make-cli login`. Works with any agent that has shell/Bash access (Claude Code, Cursor, Windsurf, Cline, …). | ||
| - **Make MCP server** — configure `https://mcp.make.com` in the agent. Required for agents without shell access (Claude Desktop, claude.ai). | ||
|
|
||
| Both expose the same tool set — the CLI is generated from the same `MakeMCPTools` SDK definition that backs the MCP server. See the `make-interface-reference` skill for detection order, install, and syntax mapping. |
There was a problem hiding this comment.
This line says “Both expose the same tool set”, but elsewhere in this PR (e.g., the interface reference) it’s stated that the CLI wraps only a subset of MCP tools and sometimes requires REST/curl fallbacks. Please reword this to avoid implying full one-to-one CLI coverage.
Suggested change
| Both expose the same tool set — the CLI is generated from the same `MakeMCPTools` SDK definition that backs the MCP server. See the `make-interface-reference` skill for detection order, install, and syntax mapping. | |
| Both are based on the same `MakeMCPTools` SDK definitions, but the CLI wraps only a subset of the MCP tools and some workflows may still require REST/curl fallbacks. See the `make-interface-reference` skill for detection order, install, and syntax mapping. |
| **If the MCP server isn't connected and the agent has shell access, check for the CLI.** Run `command -v make-cli` (Bash). | ||
|
|
||
| - Found? Run `make-cli whoami` to verify authentication. | ||
| - Success → use the **CLI path** for this session — it avoids a network round-trip per call. Consult `references/cli-tool-invocation-mapping.md` when a tool isn't wrapped as a direct subcommand. |
There was a problem hiding this comment.
The CLI path is described as “avoid[ing] a network round-trip per call”, but make-cli still calls Make’s APIs over the network; it mainly avoids routing calls through the hosted MCP server / MCP tool invocation layer. Suggest rephrasing to something like reduced MCP overhead / local invocation, to avoid implying offline operation.
Suggested change
| - Success → use the **CLI path** for this session — it avoids a network round-trip per call. Consult `references/cli-tool-invocation-mapping.md` when a tool isn't wrapped as a direct subcommand. | |
| - Success → use the **CLI path** for this session — it uses local shell invocation and avoids the hosted MCP server / MCP tool-calling layer, which can reduce MCP overhead. Consult `references/cli-tool-invocation-mapping.md` when a tool isn't wrapped as a direct subcommand. |
Comment on lines
+76
to
+77
| # Check marker balance across all SKILL.md files. Fails fast on an end marker | ||
| # without a matching start so we catch malformed ordering, not just net counts. |
There was a problem hiding this comment.
The comment says this checks marker balance across all “SKILL.md” files, but the find below runs over all *.md files in the tree. Please update the comment to match what the script actually does (or restrict the find to SKILL.md if that was the intent).
Suggested change
| # Check marker balance across all SKILL.md files. Fails fast on an end marker | |
| # without a matching start so we catch malformed ordering, not just net counts. | |
| # Check marker balance across all Markdown files being processed. Fails fast on | |
| # an end marker without a matching start so we catch malformed ordering, not | |
| # just net counts. |
|
|
||
| File-level: `references/cli-*.md` files are deleted when building ZIPs. MCP-related reference files are always kept. | ||
|
|
||
| The stripper fails the build if any SKILL.md has unbalanced variant markers. Run `bash scripts/test-strip-variants.sh` to verify the stripper itself. |
There was a problem hiding this comment.
This says the stripper fails the build if any SKILL.md has unbalanced markers, but scripts/strip-variants.sh currently validates all *.md files under the destination tree. Please align this documentation with the script’s actual behavior (either broaden the doc to “any .md file” or narrow the script).
Suggested change
| The stripper fails the build if any SKILL.md has unbalanced variant markers. Run `bash scripts/test-strip-variants.sh` to verify the stripper itself. | |
| The stripper fails the build if any `.md` file in the stripped tree has unbalanced variant markers. Run `bash scripts/test-strip-variants.sh` to verify the stripper itself. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@makehq/cli) as a first-class interface alongside the existing Make MCP server. CLI is preferred when the agent has shell access; MCP is used otherwise.make-mcp-reference→make-interface-reference. The skill now covers both interfaces: CLI install/auth, MCP OAuth/token, scopes, tool-invocation mapping, and troubleshooting.scripts/strip-variants.sh) so downloadable ZIPs for Claude Desktop / claude.ai get MCP-only content (CLI sections andreferences/cli-*.mdfiles removed). Plugin install andnpx skills addstill consume the full CLI+MCP source tree.<!-- variant:cli-* -->and<!-- variant:mcp-only-* -->markers to gate what's stripped. Stripper enforces marker balance and fails the build on mismatches.Breaking changes
make-mcp-reference→make-interface-reference. The content, frontmatter, and directory have all moved; the old skill no longer exists under its original name in the source tree.dist/make-mcp-reference.zipis kept as a deprecated alias (byte-for-byte copy ofmake-interface-reference.zip) so existingraw.githubusercontent.com/…/dist/make-mcp-reference.zipbookmarks continue to work. Folder-name-based installs of the old skill should be re-pointed atmake-interface-referencewhen convenient.npm run releasevia the existingfeat:commit semantics.Details
New files:
scripts/strip-variants.sh+scripts/test-strip-variants.shwith fixtures — awk-based, balance check, full test suite.skills/make-interface-reference/references/cli-install-and-auth.mdskills/make-interface-reference/references/mcp-install-and-auth.md(extracted from the old SKILL.md)skills/make-interface-reference/references/tool-invocation-mapping.md(MCP ↔ CLI command table)Updated:
skills/make-interface-reference/SKILL.md— rewritten for dual-interface body with detection logic (command -v make-cli→make-cli whoami→ MCP fallback).skills/make-scenario-building/SKILL.md+skills/make-module-configuring/SKILL.md— both gain an "Interface: CLI or MCP" preamble.README.md— new Interfaces section, split CLI Setup / MCP Server Setup, download table notes MCP-only ZIPs.CLAUDE.md— project overview updated, new "Build variants" subsection documenting the marker conventions.build.sh— runs the stripper over a tempdir copy ofskills/before zipping. Source tree is never modified. Producesmake-mcp-reference.zipas a deprecated alias for URL compat.package.json,.claude-plugin/plugin.json,.claude-plugin/marketplace.json— agent-agnostic dual-interface descriptions;make-cliadded to keywords.