git:20260205.21c7f65 to git:20260205.a104c93

6 added, 0 removed. Audit A to A.

# MSP Claude Plugins - Project Configuration

## Project Overview

Community-driven Claude Code plugins for Managed Service Providers (MSPs).

## Learnings - 2026-02-04

### Astro Starlight GitHub Pages Configuration

When deploying Astro/Starlight to GitHub Pages at a subpath (e.g., `user.github.io/repo`), you must set both `site` and `base` in `astro.config.mjs`, and all internal links must include the base path prefix (e.g., `/msp-claude-plugins/getting-started/`).

### GitHub Pages Workflow Enablement via API

To enable GitHub Pages with workflow-based builds: `gh api repos/OWNER/REPO/pages -X POST -f build_type=workflow`. The PUT endpoint returns 404 if pages aren't already configured - use POST first to create.

### Parallel File Creator Agents for Documentation

When creating many documentation files (e.g., 20+ pages for a docs site), use multiple Task agents with `subagent_type=file-creator` in parallel, grouping files by logical section (getting-started, reference, commands, etc.) for efficient generation.

### Claude Code Marketplace Manifest Structure

The marketplace requires `.claude-plugin/marketplace.json` with `$schema`, `name`, `owner`, and `plugins` array. Each plugin entry needs `name`, `source` (relative path like `./kaseya/autotask`), and `description`. Users install via `/plugin marketplace add owner/repo`.

### Starlight Valid Icon Names

Starlight uses a specific icon set. Use `seti:folder` for folder icons (not `folder`). Common valid icons: `open-book`, `rocket`, `setting`, `add-document`, `github`. Invalid icons render as colored squares.

### GitHub Actions Workflow Location for Monorepos

When the git repo root differs from the docs directory (e.g., repo at `/mspMarketPlace/` but docs at `/mspMarketPlace/msp-claude-plugins/docs/`), the `.github/workflows/` must be at the repo root, and workflow paths must reference the full path (e.g., `msp-claude-plugins/docs/`).

### Claude Code Plugin Architecture: Skills vs MCP

Plugins have value without MCP servers - skills provide domain knowledge, commands provide prompt templates. MCP servers require implementing the MCP protocol; client libraries (like node-syncro) are NOT MCP servers and cannot be invoked via `npx` in .mcp.json. Only include .mcp.json when an actual MCP server package exists.

### Plugin.json Valid Schema Fields

Valid fields: `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `mcpServers`, `hooks`. Don't use custom fields like `vendor`, `product`, `api_version`, `requires_api_key`. Document auth requirements in README instead.

### ESLint varsIgnorePattern for Underscore Variables

`argsIgnorePattern: "^_"` only applies to function arguments, not destructured variables. To ignore underscore-prefixed variables in destructuring, add `varsIgnorePattern: "^_"`. Full config: `["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }]`.

### Marketplace-First README Pattern

Following anthropics/knowledge-work-plugins, lead with one-command marketplace install (`/plugin marketplace add owner/repo`), then clean plugin table, then progressive disclosure. Dramatically shorter and more effective than detailed technical READMEs.

### Custom Astro vs Starlight Trade-off

Custom Astro sites require manually building navigation, search (Pagefind), dark mode, and code copy. Worth it when PRD specifies exact design system (colors, typography) that Starlight can't match.

### Marketplace.json Plugin Entries

Each plugin needs `name` (for `--plugin` flag), `source` (relative path like `./kaseya/autotask`), `description`, `version`, `category`, and `tags`. The `source` path must start with `./`.

## Learnings - 2026-02-05

### Claude Code Plugin Authentication Pattern

Plugins should use `~/.claude/settings.json` with an `env` section for credentials (encrypted in macOS Keychain), not raw shell env vars. Project-specific secrets go in `.claude/settings.local.json` (gitignored). MCP servers access credentials via `${VAR}` syntax in `.mcp.json`. Precedence: managed → CLI → local → project → user.

### Validation Status Badges for Plugin Quality

Use status badges (✅ Validated, 🧪 Community) rather than disclaimer paragraphs to set expectations. Brief footnote: "Validated = tested against production APIs. Community = follows patterns, may need adjustments." No hedging or apologies.

+ ### Claude Desktop vs Claude Code Plugin Architecture

+ Claude Desktop uses `claude_desktop_config.json` (not settings.json) and supports MCPB extensions (zip archives), not directory-based plugins. For seamless "Connect" button auth like Anthropic's first-party integrations, vendors need remote HTTP MCP servers (e.g., `https://mcp.slack.com/mcp`). MSP vendors don't have these, so we need hosted MCP servers with our own OAuth layer to store user credentials securely.

+ ### Anthropic Remote MCP Server Pattern

+ First-party integrations (Slack, Atlassian, Notion) use vendor-hosted MCP servers at `https://mcp.{vendor}.com/mcp` with OAuth handled by the vendor. For vendors without native OAuth (most MSP tools), implement a hosted MCP server with: (1) our own OAuth layer, (2) secure credential storage per user, (3) proxy to vendor API with stored credentials.