# Helix Claude Code Plugin

The official Claude Code plugin for Helix — PingCAP's unified IT
platform. It bundles:

- **MCP connection** (`.mcp.json`): points Claude Code at the production
  Helix MCP endpoint. **No token is shipped or required** — on first use
  Claude Code discovers Helix's OAuth 2.1 authorization server (RFC 9728)
  and walks the user through SSO + consent in the browser. Set
  `HELIX_MCP_URL` to override the endpoint (local dev:
  `http://localhost:8000/api/v1/mcp`).
- **Skills** (`skills/*/SKILL.md`): playbooks that teach Claude how to
  compose Helix's 400+ MCP tools correctly (permission scoping, the
  approval-chain invariant, pagination, cost semantics, …).
- **Commands** (`commands/*.md`): one-shot slash commands —
  `/helix:whoami`, `/helix:my-it`, `/helix:approvals`, `/helix:costs`,
  `/helix:support`.

## Layout

```
plugin/
  marketplace/                      # ← what actually ships (zipped to S3)
    .claude-plugin/marketplace.json # marketplace root ("helix" marketplace)
    plugins/helix/                  # the plugin itself
      .claude-plugin/plugin.json
      .mcp.json
      skills/…  commands/…
  README.md                         # this file (not shipped)
```

The marketplace uses a **relative-path plugin source**, which Claude Code
only resolves for git-based or *local-directory* marketplaces — NOT for
marketplaces added via a bare HTTPS URL to `marketplace.json` (only the
JSON would be fetched). That constraint is why distribution is a **zip of
the whole marketplace directory**, installed from a local path. Do not
"simplify" this into a hosted marketplace.json URL; it will break
installs. (Verified against the plugin-marketplaces docs, 2026-07.)

## Distribution (mirrors the CLI)

`.github/workflows/plugin-release.yml` zips `plugin/marketplace/` on
every `main` push touching `plugin/**` and publishes to S3:

```
plugin-dist/<version>+g<sha8>/helix-claude-plugin.zip
plugin-dist/latest/manifest.json      # version, key, sha256, size
```

The backend `cli_dist` domain serves the manifest + a presigned download
(`GET /api/v1/plugin/manifest`, `GET /api/v1/plugin/download`), the Help
Center (帮助 → AI 助手集成) renders the download card, and the MCP tool
`plugin_get_download_manifest` exposes the same metadata to AI clients.

## Install paths (employee-facing)

1. **With the helix CLI** (recommended; `helix plugin update` refreshes to each new release):
   ```bash
   helix plugin install        # download + verify + register with Claude Code
   helix plugin update         # refresh to the latest published version
   helix plugin status         # installed vs latest
   ```
2. **Manual**: download the zip from Help → AI 助手集成, unzip to a
   permanent location, then:
   ```bash
   claude plugin marketplace add <unzipped-dir>
   claude plugin install helix@helix
   ```

## Versioning

`plugin.json`'s `version` is the human-facing plugin version — bump it
when skills/commands/config change materially. The release workflow
appends `+g<sha8>` to the *distribution* version so every S3 upload is
immutable and traceable; `plugin.json` inside the zip is left untouched.

## Local development

```bash
claude plugin marketplace add ./plugin/marketplace
claude plugin install helix@helix
HELIX_MCP_URL=http://localhost:8000/api/v1/mcp claude
```

Validate manifests after editing:
```bash
claude plugin validate ./plugin/marketplace
```

## Why there is no MCPB (Claude Desktop) bundle

MCPB packages can only launch **local stdio** MCP servers; Helix's MCP is
remote HTTP with OAuth. Wrapping it in a local bridge would trade a
short-lived OAuth session for a long-lived pasted token — strictly worse.
Claude Desktop and claude.ai users connect via **Settings → Connectors →
Add custom connector** with the MCP URL instead (see Help → AI 助手集成).
Decision recorded in `docs/architecture/DECISIONS.md`.