diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md new file mode 100644 index 0000000..6c7a4f4 --- /dev/null +++ b/.claude/skills/release/SKILL.md @@ -0,0 +1,83 @@ +--- +name: release +description: Create a new GitHub MCP release with proper .mcpb bundle. Use when the user wants to cut a release, publish a new version, or update the mcpb bundle. +disable-model-invocation: true +argument-hint: [version-bump: patch|minor|major] +allowed-tools: Read, Bash(npm *), Bash(git *), Bash(gh *) +--- + +# Release Process for GitHub MCP + +Create a release with a proper `.mcpb` bundle for Claude Desktop. + +## Context + +- The `.mcpb` format is a zip archive created by `mcpb pack` (from `@anthropic-ai/mcpb`) +- `manifest.json` defines the bundle metadata and defaults to `--preset core` (~109 tools) +- `.mcpbignore` controls what's excluded from the bundle +- The release workflow (`.github/workflows/release.yml`) handles CI builds automatically + +## Steps + +### 1. Determine version bump + +Use `$ARGUMENTS` or default to `patch`. Valid: `patch`, `minor`, `major`. + +### 2. Create release branch + +```bash +gh issue create --title "Release v" --body "Version bump for release." +git checkout -b -release-v +``` + +### 3. Bump version + +```bash +npm version --no-git-tag-version +``` + +This updates `package.json` and `package-lock.json`. + +### 4. Commit, push, PR, merge + +```bash +git add package.json package-lock.json +git commit -m "chore: bump version to (#)" +git push -u origin +gh pr create --title "chore: release v" --body "Closes #" +gh pr merge --squash --delete-branch +``` + +### 5. Tag and push + +```bash +git checkout main && git pull +git tag v +git push origin v +``` + +This triggers `.github/workflows/release.yml` which: +1. `npm ci` - install all deps +2. `npm run build` - compile TypeScript +3. `npm install -g @anthropic-ai/mcpb` - install bundle CLI +4. Updates `manifest.json` version from tag +5. `mcpb pack` - creates `github-mcp.mcpb` +6. Creates GitHub release with the `.mcpb` asset +7. `npm publish` - publishes to npm + +### 6. Verify + +```bash +gh run list --limit 1 +gh run watch --exit-status +gh release view v --json assets +``` + +Confirm the release has `github-mcp.mcpb` as an asset. + +## Important Notes + +- The manifest.json hardcodes `--preset core` - the .mcpb only loads core tools (~109) +- `.mcpbignore` excludes src/, docs/, .git/, etc. from the bundle +- `npm ci --omit=dev` is NOT yet in the workflow - bundle is bloated (~23MB vs ideal ~3MB). See issue #66. +- Do NOT create tar.gz or zip archives - .mcpb is the only distribution format diff --git a/.gitignore b/.gitignore index 5af4d11..b97f5d9 100644 --- a/.gitignore +++ b/.gitignore @@ -38,7 +38,13 @@ pnpm-lock.yaml # GitHub OAuth App secrets (never commit) .oauth-secrets oauth-config.json -.claude/ +.claude/* +!.claude/skills/ +!.claude/CLAUDE.md +!.claude/hooks/ +!.claude/validators/ +!.claude/loggers/ +!.claude/sop.json # Local workflow state .current-issue diff --git a/docs/architecture.html b/docs/architecture.html index 8d04473..eee5d62 100644 --- a/docs/architecture.html +++ b/docs/architecture.html @@ -123,6 +123,7 @@ Guide Architecture User Stories + Roadmap GitHub diff --git a/docs/guide.html b/docs/guide.html index ca53736..aa034e8 100644 --- a/docs/guide.html +++ b/docs/guide.html @@ -196,6 +196,7 @@ Guide Architecture User Stories + Roadmap GitHub diff --git a/docs/index.html b/docs/index.html index 44a85f7..b907386 100644 --- a/docs/index.html +++ b/docs/index.html @@ -205,6 +205,7 @@ Guide Architecture User Stories + Roadmap GitHub diff --git a/docs/roadmap.html b/docs/roadmap.html new file mode 100644 index 0000000..0f17826 --- /dev/null +++ b/docs/roadmap.html @@ -0,0 +1,304 @@ + + + + + + GitHub MCP - Roadmap + + + + + +

