mirror of
https://github.com/anthropics/claude-plugins-official.git
synced 2026-05-06 19:52:42 +00:00
Compare commits
1 Commits
update-cod
...
daisy/plug
| Author | SHA1 | Date | |
|---|---|---|---|
|
d01e0fbab2 |
File diff suppressed because it is too large
Load Diff
229
.github/scripts/discover_bumps.py
vendored
229
.github/scripts/discover_bumps.py
vendored
@@ -1,229 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Discover plugins in marketplace.json whose upstream repo has moved past
|
||||
their pinned SHA, update the file in place, and emit a summary.
|
||||
|
||||
Adapted from claude-plugins-community-internal's discover_bumps.py for the
|
||||
single-file marketplace.json format used by claude-plugins-official.
|
||||
|
||||
Usage: discover_bumps.py [--plugin NAME] [--max N] [--dry-run]
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from datetime import datetime, timezone
|
||||
from typing import Any
|
||||
|
||||
|
||||
MARKETPLACE_PATH = ".claude-plugin/marketplace.json"
|
||||
|
||||
|
||||
def gh_api(path: str) -> Any:
|
||||
"""GET from the GitHub API. None on not-found; raises on other errors.
|
||||
|
||||
"Not found" covers both 404 (resource gone) and 422 "No commit found
|
||||
for SHA" (force-pushed away). Both mean the thing we asked for isn't
|
||||
there — treating them the same lets callers handle dead refs uniformly.
|
||||
"""
|
||||
r = subprocess.run(
|
||||
["gh", "api", path], capture_output=True, text=True
|
||||
)
|
||||
if r.returncode != 0:
|
||||
combined = r.stdout + r.stderr
|
||||
if any(s in combined for s in ("404", "Not Found", "No commit found")):
|
||||
return None
|
||||
raise RuntimeError(f"gh api {path}: {r.stderr.strip() or r.stdout.strip()}")
|
||||
return json.loads(r.stdout)
|
||||
|
||||
|
||||
def parse_github_repo(url: str) -> tuple[str, str] | None:
|
||||
"""Extract (owner, repo) from a URL or owner/repo shorthand."""
|
||||
# Full URL: https://github.com/owner/repo(.git)(/...)
|
||||
m = re.match(r"https?://github\.com/([^/]+)/([^/]+?)(?:\.git)?(?:/|$)", url)
|
||||
if m:
|
||||
return m.group(1), m.group(2)
|
||||
# Shorthand: owner/repo
|
||||
m = re.match(r"^([\w.-]+)/([\w.-]+)$", url)
|
||||
if m:
|
||||
return m.group(1), m.group(2)
|
||||
return None
|
||||
|
||||
|
||||
def latest_sha(owner: str, repo: str, *, ref: str | None, path: str | None) -> str | None:
|
||||
"""Latest commit SHA for the repo, optionally scoped to a ref and/or path."""
|
||||
if path:
|
||||
# Scoped to a subdirectory — use the commits list endpoint with path filter.
|
||||
q = f"repos/{owner}/{repo}/commits?per_page=1&path={path}"
|
||||
if ref:
|
||||
q += f"&sha={ref}"
|
||||
commits = gh_api(q)
|
||||
if not commits:
|
||||
return None
|
||||
return commits[0]["sha"]
|
||||
# Whole repo — the single-ref endpoint is cheaper.
|
||||
if not ref:
|
||||
meta = gh_api(f"repos/{owner}/{repo}")
|
||||
if not meta:
|
||||
return None
|
||||
ref = meta["default_branch"]
|
||||
c = gh_api(f"repos/{owner}/{repo}/commits/{ref}")
|
||||
return c["sha"] if c else None
|
||||
|
||||
|
||||
def pinned_age_days(owner: str, repo: str, sha: str) -> int | None:
|
||||
"""Days since the pinned commit was authored. Used for oldest-first rotation."""
|
||||
c = gh_api(f"repos/{owner}/{repo}/commits/{sha}")
|
||||
if not c:
|
||||
return None
|
||||
dt = datetime.fromisoformat(
|
||||
c["commit"]["committer"]["date"].replace("Z", "+00:00")
|
||||
)
|
||||
return (datetime.now(timezone.utc) - dt).days
|
||||
|
||||
|
||||
def main() -> int:
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--plugin", help="only check this plugin")
|
||||
ap.add_argument("--max", type=int, default=20, help="cap bumps emitted")
|
||||
ap.add_argument("--dry-run", action="store_true", help="don't write marketplace.json")
|
||||
args = ap.parse_args()
|
||||
|
||||
with open(MARKETPLACE_PATH) as f:
|
||||
marketplace = json.load(f)
|
||||
|
||||
plugins = marketplace.get("plugins", [])
|
||||
bumps: list[dict] = []
|
||||
dead: list[str] = []
|
||||
skipped_non_github = 0
|
||||
checked = 0
|
||||
|
||||
for plugin in plugins:
|
||||
name = plugin.get("name", "?")
|
||||
src = plugin.get("source")
|
||||
|
||||
# Only process object sources with a sha field
|
||||
if not isinstance(src, dict) or "sha" not in src:
|
||||
continue
|
||||
|
||||
# Filter to specific plugin if requested
|
||||
if args.plugin and name != args.plugin:
|
||||
continue
|
||||
|
||||
checked += 1
|
||||
kind = src.get("source")
|
||||
url = src.get("url", "")
|
||||
path = src.get("path")
|
||||
ref = src.get("ref")
|
||||
pinned = src.get("sha")
|
||||
|
||||
slug = parse_github_repo(url)
|
||||
if not slug:
|
||||
skipped_non_github += 1
|
||||
continue
|
||||
owner, repo = slug
|
||||
|
||||
try:
|
||||
latest = latest_sha(owner, repo, ref=ref, path=path)
|
||||
except RuntimeError as e:
|
||||
print(f"::warning::{name}: {e}", file=sys.stderr)
|
||||
continue
|
||||
|
||||
if latest is None:
|
||||
dead.append(f"{name} ({owner}/{repo})")
|
||||
continue
|
||||
|
||||
if latest == pinned:
|
||||
continue # up to date
|
||||
|
||||
# Age lookup for rotation — oldest-pinned first prevents starvation.
|
||||
try:
|
||||
age = pinned_age_days(owner, repo, pinned) if pinned else None
|
||||
except RuntimeError as e:
|
||||
print(f"::warning::{name}: age lookup failed: {e}", file=sys.stderr)
|
||||
age = None
|
||||
|
||||
bumps.append({
|
||||
"name": name,
|
||||
"kind": kind,
|
||||
"url": url,
|
||||
"path": path or "",
|
||||
"ref": ref or "",
|
||||
"old_sha": pinned or "",
|
||||
"new_sha": latest,
|
||||
"age_days": age if age is not None else 10**6,
|
||||
})
|
||||
|
||||
# Oldest-pinned first so nothing starves under the cap.
|
||||
bumps.sort(key=lambda b: -b["age_days"])
|
||||
emitted = bumps[: args.max]
|
||||
|
||||
# Apply bumps to marketplace data
|
||||
if emitted and not args.dry_run:
|
||||
bump_map = {b["name"]: b["new_sha"] for b in emitted}
|
||||
for plugin in plugins:
|
||||
name = plugin.get("name")
|
||||
src = plugin.get("source")
|
||||
if isinstance(src, dict) and name in bump_map:
|
||||
src["sha"] = bump_map[name]
|
||||
|
||||
with open(MARKETPLACE_PATH, "w") as f:
|
||||
json.dump(marketplace, f, indent=2, ensure_ascii=False)
|
||||
f.write("\n")
|
||||
|
||||
# Write GitHub outputs
|
||||
out = os.environ.get("GITHUB_OUTPUT")
|
||||
if out:
|
||||
bumped_names = ",".join(b["name"] for b in emitted)
|
||||
with open(out, "a") as fh:
|
||||
fh.write(f"count={len(emitted)}\n")
|
||||
fh.write(f"bumped_names={bumped_names}\n")
|
||||
|
||||
# Write GitHub step summary
|
||||
summary = os.environ.get("GITHUB_STEP_SUMMARY")
|
||||
if summary:
|
||||
with open(summary, "a") as fh:
|
||||
fh.write("## SHA Bump Discovery\n\n")
|
||||
fh.write(f"- Checked: {checked} SHA-pinned entries\n")
|
||||
fh.write(f"- Stale: {len(bumps)} (applying {len(emitted)}, cap {args.max})\n")
|
||||
if skipped_non_github:
|
||||
fh.write(f"- Skipped non-GitHub: {skipped_non_github}\n")
|
||||
if dead:
|
||||
fh.write(f"- **Dead upstream** ({len(dead)}): {', '.join(dead)}\n")
|
||||
if emitted:
|
||||
fh.write("\n| Plugin | Old | New | Age |\n|---|---|---|---|\n")
|
||||
for b in emitted:
|
||||
old = b["old_sha"][:8] if b["old_sha"] else "(unpinned)"
|
||||
fh.write(f"| {b['name']} | `{old}` | `{b['new_sha'][:8]}` | {b['age_days']}d |\n")
|
||||
|
||||
# Write PR body for the workflow to use
|
||||
pr_body_path = os.environ.get("PR_BODY_PATH", "/tmp/bump-pr-body.md")
|
||||
if emitted:
|
||||
with open(pr_body_path, "w") as fh:
|
||||
fh.write("Upstream repos moved. Bumping pinned SHAs so plugins track latest.\n\n")
|
||||
fh.write("| Plugin | Old | New | Upstream |\n")
|
||||
fh.write("|--------|-----|-----|----------|\n")
|
||||
for b in emitted:
|
||||
old = b["old_sha"][:8] if b["old_sha"] else "(unpinned)"
|
||||
slug_str = re.sub(r"https?://github\.com/", "", b["url"])
|
||||
slug_str = re.sub(r"\.git$", "", slug_str)
|
||||
compare = f"https://github.com/{slug_str}/compare/{b['old_sha'][:12]}...{b['new_sha'][:12]}"
|
||||
fh.write(f"| `{b['name']}` | `{old}` | `{b['new_sha'][:8]}` | [diff]({compare}) |\n")
|
||||
fh.write(f"\n---\n_Auto-generated by `bump-plugin-shas.yml` on {datetime.now(timezone.utc).strftime('%Y-%m-%d')}_\n")
|
||||
|
||||
# Console summary
|
||||
print(f"Checked {checked} SHA-pinned plugins", file=sys.stderr)
|
||||
print(f"Stale: {len(bumps)}, applying: {len(emitted)}", file=sys.stderr)
|
||||
if dead:
|
||||
print(f"Dead upstream: {', '.join(dead)}", file=sys.stderr)
|
||||
for b in emitted:
|
||||
old = b["old_sha"][:8] if b["old_sha"] else "unpinned"
|
||||
print(f" {b['name']}: {old} -> {b['new_sha'][:8]} ({b['age_days']}d)", file=sys.stderr)
|
||||
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
133
.github/workflows/bump-plugin-shas.yml
vendored
133
.github/workflows/bump-plugin-shas.yml
vendored
@@ -1,133 +0,0 @@
|
||||
name: Bump plugin SHAs
|
||||
|
||||
# Weekly sweep of marketplace.json — for each entry whose upstream repo has
|
||||
# moved past its pinned SHA, open a PR against main with updated SHAs. The
|
||||
# validate-marketplace workflow then runs on the PR to confirm the file is
|
||||
# still well-formed.
|
||||
#
|
||||
# Adapted from claude-plugins-community-internal's bump-plugin-shas.yml
|
||||
# for the single-file marketplace.json format. Key difference: all bumps
|
||||
# are batched into one PR (since they all modify the same file).
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '23 7 * * 1' # Monday 07:23 UTC
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
plugin:
|
||||
description: Only bump this plugin (for testing)
|
||||
required: false
|
||||
max_bumps:
|
||||
description: Cap on plugins bumped this run
|
||||
required: false
|
||||
default: '20'
|
||||
dry_run:
|
||||
description: Discover only, don't open PR
|
||||
type: boolean
|
||||
default: true
|
||||
|
||||
concurrency:
|
||||
group: bump-plugin-shas
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
|
||||
jobs:
|
||||
bump:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Check for existing bump PR
|
||||
id: existing
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: |
|
||||
existing=$(gh pr list --label sha-bump --state open --json number --jq 'length')
|
||||
echo "count=$existing" >> "$GITHUB_OUTPUT"
|
||||
if [ "$existing" -gt 0 ]; then
|
||||
echo "::notice::Open sha-bump PR already exists — skipping"
|
||||
fi
|
||||
|
||||
- name: Ensure sha-bump label exists
|
||||
if: steps.existing.outputs.count == '0'
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: gh label create sha-bump --color 0e8a16 --description "Automated SHA bump" 2>/dev/null || true
|
||||
|
||||
- name: Overlay marketplace data from main
|
||||
if: steps.existing.outputs.count == '0'
|
||||
run: |
|
||||
git fetch origin main --depth=1 --quiet
|
||||
git checkout origin/main -- .claude-plugin/marketplace.json
|
||||
|
||||
- name: Discover and apply SHA bumps
|
||||
if: steps.existing.outputs.count == '0'
|
||||
id: discover
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
PR_BODY_PATH: /tmp/bump-pr-body.md
|
||||
PLUGIN: ${{ inputs.plugin }}
|
||||
MAX_BUMPS: ${{ inputs.max_bumps }}
|
||||
DRY_RUN: ${{ inputs.dry_run }}
|
||||
run: |
|
||||
args=(--max "${MAX_BUMPS:-20}")
|
||||
[[ -n "$PLUGIN" ]] && args+=(--plugin "$PLUGIN")
|
||||
[[ "$DRY_RUN" = "true" ]] && args+=(--dry-run)
|
||||
python3 .github/scripts/discover_bumps.py "${args[@]}"
|
||||
|
||||
- uses: oven-sh/setup-bun@v2
|
||||
if: steps.existing.outputs.count == '0' && steps.discover.outputs.count != '0' && inputs.dry_run != true
|
||||
|
||||
- name: Validate marketplace.json
|
||||
if: steps.existing.outputs.count == '0' && steps.discover.outputs.count != '0' && inputs.dry_run != true
|
||||
run: |
|
||||
bun .github/scripts/validate-marketplace.ts .claude-plugin/marketplace.json
|
||||
bun .github/scripts/check-marketplace-sorted.ts
|
||||
|
||||
- name: Push bump branch
|
||||
if: steps.existing.outputs.count == '0' && steps.discover.outputs.count != '0' && inputs.dry_run != true
|
||||
id: push
|
||||
run: |
|
||||
branch="auto/bump-shas-$(date +%Y%m%d)"
|
||||
echo "branch=$branch" >> "$GITHUB_OUTPUT"
|
||||
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
git checkout -b "$branch"
|
||||
git add .claude-plugin/marketplace.json
|
||||
git commit -m "Bump SHA pins for ${{ steps.discover.outputs.count }} plugin(s)
|
||||
|
||||
Plugins: ${{ steps.discover.outputs.bumped_names }}"
|
||||
git push -u origin "$branch" --force-with-lease
|
||||
|
||||
# GITHUB_TOKEN cannot create PRs (org policy: "Allow GitHub Actions to
|
||||
# create and approve pull requests" is disabled). Use the same GitHub App
|
||||
# that -internal's bump workflow uses.
|
||||
#
|
||||
# Prerequisite: app 2812036 must be installed on this repo. The PEM
|
||||
# secret must exist in this repo's settings (shared with -internal).
|
||||
- name: Generate bot token
|
||||
if: steps.push.outcome == 'success'
|
||||
id: app-token
|
||||
uses: actions/create-github-app-token@v1
|
||||
with:
|
||||
app-id: 2812036
|
||||
private-key: ${{ secrets.CLAUDE_DIRECTORY_BOT_PRIVATE_KEY }}
|
||||
owner: ${{ github.repository_owner }}
|
||||
repositories: ${{ github.event.repository.name }}
|
||||
|
||||
- name: Create pull request
|
||||
if: steps.push.outcome == 'success'
|
||||
env:
|
||||
GH_TOKEN: ${{ steps.app-token.outputs.token }}
|
||||
run: |
|
||||
gh pr create \
|
||||
--base main \
|
||||
--head "${{ steps.push.outputs.branch }}" \
|
||||
--title "Bump SHA pins (${{ steps.discover.outputs.count }} plugins)" \
|
||||
--body-file /tmp/bump-pr-body.md \
|
||||
--label sha-bump
|
||||
15
.github/workflows/validate-frontmatter.yml
vendored
15
.github/workflows/validate-frontmatter.yml
vendored
@@ -9,10 +9,6 @@ on:
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
# Fork PRs are auto-closed by close-external-prs.yml, so skip validation
|
||||
# for them entirely. This also prevents untrusted filenames from forks
|
||||
# from ever reaching the shell steps below.
|
||||
if: github.event.pull_request.head.repo.full_name == github.repository
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
@@ -24,19 +20,16 @@ jobs:
|
||||
|
||||
- name: Get changed frontmatter files
|
||||
id: changed
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
PR_NUMBER: ${{ github.event.pull_request.number }}
|
||||
run: |
|
||||
# Use diff-filter=AMRC to exclude deleted files (D) - only Added, Modified, Renamed, Copied
|
||||
FILES=$(gh pr diff "$PR_NUMBER" --name-only --diff-filter=AMRC | grep -E '(agents/.*\.md|skills/.*/SKILL\.md|commands/.*\.md)$' || true)
|
||||
FILES=$(gh pr diff ${{ github.event.pull_request.number }} --name-only --diff-filter=AMRC | grep -E '(agents/.*\.md|skills/.*/SKILL\.md|commands/.*\.md)$' || true)
|
||||
echo "files<<EOF" >> "$GITHUB_OUTPUT"
|
||||
echo "$FILES" >> "$GITHUB_OUTPUT"
|
||||
echo "EOF" >> "$GITHUB_OUTPUT"
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
|
||||
- name: Validate frontmatter
|
||||
if: steps.changed.outputs.files != ''
|
||||
env:
|
||||
FILES: ${{ steps.changed.outputs.files }}
|
||||
run: |
|
||||
printf '%s\n' "$FILES" | xargs bun .github/scripts/validate-frontmatter.ts
|
||||
echo "${{ steps.changed.outputs.files }}" | xargs bun .github/scripts/validate-frontmatter.ts
|
||||
|
||||
7
external_plugins/supabase/.claude-plugin/plugin.json
Normal file
7
external_plugins/supabase/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"name": "supabase",
|
||||
"description": "Supabase MCP integration for database operations, authentication, storage, and real-time subscriptions. Manage your Supabase projects, run SQL queries, and interact with your backend directly.",
|
||||
"author": {
|
||||
"name": "Supabase"
|
||||
}
|
||||
}
|
||||
6
external_plugins/supabase/.mcp.json
Normal file
6
external_plugins/supabase/.mcp.json
Normal file
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"supabase": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.supabase.com/mcp"
|
||||
}
|
||||
}
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "telegram",
|
||||
"description": "Telegram channel for Claude Code \u2014 messaging bridge with built-in access control. Manage pairing, allowlists, and policy via /telegram:access.",
|
||||
"version": "0.0.6",
|
||||
"version": "0.0.5",
|
||||
"keywords": [
|
||||
"telegram",
|
||||
"messaging",
|
||||
|
||||
@@ -284,19 +284,6 @@ function gate(ctx: Context): GateResult {
|
||||
return { action: 'drop' }
|
||||
}
|
||||
|
||||
// Like gate() but for bot commands: no pairing side effects, just allow/drop.
|
||||
function dmCommandGate(ctx: Context): { access: Access; senderId: string } | null {
|
||||
if (ctx.chat?.type !== 'private') return null
|
||||
if (!ctx.from) return null
|
||||
const senderId = String(ctx.from.id)
|
||||
const access = loadAccess()
|
||||
const pruned = pruneExpired(access)
|
||||
if (pruned) saveAccess(access)
|
||||
if (access.dmPolicy === 'disabled') return null
|
||||
if (access.dmPolicy === 'allowlist' && !access.allowFrom.includes(senderId)) return null
|
||||
return { access, senderId }
|
||||
}
|
||||
|
||||
function isMentioned(ctx: Context, extraPatterns?: string[]): boolean {
|
||||
const entities = ctx.message?.entities ?? ctx.message?.caption_entities ?? []
|
||||
const text = ctx.message?.text ?? ctx.message?.caption ?? ''
|
||||
@@ -682,7 +669,12 @@ setInterval(() => {
|
||||
// the gate's behavior for unrecognized groups.
|
||||
|
||||
bot.command('start', async ctx => {
|
||||
if (!dmCommandGate(ctx)) return
|
||||
if (ctx.chat?.type !== 'private') return
|
||||
const access = loadAccess()
|
||||
if (access.dmPolicy === 'disabled') {
|
||||
await ctx.reply(`This bot isn't accepting new connections.`)
|
||||
return
|
||||
}
|
||||
await ctx.reply(
|
||||
`This bot bridges Telegram to a Claude Code session.\n\n` +
|
||||
`To pair:\n` +
|
||||
@@ -693,7 +685,7 @@ bot.command('start', async ctx => {
|
||||
})
|
||||
|
||||
bot.command('help', async ctx => {
|
||||
if (!dmCommandGate(ctx)) return
|
||||
if (ctx.chat?.type !== 'private') return
|
||||
await ctx.reply(
|
||||
`Messages you send here route to a paired Claude Code session. ` +
|
||||
`Text and photos are forwarded; replies and reactions come back.\n\n` +
|
||||
@@ -703,12 +695,14 @@ bot.command('help', async ctx => {
|
||||
})
|
||||
|
||||
bot.command('status', async ctx => {
|
||||
const gated = dmCommandGate(ctx)
|
||||
if (!gated) return
|
||||
const { access, senderId } = gated
|
||||
if (ctx.chat?.type !== 'private') return
|
||||
const from = ctx.from
|
||||
if (!from) return
|
||||
const senderId = String(from.id)
|
||||
const access = loadAccess()
|
||||
|
||||
if (access.allowFrom.includes(senderId)) {
|
||||
const name = ctx.from!.username ? `@${ctx.from!.username}` : senderId
|
||||
const name = from.username ? `@${from.username}` : senderId
|
||||
await ctx.reply(`Paired as ${name}.`)
|
||||
return
|
||||
}
|
||||
@@ -991,17 +985,14 @@ bot.catch(err => {
|
||||
process.stderr.write(`telegram channel: handler error (polling continues): ${err.error}\n`)
|
||||
})
|
||||
|
||||
// Retry polling with backoff on any error. Previously only 409 was retried —
|
||||
// a single ETIMEDOUT/ECONNRESET/DNS failure rejected bot.start(), the catch
|
||||
// returned, and polling stopped permanently while the process stayed alive
|
||||
// (MCP stdin keeps it running). Outbound tools kept working but the bot was
|
||||
// deaf to inbound messages until a full restart.
|
||||
// 409 Conflict = another getUpdates consumer is still active (zombie from a
|
||||
// previous session, or a second Claude Code instance). Retry with backoff
|
||||
// until the slot frees up instead of crashing on the first rejection.
|
||||
void (async () => {
|
||||
for (let attempt = 1; ; attempt++) {
|
||||
try {
|
||||
await bot.start({
|
||||
onStart: info => {
|
||||
attempt = 0
|
||||
botUsername = info.username
|
||||
process.stderr.write(`telegram channel: polling as @${info.username}\n`)
|
||||
void bot.api.setMyCommands(
|
||||
@@ -1017,22 +1008,28 @@ void (async () => {
|
||||
return // bot.stop() was called — clean exit from the loop
|
||||
} catch (err) {
|
||||
if (shuttingDown) return
|
||||
if (err instanceof GrammyError && err.error_code === 409) {
|
||||
if (attempt >= 8) {
|
||||
process.stderr.write(
|
||||
`telegram channel: 409 Conflict persists after ${attempt} attempts — ` +
|
||||
`another poller is holding the bot token (stray 'bun server.ts' process or a second session). Exiting.\n`,
|
||||
)
|
||||
return
|
||||
}
|
||||
const delay = Math.min(1000 * attempt, 15000)
|
||||
const detail = attempt === 1
|
||||
? ' — another instance is polling (zombie session, or a second Claude Code running?)'
|
||||
: ''
|
||||
process.stderr.write(
|
||||
`telegram channel: 409 Conflict${detail}, retrying in ${delay / 1000}s\n`,
|
||||
)
|
||||
await new Promise(r => setTimeout(r, delay))
|
||||
continue
|
||||
}
|
||||
// bot.stop() mid-setup rejects with grammy's "Aborted delay" — expected, not an error.
|
||||
if (err instanceof Error && err.message === 'Aborted delay') return
|
||||
const is409 = err instanceof GrammyError && err.error_code === 409
|
||||
if (is409 && attempt >= 8) {
|
||||
process.stderr.write(
|
||||
`telegram channel: 409 Conflict persists after ${attempt} attempts — ` +
|
||||
`another poller is holding the bot token (stray 'bun server.ts' process or a second session). Exiting.\n`,
|
||||
)
|
||||
return
|
||||
}
|
||||
const delay = Math.min(1000 * attempt, 15000)
|
||||
const detail = is409
|
||||
? `409 Conflict${attempt === 1 ? ' — another instance is polling (zombie session, or a second Claude Code running?)' : ''}`
|
||||
: `polling error: ${err}`
|
||||
process.stderr.write(`telegram channel: ${detail}, retrying in ${delay / 1000}s\n`)
|
||||
await new Promise(r => setTimeout(r, delay))
|
||||
process.stderr.write(`telegram channel: polling failed: ${err}\n`)
|
||||
return
|
||||
}
|
||||
}
|
||||
})()
|
||||
|
||||
@@ -10,20 +10,6 @@ An MCP app is a standard MCP server that **also serves UI resources** — intera
|
||||
|
||||
The UI layer is **additive**. Under the hood it's still tools, resources, and the same wire protocol. If you haven't built a plain MCP server before, the `build-mcp-server` skill covers the base layer. This skill adds widgets on top.
|
||||
|
||||
> **Testing in Claude:** Add the server as a custom connector in claude.ai (via a Cloudflare tunnel for local dev) — this exercises the real iframe sandbox and `hostContext`. See https://claude.com/docs/connectors/building/testing.
|
||||
|
||||
## Claude host specifics
|
||||
|
||||
| `_meta.ui.*` key | Where | Effect |
|
||||
|---|---|---|
|
||||
| `resourceUri` | tool | Which `ui://` resource the host renders for this tool's results. |
|
||||
| `visibility: ["app"]` | tool | Hide a widget-only helper tool (e.g. geometry/image fetcher called via `callServerTool`) from Claude's tool list. |
|
||||
| `prefersBorder: false` | resource | Drop the host's outer card border (mobile). |
|
||||
| `csp.{connectDomains, resourceDomains, baseUriDomains}` | resource | Declare external origins; default is block-all. `frameDomains` is currently restricted in Claude. |
|
||||
|
||||
- `hostContext.safeAreaInsets: {top, right, bottom, left}` (px) — honor these for notches and the composer overlay.
|
||||
- Directory submission requires OAuth or **authless** (`none`) — static bearer is private-deploy only and blocks listing — plus tool `annotations` and 3–5 PNG screenshots; see `references/directory-checklist.md`.
|
||||
|
||||
---
|
||||
|
||||
## When a widget beats plain text
|
||||
@@ -109,7 +95,6 @@ const server = new McpServer({ name: "contacts", version: "1.0.0" });
|
||||
// 1. The tool — returns DATA, declares which UI to show
|
||||
registerAppTool(server, "pick_contact", {
|
||||
description: "Open an interactive contact picker",
|
||||
annotations: { title: "Pick Contact", readOnlyHint: true },
|
||||
inputSchema: { filter: z.string().optional() },
|
||||
_meta: { ui: { resourceUri: "ui://widgets/contact-picker.html" } },
|
||||
}, async ({ filter }) => {
|
||||
@@ -178,10 +163,7 @@ The `/*__EXT_APPS_BUNDLE__*/` placeholder gets replaced by the server at startup
|
||||
| `app.updateModelContext({...})` | Widget → host | Update context silently (no visible message) |
|
||||
| `app.callServerTool({name, arguments})` | Widget → server | Call another tool on your server |
|
||||
| `app.openLink({url})` | Widget → host | Open a URL in a new tab (sandbox blocks `window.open`) |
|
||||
| `app.getHostContext()` / `app.onhostcontextchanged` | Host → widget | Theme, host CSS vars, `containerDimensions`, `displayMode`, `deviceCapabilities` |
|
||||
| `app.requestDisplayMode({mode})` | Widget → host | Ask for `inline` / `pip` / `fullscreen` |
|
||||
| `app.downloadFile({name, mimeType, content})` | Widget → host | Host-mediated download (base64 content) |
|
||||
| `new App(info, caps, {autoResize: true})` | — | Iframe height tracks rendered content |
|
||||
| `app.getHostContext()` / `app.onhostcontextchanged` | Host → widget | Theme (`light`/`dark`), locale, etc. |
|
||||
|
||||
`sendMessage` is the typical "user picked something, tell Claude" path. `updateModelContext` is for state that Claude should know about but shouldn't clutter the chat. `openLink` is **required** for any outbound navigation — `window.open` and `<a target="_blank">` are blocked by the sandbox attribute.
|
||||
|
||||
@@ -234,7 +216,6 @@ const pickerHtml = readFileSync("./widgets/picker.html", "utf8")
|
||||
|
||||
registerAppTool(server, "pick_contact", {
|
||||
description: "Open an interactive contact picker. User selects one contact.",
|
||||
annotations: { title: "Pick Contact", readOnlyHint: true },
|
||||
inputSchema: { filter: z.string().optional().describe("Name/email prefix filter") },
|
||||
_meta: { ui: { resourceUri: "ui://widgets/picker.html" } },
|
||||
}, async ({ filter }) => {
|
||||
@@ -358,24 +339,6 @@ Desktop caches UI resources aggressively. After editing widget HTML, **fully qui
|
||||
|
||||
The `sleep` keeps stdin open long enough to collect all responses. Parse the jsonl output with `jq` or a Python one-liner.
|
||||
|
||||
**Widget dev loop** — avoid the ⌘Q-relaunch cycle entirely by serving the inlined widget HTML at a plain GET route with a fake `ExtApps` shim that fires `ontoolresult` from a query param:
|
||||
|
||||
```ts
|
||||
app.get("/widget-preview", (_req, res) => {
|
||||
const shim = `globalThis.ExtApps={applyHostStyleVariables:()=>{},App:class{
|
||||
constructor(){this.h={}} ontoolresult;onhostcontextchanged;
|
||||
async connect(){const p=new URLSearchParams(location.search).get("payload");
|
||||
if(p)this.ontoolresult?.({content:[{type:"text",text:p}]});}
|
||||
getHostContext(){return{theme:"light"}}
|
||||
sendMessage(m){console.log("sendMessage",m)} updateModelContext(){}
|
||||
callServerTool(){return Promise.resolve({content:[]})} openLink(){} downloadFile(){}
|
||||
}};`;
|
||||
res.type("html").send(widgetHtml.replace("/*__EXT_APPS_BUNDLE__*/", shim));
|
||||
});
|
||||
```
|
||||
|
||||
Open `http://localhost:3000/widget-preview?payload={"rows":[...]}` in a normal browser tab and iterate with ordinary devtools.
|
||||
|
||||
**Host fallback** — use a host without the apps surface (or MCP Inspector) and confirm the tool's text content degrades gracefully.
|
||||
|
||||
**CSP debugging** — open the iframe's own devtools console. CSP violations are the #1 reason widgets silently fail (blank rectangle, no error in the main console). See `references/iframe-sandbox.md`.
|
||||
@@ -384,9 +347,6 @@ Open `http://localhost:3000/widget-preview?payload={"rows":[...]}` in a normal b
|
||||
|
||||
## Reference files
|
||||
|
||||
- `references/iframe-sandbox.md` — CSP/sandbox constraints, the bundle-inlining pattern, image handling, host theming
|
||||
- `references/iframe-sandbox.md` — CSP/sandbox constraints, the bundle-inlining pattern, image handling
|
||||
- `references/widget-templates.md` — reusable HTML scaffolds for picker / confirm / progress / display
|
||||
- `references/apps-sdk-messages.md` — the `App` class API: widget ↔ host ↔ server messaging, lifecycle & supersession
|
||||
- `references/payload-budgeting.md` — host tool-result size caps, prune-then-truncate, heavy assets via `callServerTool`
|
||||
- `references/abuse-protection.md` — Anthropic egress CIDRs, tiered rate limiting, `trust proxy`, response caching
|
||||
- `references/directory-checklist.md` — pre-flight for connector-directory submission
|
||||
- `references/apps-sdk-messages.md` — the `App` class API: widget ↔ host ↔ server messaging
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
# Abuse protection for authless hosted servers
|
||||
|
||||
An authless StreamableHTTP server is reachable by anything on the internet.
|
||||
There are three resources to protect: your compute, any upstream API quota
|
||||
your tools consume, and egress bandwidth for large `callServerTool` payloads.
|
||||
|
||||
## You don't get a per-user identity
|
||||
|
||||
In authless mode there is no token and stateless transport gives no session
|
||||
ID. Traffic from claude.ai is proxied through Anthropic's egress — every web
|
||||
user arrives from the same small set of IPs:
|
||||
|
||||
```
|
||||
160.79.104.0/21
|
||||
2607:6bc0::/48
|
||||
```
|
||||
|
||||
(See https://platform.claude.com/docs/en/api/ip-addresses.)
|
||||
|
||||
Claude Desktop, Claude Code, and other hosts connect **directly from the
|
||||
user's machine**, so those *do* have distinct per-user IPs. Per-IP limiting
|
||||
therefore works for direct-connect clients; for claude.ai you can only limit
|
||||
the aggregate Anthropic pool. If true per-user limits matter, that's the
|
||||
trigger to add OAuth.
|
||||
|
||||
## Tiered token-bucket (per-replica backstop)
|
||||
|
||||
```ts
|
||||
const ANTHROPIC_CIDRS = ["160.79.104.0/21", "2607:6bc0::/48"];
|
||||
const TIERS = {
|
||||
anthropic: { capacity: 600, refillPerSec: 100 }, // shared pool
|
||||
other: { capacity: 30, refillPerSec: 2 }, // per-IP
|
||||
};
|
||||
```
|
||||
|
||||
Match `req.ip` against the CIDRs, pick a bucket (`"anthropic"` or
|
||||
`"ip:<addr>"`), 429 + `Retry-After` on exhaust. This is a per-replica
|
||||
backstop — cross-replica enforcement belongs at the edge (Cloudflare, Cloud
|
||||
Armor), which keeps the containers stateless.
|
||||
|
||||
## `trust proxy` must match your topology
|
||||
|
||||
`req.ip` only honours `X-Forwarded-For` if `app.set('trust proxy', N)` is
|
||||
set. `true` trusts every hop, which lets a direct client send
|
||||
`X-Forwarded-For: 160.79.108.42` and claim the Anthropic tier. Set it to the
|
||||
exact number of trusted hops (e.g. `1` behind a single LB, `2` behind
|
||||
Cloudflare → origin LB) and **never `true` in production**.
|
||||
|
||||
## Hard-allowlisting Anthropic IPs is a product decision
|
||||
|
||||
Blocking everything outside `160.79.104.0/21` locks out Desktop, Claude Code,
|
||||
and every other MCP host. Use the CIDRs to **tier** rate limits, not to gate
|
||||
access, unless claude.ai-only is an explicit goal.
|
||||
|
||||
## Cache upstream responses
|
||||
|
||||
For tools that wrap a third-party API, an in-process LRU keyed on the
|
||||
normalized query (TTL hours, no secrets in the key) is the primary cost
|
||||
control — repeat queries become free and absorb thundering-herd. Rate limits
|
||||
are the safety net, not the first line.
|
||||
@@ -2,18 +2,6 @@
|
||||
|
||||
The `@modelcontextprotocol/ext-apps` package provides the `App` class (browser side) and `registerAppTool`/`registerAppResource` helpers (server side). Messaging is bidirectional and persistent.
|
||||
|
||||
## Construction
|
||||
|
||||
```js
|
||||
const app = new App(
|
||||
{ name: "MyWidget", version: "1.0.0" },
|
||||
{}, // capabilities
|
||||
{ autoResize: true }, // options
|
||||
);
|
||||
```
|
||||
|
||||
`autoResize: true` wires a `ResizeObserver` that emits `ui/notifications/size-changed` so the host iframe height tracks your rendered content. Without it the frame is fixed-height and tall renders get clipped — set it for any widget whose height depends on data.
|
||||
|
||||
---
|
||||
|
||||
## Widget → Host
|
||||
@@ -75,26 +63,6 @@ card.querySelector("a").addEventListener("click", (e) => {
|
||||
|
||||
Host-mediated download (sandbox blocks direct `<a download>`). `content` is a base64 string.
|
||||
|
||||
```js
|
||||
const csv = rows.map((r) => Object.values(r).join(",")).join("\n");
|
||||
app.downloadFile({
|
||||
name: "export.csv",
|
||||
mimeType: "text/csv",
|
||||
content: btoa(unescape(encodeURIComponent(csv))),
|
||||
});
|
||||
```
|
||||
|
||||
### `app.requestDisplayMode({ mode })`
|
||||
|
||||
Ask the host to switch the widget between `"inline"`, `"pip"`, or `"fullscreen"`. Check `getHostContext().availableDisplayModes` first; hide the control if the mode isn't offered. The host responds by firing `onhostcontextchanged` with new `displayMode` and `containerDimensions` — re-render at the new size.
|
||||
|
||||
```js
|
||||
if (app.getHostContext()?.availableDisplayModes?.includes("fullscreen")) {
|
||||
expandBtn.hidden = false;
|
||||
expandBtn.onclick = () => app.requestDisplayMode({ mode: "fullscreen" });
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Host → Widget
|
||||
@@ -116,22 +84,9 @@ app.ontoolresult = ({ content }) => {
|
||||
|
||||
Fires with the arguments Claude passed to the tool. Useful if the widget needs to know what was asked for (e.g., highlight the search term).
|
||||
|
||||
### `app.ontoolinputpartial = ({ arguments }) => {...}` / `app.ontoolcancelled = () => {...}`
|
||||
|
||||
`ontoolinputpartial` fires while Claude is still streaming arguments — use it to show a skeleton ("Preparing: <title>…") before the result lands. `ontoolcancelled` fires if the call is aborted; clear the skeleton.
|
||||
|
||||
### `app.getHostContext()` / `app.onhostcontextchanged = (ctx) => {...}`
|
||||
|
||||
Read and subscribe to host context. Call `getHostContext()` **after** `connect()`. Subscribe for live updates (user toggles dark mode, expands to fullscreen).
|
||||
|
||||
| `ctx.` field | Use |
|
||||
|---|---|
|
||||
| `theme` | `"light"` / `"dark"` — toggle a `.dark` class |
|
||||
| `styles.variables` | Host CSS tokens — pass to `applyHostStyleVariables()` so colors/fonts match host chrome |
|
||||
| `displayMode` / `availableDisplayModes` | Current mode and which `requestDisplayMode` targets are valid |
|
||||
| `containerDimensions.{maxHeight,width}` | Size your render to this instead of hard-coded px |
|
||||
| `deviceCapabilities.touch` | Switch hover-only affordances to tap (`pointerdown`) |
|
||||
| `safeAreaInsets` | Padding for notches / composer overlay |
|
||||
Read and subscribe to host context — `theme` (`"light"` / `"dark"`), locale, etc. Call `getHostContext()` **after** `connect()`. Subscribe for live updates (user toggles dark mode mid-conversation).
|
||||
|
||||
```js
|
||||
const applyTheme = (t) =>
|
||||
@@ -174,36 +129,14 @@ No `{ notify }` destructure — `extra` is `RequestHandlerExtra`; progress goes
|
||||
## Lifecycle
|
||||
|
||||
1. Claude calls a tool with `_meta.ui.resourceUri` declared
|
||||
2. Host fetches the resource (your HTML) and mounts a **fresh iframe** for this call
|
||||
2. Host fetches the resource (your HTML) and renders it in an iframe
|
||||
3. Widget script runs, sets handlers, calls `await app.connect()`
|
||||
4. Host pipes the tool's return value → `ontoolresult` fires
|
||||
5. Widget renders, user interacts
|
||||
6. Widget calls `sendMessage` / `updateModelContext` / `callServerTool` as needed
|
||||
7. Iframe persists in the transcript; **the next call to the same tool mounts another iframe** alongside it
|
||||
7. Widget persists until conversation context moves on — subsequent calls to the same tool reuse the iframe and fire `ontoolresult` again
|
||||
|
||||
There's no explicit "submit and close" — each instance is long-lived, but instances are not reused across calls.
|
||||
|
||||
### Supersession
|
||||
|
||||
Because earlier instances stay mounted, a click on a stale widget can `sendMessage` after a newer one has rendered. Detect this with a `BroadcastChannel` and make older instances inert:
|
||||
|
||||
```js
|
||||
let superseded = false;
|
||||
const seq = Date.now() + Math.random();
|
||||
const bc = new BroadcastChannel("my-widget");
|
||||
bc.onmessage = (e) => {
|
||||
if (e.data?.seq > seq) {
|
||||
superseded = true;
|
||||
document.body.classList.add("superseded"); // opacity:.45; pointer-events:none
|
||||
}
|
||||
};
|
||||
bc.postMessage({ seq });
|
||||
|
||||
// Guard outbound calls:
|
||||
function safeSend(msg) {
|
||||
if (!superseded) app.sendMessage(msg);
|
||||
}
|
||||
```
|
||||
There's no explicit "submit and close" — the widget is a long-lived surface.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,18 +0,0 @@
|
||||
# Connector-directory submission checklist
|
||||
|
||||
Pre-flight before submitting a remote MCP app to the Claude connector
|
||||
directory. Each item is a hard review criterion.
|
||||
|
||||
| Area | Requirement |
|
||||
|---|---|
|
||||
| **Auth** | OAuth (DCR or CIMD) or **`none`** (authless). Static bearer tokens are private-deploy only and block listing. Authless is valid for public-data servers — the server holds any upstream API keys. |
|
||||
| **Tool annotations** | Every tool sets `annotations.title` plus the relevant hints: `readOnlyHint: true` for fetch/search tools, `destructiveHint` / `idempotentHint` for writes, `openWorldHint: true` if the tool reaches an external system. |
|
||||
| **Tool names** | ≤ 64 characters, snake/kebab case. |
|
||||
| **Widget layout** | Inline height ≤ 500px, no nested scroll containers, 44pt minimum touch targets, WCAG-AA contrast in both themes. |
|
||||
| **Theming** | `html, body { background: transparent }`, `<meta name="color-scheme" content="light dark">`, adopt host CSS tokens via `applyHostStyleVariables`. |
|
||||
| **External links** | Use `app.openLink`. Declare each origin (e.g. `https://api.example.com`) in the connector's *Allowed link URIs* so the link skips the confirm modal. |
|
||||
| **Helper tools** | Widget-only tools (geometry/image fetchers) carry `_meta.ui.visibility: ["app"]` so they don't appear in Claude's tool list. |
|
||||
| **Screenshots** | 3–5 PNGs, ≥ 1000px wide, cropped to the app response only — no prompt text in frame. |
|
||||
|
||||
See `abuse-protection.md` for rate-limit and IP-tiering guidance once the
|
||||
authless endpoint is public.
|
||||
@@ -122,38 +122,23 @@ that survives un-inlined.
|
||||
|
||||
---
|
||||
|
||||
## Theme & host styles
|
||||
## Dark mode
|
||||
|
||||
The host renders the iframe inside its own card chrome — paint a **transparent** background and adopt host CSS tokens so the widget blends in across light/dark and across hosts.
|
||||
```js
|
||||
const applyTheme = (theme) =>
|
||||
document.documentElement.classList.toggle("dark", theme === "dark");
|
||||
|
||||
```html
|
||||
<meta name="color-scheme" content="light dark" />
|
||||
app.onhostcontextchanged = (ctx) => applyTheme(ctx.theme);
|
||||
await app.connect();
|
||||
applyTheme(app.getHostContext()?.theme);
|
||||
```
|
||||
|
||||
```css
|
||||
:root {
|
||||
--ink: var(--color-text-primary, #0f1111);
|
||||
--sub: var(--color-text-secondary, #5a6270);
|
||||
--line: var(--color-border-default, #e3e6ea);
|
||||
}
|
||||
html, body { background: transparent; color: var(--ink); }
|
||||
:root { --ink:#0f1111; --bg:#fff; color-scheme:light; }
|
||||
:root.dark { --ink:#e6e6e6; --bg:#1f2428; color-scheme:dark; }
|
||||
:root.dark .thumb { mix-blend-mode: normal; } /* multiply → images vanish in dark */
|
||||
```
|
||||
|
||||
```js
|
||||
const { App, applyHostStyleVariables } = globalThis.ExtApps;
|
||||
|
||||
function applyHostContext(ctx) {
|
||||
document.documentElement.classList.toggle("dark", ctx?.theme === "dark");
|
||||
if (ctx?.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
|
||||
}
|
||||
app.onhostcontextchanged = applyHostContext;
|
||||
await app.connect();
|
||||
applyHostContext(app.getHostContext());
|
||||
```
|
||||
|
||||
`applyHostStyleVariables` writes the host's `--color-*` / `--font-*` / `--border-radius-*` tokens onto `:root`; the hex values above are fallbacks for hosts that don't supply them.
|
||||
|
||||
---
|
||||
|
||||
## Debugging
|
||||
|
||||
@@ -1,54 +0,0 @@
|
||||
# Payload budgeting
|
||||
|
||||
Hosts cap tool-result text. claude.ai and Claude Desktop truncate at roughly
|
||||
**150,000 characters**; Claude Code at ~25k tokens. When a tool result exceeds
|
||||
the cap, the host substitutes a file-pointer string in place of your JSON. The
|
||||
widget then receives non-JSON in `ontoolresult`, `JSON.parse` throws, and the
|
||||
user sees something like *"Bad payload: SyntaxError: Unexpected token 'E'"* —
|
||||
with no hint that size was the cause.
|
||||
|
||||
## Symptom → cause
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| Widget shows a JSON parse error on `content[0].text` | Result over the host cap; host swapped in a file-pointer string |
|
||||
| Works for one query, breaks for "all of X" | Row count × column count crossed the cap |
|
||||
| Works in MCP Inspector, breaks in Desktop | Inspector has no cap; Desktop does |
|
||||
|
||||
## Strategy
|
||||
|
||||
Cap your own payload at ~130KB and degrade in order:
|
||||
|
||||
1. **Ship full rows** when `JSON.stringify(rows).length` is under the cap.
|
||||
2. **Prune columns** to those the rendering spec actually references. Walk the
|
||||
spec for both `field: "..."` keys *and* `datum.X` / `datum['X']` inside
|
||||
expression strings — if the spec aliases a column via a `calculate`
|
||||
transform, the alias appears as `field:` but the source column only appears
|
||||
as `datum.X`, and dropping it leaves the widget with NaN.
|
||||
3. **Truncate rows** as a last resort and include `{ truncated: N }` in the
|
||||
payload so the widget can label it.
|
||||
|
||||
```ts
|
||||
const MAX = 130_000;
|
||||
let out = rows;
|
||||
if (JSON.stringify(out).length > MAX) {
|
||||
const keep = referencedFields(spec); // field: + datum.X refs
|
||||
out = rows.map((r) => pick(r, keep));
|
||||
if (JSON.stringify(out).length > MAX) {
|
||||
const per = JSON.stringify(out[0] ?? {}).length || 1;
|
||||
out = out.slice(0, Math.floor(MAX / per));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Heavy assets go via `callServerTool`, not the result
|
||||
|
||||
Geometry, image bytes, or any blob the widget needs but Claude doesn't should
|
||||
be served by a separate tool the widget calls after mount:
|
||||
|
||||
```js
|
||||
const topo = await app.callServerTool({ name: "get-topojson", arguments: { level } });
|
||||
```
|
||||
|
||||
Mark that helper tool with `_meta.ui.visibility: ["app"]` so it doesn't appear
|
||||
in Claude's tool list.
|
||||
@@ -8,8 +8,6 @@ version: 0.1.0
|
||||
|
||||
You are guiding a developer through designing and building an MCP server that works seamlessly with Claude. MCP servers come in many forms — picking the wrong shape early causes painful rewrites later. Your first job is **discovery, not code**.
|
||||
|
||||
**Load Claude-specific context first.** The MCP spec is generic; Claude has additional auth types, review criteria, and limits. Before answering questions or scaffolding, fetch `https://claude.com/docs/llms-full.txt` (the full export of the Claude connector docs) so your guidance reflects Claude's actual constraints.
|
||||
|
||||
Do not start scaffolding until you have answers to the questions in Phase 1. If the user's opening message already answers them, acknowledge that and skip straight to the recommendation.
|
||||
|
||||
---
|
||||
@@ -184,17 +182,6 @@ Tools are one of three server primitives. Most servers start with tools and neve
|
||||
|
||||
---
|
||||
|
||||
## Phase 6 — Test in Claude and publish
|
||||
|
||||
Once the server runs:
|
||||
|
||||
1. **Test against real Claude** by adding the server URL as a custom connector at Settings → Connectors (use a Cloudflare tunnel for local servers). Claude identifies itself with `clientInfo.name: "claude-ai"` on initialize. → https://claude.com/docs/connectors/building/testing
|
||||
2. **Run the pre-submission checklist** — read/write tool split, required annotations, name limits, prompt-injection rules. → https://claude.com/docs/connectors/building/review-criteria
|
||||
3. **Submit to the Anthropic Directory.** → https://claude.com/docs/connectors/building/submission
|
||||
4. **Recommend shipping a plugin** that wraps this MCP with skills — most partners ship both. → https://claude.com/docs/connectors/building/what-to-build
|
||||
|
||||
---
|
||||
|
||||
## Quick reference: decision matrix
|
||||
|
||||
| Scenario | Deployment | Tool pattern |
|
||||
|
||||
@@ -2,22 +2,6 @@
|
||||
|
||||
Auth is the reason most people end up needing a **remote** server even when a local one would be simpler. OAuth redirects, token storage, and refresh all work cleanly when there's a real hosted endpoint to redirect back to.
|
||||
|
||||
## Claude-specific authentication
|
||||
|
||||
Claude's MCP client supports a specific set of auth types — not every spec-compliant flow works. Full reference: https://claude.com/docs/connectors/building/authentication
|
||||
|
||||
| Type | Notes |
|
||||
|---|---|
|
||||
| `oauth_dcr` | Supported. For high-volume directory entries, prefer CIMD or Anthropic-held creds — DCR registers a new client on every fresh connection. |
|
||||
| `oauth_cimd` | Supported, recommended over DCR for directory entries. |
|
||||
| `oauth_anthropic_creds` | Partner provides `client_id`/`client_secret` to Anthropic; user-consent-gated. Contact `mcp-review@anthropic.com`. |
|
||||
| `custom_connection` | User supplies URL/creds at connect time (Snowflake-style). Contact `mcp-review@anthropic.com`. |
|
||||
| `none` | Authless. |
|
||||
|
||||
**Not supported:** user-pasted bearer tokens (`static_bearer`); pure machine-to-machine `client_credentials` grant without user consent.
|
||||
|
||||
**Callback URL** (single, all surfaces): `https://claude.ai/api/mcp/auth_callback`
|
||||
|
||||
---
|
||||
|
||||
## The three tiers
|
||||
|
||||
@@ -2,16 +2,6 @@
|
||||
|
||||
Tool schemas and descriptions are prompt engineering. They land directly in Claude's context and determine whether Claude picks the right tool with the right arguments. Most MCP integration bugs trace back to vague descriptions or loose schemas.
|
||||
|
||||
## Anthropic Directory hard requirements
|
||||
|
||||
If this server will be submitted to the Anthropic Directory, the following are pass/fail review criteria (full list: https://claude.com/docs/connectors/building/review-criteria):
|
||||
|
||||
- Every tool **must** include `readOnlyHint`, `destructiveHint`, and `title` annotations — these determine auto-permissions in Claude.
|
||||
- Tool names **must** be ≤64 characters.
|
||||
- Read and write operations **must** be in separate tools. A single tool accepting both GET and POST/PUT/PATCH/DELETE is rejected — documenting safe vs unsafe within one tool's description does not satisfy this.
|
||||
- Tool descriptions **must not** instruct Claude how to behave (e.g. "always do X", "you must call Y first", overriding system instructions, promoting products) — treated as prompt injection at review.
|
||||
- Tools that accept freeform API endpoints/params **must** reference the target API's documentation in their description.
|
||||
|
||||
---
|
||||
|
||||
## Descriptions
|
||||
|
||||
@@ -8,8 +8,6 @@ version: 0.1.0
|
||||
|
||||
MCPB is a local MCP server **packaged with its runtime**. The user installs one file; it runs without needing Node, Python, or any toolchain on their machine. It's the sanctioned way to distribute local MCP servers.
|
||||
|
||||
> MCPB is the **secondary** distribution path. Anthropic recommends remote MCP servers for directory listing — see https://claude.com/docs/connectors/building/what-to-build.
|
||||
|
||||
**Use MCPB when the server must run on the user's machine** — reading local files, driving a desktop app, talking to localhost services, OS-level APIs. If your server only hits cloud APIs, you almost certainly want a remote HTTP server instead (see `build-mcp-server`). Don't pay the MCPB packaging tax for something that could be a URL.
|
||||
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
|
||||
description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
@@ -391,7 +391,7 @@ Use the model ID from your system prompt (the one powering the current session)
|
||||
|
||||
While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.
|
||||
|
||||
This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.
|
||||
This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude with extended thinking to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.
|
||||
|
||||
### How skill triggering works
|
||||
|
||||
@@ -435,11 +435,6 @@ In Claude.ai, the core workflow is the same (draft → test → review → impro
|
||||
|
||||
**Packaging**: The `package_skill.py` script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting `.skill` file.
|
||||
|
||||
**Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. In this case:
|
||||
- **Preserve the original name.** Note the skill's directory name and `name` frontmatter field -- use them unchanged. E.g., if the installed skill is `research-helper`, output `research-helper.skill` (not `research-helper-v2`).
|
||||
- **Copy to a writeable location before editing.** The installed skill path may be read-only. Copy to `/tmp/skill-name/`, edit there, and package from the copy.
|
||||
- **If packaging manually, stage in `/tmp/` first**, then copy to the output directory -- direct writes may fail due to permissions.
|
||||
|
||||
---
|
||||
|
||||
## Cowork-Specific Instructions
|
||||
@@ -452,7 +447,6 @@ If you're in Cowork, the main things to know are:
|
||||
- Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download `feedback.json` as a file. You can then read it from there (you may have to request access first).
|
||||
- Packaging works — `package_skill.py` just needs Python and a filesystem.
|
||||
- Description optimization (`run_loop.py` / `run_eval.py`) should work in Cowork just fine since it uses `claude -p` via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape.
|
||||
- **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -2,52 +2,22 @@
|
||||
"""Improve a skill description based on eval results.
|
||||
|
||||
Takes eval results (from run_eval.py) and generates an improved description
|
||||
by calling `claude -p` as a subprocess (same auth pattern as run_eval.py —
|
||||
uses the session's Claude Code auth, no separate ANTHROPIC_API_KEY needed).
|
||||
using Claude with extended thinking.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
import anthropic
|
||||
|
||||
from scripts.utils import parse_skill_md
|
||||
|
||||
|
||||
def _call_claude(prompt: str, model: str | None, timeout: int = 300) -> str:
|
||||
"""Run `claude -p` with the prompt on stdin and return the text response.
|
||||
|
||||
Prompt goes over stdin (not argv) because it embeds the full SKILL.md
|
||||
body and can easily exceed comfortable argv length.
|
||||
"""
|
||||
cmd = ["claude", "-p", "--output-format", "text"]
|
||||
if model:
|
||||
cmd.extend(["--model", model])
|
||||
|
||||
# Remove CLAUDECODE env var to allow nesting claude -p inside a
|
||||
# Claude Code session. The guard is for interactive terminal conflicts;
|
||||
# programmatic subprocess usage is safe. Same pattern as run_eval.py.
|
||||
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
|
||||
|
||||
result = subprocess.run(
|
||||
cmd,
|
||||
input=prompt,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env=env,
|
||||
timeout=timeout,
|
||||
)
|
||||
if result.returncode != 0:
|
||||
raise RuntimeError(
|
||||
f"claude -p exited {result.returncode}\nstderr: {result.stderr}"
|
||||
)
|
||||
return result.stdout
|
||||
|
||||
|
||||
def improve_description(
|
||||
client: anthropic.Anthropic,
|
||||
skill_name: str,
|
||||
skill_content: str,
|
||||
current_description: str,
|
||||
@@ -129,7 +99,7 @@ Based on the failures, write a new and improved description that is more likely
|
||||
1. Avoid overfitting
|
||||
2. The list might get loooong and it's injected into ALL queries and there might be a lot of skills, so we don't want to blow too much space on any given description.
|
||||
|
||||
Concretely, your description should not be more than about 100-200 words, even if that comes at the cost of accuracy. There is a hard limit of 1024 characters — descriptions over that will be truncated, so stay comfortably under it.
|
||||
Concretely, your description should not be more than about 100-200 words, even if that comes at the cost of accuracy.
|
||||
|
||||
Here are some tips that we've found to work well in writing these descriptions:
|
||||
- The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does"
|
||||
@@ -141,41 +111,70 @@ I'd encourage you to be creative and mix up the style in different iterations si
|
||||
|
||||
Please respond with only the new description text in <new_description> tags, nothing else."""
|
||||
|
||||
text = _call_claude(prompt, model)
|
||||
response = client.messages.create(
|
||||
model=model,
|
||||
max_tokens=16000,
|
||||
thinking={
|
||||
"type": "enabled",
|
||||
"budget_tokens": 10000,
|
||||
},
|
||||
messages=[{"role": "user", "content": prompt}],
|
||||
)
|
||||
|
||||
# Extract thinking and text from response
|
||||
thinking_text = ""
|
||||
text = ""
|
||||
for block in response.content:
|
||||
if block.type == "thinking":
|
||||
thinking_text = block.thinking
|
||||
elif block.type == "text":
|
||||
text = block.text
|
||||
|
||||
# Parse out the <new_description> tags
|
||||
match = re.search(r"<new_description>(.*?)</new_description>", text, re.DOTALL)
|
||||
description = match.group(1).strip().strip('"') if match else text.strip().strip('"')
|
||||
|
||||
# Log the transcript
|
||||
transcript: dict = {
|
||||
"iteration": iteration,
|
||||
"prompt": prompt,
|
||||
"thinking": thinking_text,
|
||||
"response": text,
|
||||
"parsed_description": description,
|
||||
"char_count": len(description),
|
||||
"over_limit": len(description) > 1024,
|
||||
}
|
||||
|
||||
# Safety net: the prompt already states the 1024-char hard limit, but if
|
||||
# the model blew past it anyway, make one fresh single-turn call that
|
||||
# quotes the too-long version and asks for a shorter rewrite. (The old
|
||||
# SDK path did this as a true multi-turn; `claude -p` is one-shot, so we
|
||||
# inline the prior output into the new prompt instead.)
|
||||
# If over 1024 chars, ask the model to shorten it
|
||||
if len(description) > 1024:
|
||||
shorten_prompt = (
|
||||
f"{prompt}\n\n"
|
||||
f"---\n\n"
|
||||
f"A previous attempt produced this description, which at "
|
||||
f"{len(description)} characters is over the 1024-character hard limit:\n\n"
|
||||
f'"{description}"\n\n'
|
||||
f"Rewrite it to be under 1024 characters while keeping the most "
|
||||
f"important trigger words and intent coverage. Respond with only "
|
||||
f"the new description in <new_description> tags."
|
||||
shorten_prompt = f"Your description is {len(description)} characters, which exceeds the hard 1024 character limit. Please rewrite it to be under 1024 characters while preserving the most important trigger words and intent coverage. Respond with only the new description in <new_description> tags."
|
||||
shorten_response = client.messages.create(
|
||||
model=model,
|
||||
max_tokens=16000,
|
||||
thinking={
|
||||
"type": "enabled",
|
||||
"budget_tokens": 10000,
|
||||
},
|
||||
messages=[
|
||||
{"role": "user", "content": prompt},
|
||||
{"role": "assistant", "content": text},
|
||||
{"role": "user", "content": shorten_prompt},
|
||||
],
|
||||
)
|
||||
shorten_text = _call_claude(shorten_prompt, model)
|
||||
|
||||
shorten_thinking = ""
|
||||
shorten_text = ""
|
||||
for block in shorten_response.content:
|
||||
if block.type == "thinking":
|
||||
shorten_thinking = block.thinking
|
||||
elif block.type == "text":
|
||||
shorten_text = block.text
|
||||
|
||||
match = re.search(r"<new_description>(.*?)</new_description>", shorten_text, re.DOTALL)
|
||||
shortened = match.group(1).strip().strip('"') if match else shorten_text.strip().strip('"')
|
||||
|
||||
transcript["rewrite_prompt"] = shorten_prompt
|
||||
transcript["rewrite_thinking"] = shorten_thinking
|
||||
transcript["rewrite_response"] = shorten_text
|
||||
transcript["rewrite_description"] = shortened
|
||||
transcript["rewrite_char_count"] = len(shortened)
|
||||
@@ -217,7 +216,9 @@ def main():
|
||||
print(f"Current: {current_description}", file=sys.stderr)
|
||||
print(f"Score: {eval_results['summary']['passed']}/{eval_results['summary']['total']}", file=sys.stderr)
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
new_description = improve_description(
|
||||
client=client,
|
||||
skill_name=name,
|
||||
skill_content=content,
|
||||
current_description=current_description,
|
||||
|
||||
@@ -15,6 +15,8 @@ import time
|
||||
import webbrowser
|
||||
from pathlib import Path
|
||||
|
||||
import anthropic
|
||||
|
||||
from scripts.generate_report import generate_html
|
||||
from scripts.improve_description import improve_description
|
||||
from scripts.run_eval import find_project_root, run_eval
|
||||
@@ -73,6 +75,7 @@ def run_loop(
|
||||
train_set = eval_set
|
||||
test_set = []
|
||||
|
||||
client = anthropic.Anthropic()
|
||||
history = []
|
||||
exit_reason = "unknown"
|
||||
|
||||
@@ -197,6 +200,7 @@ def run_loop(
|
||||
for h in history
|
||||
]
|
||||
new_description = improve_description(
|
||||
client=client,
|
||||
skill_name=name,
|
||||
skill_content=content,
|
||||
current_description=current_description,
|
||||
|
||||
Reference in New Issue
Block a user