diff --git a/.claude/mcp.json b/.claude/mcp.json deleted file mode 100644 index dc19508872d..00000000000 --- a/.claude/mcp.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "mcpServers": { - "linear": { - "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"] - } - } -} diff --git a/.claude/plugins/n8n/.claude-plugin/marketplace.json b/.claude/plugins/n8n/.claude-plugin/marketplace.json new file mode 100644 index 00000000000..df61b27875d --- /dev/null +++ b/.claude/plugins/n8n/.claude-plugin/marketplace.json @@ -0,0 +1,12 @@ +{ + "name": "n8n", + "owner": { + "name": "n8n" + }, + "plugins": [ + { + "name": "n8n", + "source": "./" + } + ] +} diff --git a/.claude/plugins/n8n/.claude-plugin/plugin.json b/.claude/plugins/n8n/.claude-plugin/plugin.json new file mode 100644 index 00000000000..60449da743c --- /dev/null +++ b/.claude/plugins/n8n/.claude-plugin/plugin.json @@ -0,0 +1,4 @@ +{ + "name": "n8n", + "description": "n8n Claude Code plugin — shared skills, commands, and agents for n8n development" +} diff --git a/.claude/plugins/n8n/README.md b/.claude/plugins/n8n/README.md new file mode 100644 index 00000000000..000f72b26bc --- /dev/null +++ b/.claude/plugins/n8n/README.md @@ -0,0 +1,67 @@ +# n8n Claude Code Plugin + +Shared skills, commands, and agents for n8n development. + +## Skills + +### `n8n:setup-mcps` + +Configures commonly used MCP servers for n8n engineers. + +**Usage:** +``` +/n8n:setup-mcps +``` + +**What it does:** +1. Checks which MCPs are already configured (matches by URL, not name) +2. Presents a multi-select menu of available MCPs (Linear, Notion, Context7, Figma) +3. For each selected MCP, asks which scope to install in: + - **user** (recommended) — available across all projects + - **local** — only in this project (`settings.local.json`) +4. Installs using official recommended commands + +**Note:** Project scope is intentionally not offered since `.claude/settings.json` is tracked in git. + +## Design Decisions + +### Why a plugin instead of standalone skills? + +To get the `n8n:` namespace prefix for all n8n-specific skills, avoiding name +collisions with built-in or personal skills. Claude Code only supports +colon-namespaced skills (`n8n:setup-mcps`) through the plugin system — +standalone `.claude/skills/` entries cannot be namespaced. This also provides a +home for future n8n skills, commands, and agents under the same `n8n:` prefix. + +### Why only user and local scope (no project scope)? + +Project scope writes MCP config to `.claude/settings.json`, which is tracked in +git. Since MCP credentials are personal (OAuth tokens, API keys), they should +not end up in version control. User scope makes MCPs available across all +projects; local scope (`settings.local.json`) keeps them project-specific but +gitignored. + +### Why ask scope per MCP instead of once for all? + +Engineers may want different scopes for different MCPs. For example, Context7 +and Figma are useful across all projects (user scope), while Linear or Notion +might only be needed for this project (local scope). + +## Plugin Structure + +``` +.claude/plugins/n8n/ +├── .claude-plugin/ +│ ├── marketplace.json # Marketplace manifest +│ └── plugin.json # Plugin identity +├── skills/ +│ └── sample-skill/ +│ └── SKILL.md +└── README.md +``` + +## Known Issues + +- Plugin skill namespacing requires omitting the `name` field from SKILL.md + frontmatter due to a [Claude Code bug](https://github.com/anthropics/claude-code/issues/17271). + The directory name is used as the skill identifier instead. diff --git a/.claude/plugins/n8n/skills/setup-mcps/SKILL.md b/.claude/plugins/n8n/skills/setup-mcps/SKILL.md new file mode 100644 index 00000000000..6abac77be56 --- /dev/null +++ b/.claude/plugins/n8n/skills/setup-mcps/SKILL.md @@ -0,0 +1,75 @@ +--- +description: >- + Configure MCP servers for n8n development. Use when the user says /setup-mcps + or asks to set up MCP servers for n8n. +--- + +# MCP Setup for n8n Development + +Configure commonly used MCP servers for n8n engineers. + +## Instructions + +1. First, check which MCPs are already configured by running: +```bash +claude mcp list +``` +Parse the output and match by **URL/command**, not server name (users may have +used different names). The URLs to check for: +- Linear: `mcp.linear.app` +- Notion: `mcp.notion.com` +- Context7: `ctx7` or `context7-mcp` +- Figma: `mcp.figma.com` + +Skip any MCP whose URL/command is already present (regardless of scope or name). + +2. Present the MCP selection menu using `AskUserQuestion` with `multiSelect: true`. +Only show MCPs that are **not** already configured. If all are already configured, +inform the user and skip the menu. + +| Option | Label | Description | +|--------|-------|-------------| +| Linear | `Linear` | Linear ticket management (HTTP, OAuth — opens browser to authenticate) | +| Notion | `Notion` | Notion workspace integration (HTTP, OAuth — opens browser to authenticate) | +| Context7 | `Context7` | Library documentation lookup (OAuth setup via CLI) | +| Figma | `Figma` | Figma design integration (HTTP, OAuth — opens browser to authenticate) | + +3. Process each selected MCP **one at a time** in a loop. For each MCP: + a. Ask the user via `AskUserQuestion`: "Where should **{MCP name}** be installed?" + - **user** (default, recommended) — available in all projects + - **local** — only in this project + b. Run the install command for that MCP with the chosen scope + c. Then move to the next MCP and ask again + +Do NOT batch the scope question — ask separately for each MCP. +Do NOT offer project scope — it modifies `.claude/settings.json` which is tracked in git. + +Commands per MCP: + +### Linear +```bash +claude mcp add -s {scope} linear-server --transport http https://mcp.linear.app/mcp +``` +After adding, tell the user to run `/mcp` in their next session to authenticate. + +### Notion +```bash +claude mcp add -s {scope} notion --transport http https://mcp.notion.com/mcp +``` +After adding, tell the user to run `/mcp` in their next session to authenticate. + +### Context7 +Tell the user to run this command themselves (it handles auth via OAuth automatically): + +``` +npx ctx7 setup --claude +``` + +### Figma +```bash +claude mcp add -s {scope} figma --transport http https://mcp.figma.com/mcp +``` +After adding, tell the user to run `/mcp` in their next session to authenticate. + +5. After running the commands, confirm which MCPs were configured and note any + manual steps remaining (authentication via `/mcp`, Context7 setup). diff --git a/.claude/settings.json b/.claude/settings.json index accfe1fb14b..e304c45af6d 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -12,5 +12,16 @@ "Bash(popd)", "Bash(pushd:*)" ] + }, + "extraKnownMarketplaces": { + "n8n": { + "source": { + "source": "directory", + "path": "./.claude/plugins/n8n" + } + } + }, + "enabledPlugins": { + "n8n@n8n": true } }