Roadmap

+ +

Preset System

+

Tools are organized into 33 categories, grouped into presets to stay within Claude Desktop's ~100 tool limit. Presets are defined in src/tools/generator.ts.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PresetCategoriesToolsTargetStatus
corerepos, issues, pulls, search, users, actions, gists109Claude Desktop (default)shipped
securitydependabot, secretScanning, codeScanning, codeSecurity, securityAdvisories~50Security auditscode done
org-adminorgs, teams, projects, activity, users, apps~70Org managementcode done
cicdactions, checks, repos, packages~60CI/CD pipelinescode done
fullall 33 categories327Claude Code onlycode done
+ +

All 33 Tool Categories

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CategoryToolsPresetsPriority
repos20core cicdHigh
issues17coreHigh
pulls15coreHigh
search7coreHigh
users16core org-adminHigh
actions17core cicdHigh
gists17coreMedium
orgs-org-adminHigh
teams-org-adminMedium
projects-org-adminMedium
activity-org-adminMedium
checks-cicdMedium
git-fullMedium
reactions-fullLow
packages-cicdLow
dependabot-securityLow
secretScanning-securityLow
codeScanning-securityLow
codeSecurity-securityLow
securityAdvisories-securityLow
apps-org-adminLow
billing-fullLow
codespaces-fullLow
copilot-fullLow
migrations-fullLow
interactions-fullLow
rateLimit-fullLow
markdown-fullLow
meta-fullLow
emojis-fullLow
gitignore-fullLow
licenses-fullLow
codesOfConduct-fullLow
+ +

Release Status

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Version.mcpbSizePresetNotes
v0.1.0yes3 MB-Initial release
v0.2.0-beta.3yes20 MB-Bloated - all deps bundled
v0.2.0no--Broken - released tar.gz/zip instead
v0.2.1yes23 MBcoreFixed workflow, but bundle still bloated (#66)
+ +

Open Work

+ +
+

Reduce .mcpb bundle size (23MB → ~3MB)

+

#66 — Dev dependencies (typescript, tsx, @types) and unused SDK transitive deps (express, hono) are bundled. Fix: add npm ci --omit=dev before mcpb pack in release workflow, and update .mcpbignore.

+ todo +
+ +
+

Multiple .mcpb bundles per preset

+

Original plan from #55: release separate github-mcp-core.mcpb, github-mcp-security.mcpb, etc. Currently only core is bundled. Other presets work via CLI (--preset security) but have no .mcpb download.

+ todo +
+ +
+

Sync version across package.json and manifest.json

+

Both files have a version field that can drift. Release workflow updates manifest from tag, but local manifest.json stays stale.

+ low priority +
+ +

Architecture Decisions

+ +
+

One .mcpb = core preset only

+

Claude Desktop users get the core preset (~109 tools). Claude Code users use npx @ldraney/github-mcp with --preset full or --categories flag. This avoids overwhelming Claude Desktop's tool limit.

+
+ +
+

.mcpb is built by mcpb pack

+

The @anthropic-ai/mcpb CLI creates the bundle. It reads manifest.json for metadata and .mcpbignore for exclusions. Do not manually create archives.

+
+ +
+

Presets are code, not config

+

Preset definitions live in src/tools/generator.ts as TypeScript constants. Each preset lists category names. Categories are defined in src/tools/categories/*.ts with tool definitions and handlers inline.

+
+ + + + diff --git a/docs/user-story.html b/docs/user-story.html index 4dd7f9c..aac7816 100644 --- a/docs/user-story.html +++ b/docs/user-story.html @@ -118,6 +118,7 @@ Guide Architecture User Stories + Roadmap GitHub