shipit-skill — pipeline de lancement en un passage pour outils de développement
Faites passer un dépôt existant de « ça marche » à publié + listé + commercialisable. Quatre phases, chacune avec un critère de sortie strict. Il est permis de sauter une phase uniquement si son critère de sortie est déjà rempli.
Philosophie : regarder avant de construire. Vérifiez d'abord ce qui existe déjà et ce que l'écosystème exige — comme vous conseilleriez à tout utilisateur de ne pas réinventer la roue.
Phase 0 — Reconnaissance (30 s, toujours)
Effectuez ces vérifications avant de toucher à quoi que ce soit :
- État du dépôt —
git status,git remote -v,git logrécent. - Enregistrement du package — le nom est-il pris ? (
pip index versions <nom>,npm view <nom>, CDN des registres). Les collisions de noms sont fréquentes ; les noms scopés pour npm (@org/pkg) évitent les règles de typosquatting. - Projets similaires — recherchez sur GitHub les concurrents directs. S'il en existe un, notez explicitement la différenciation ; ne créez pas de copie conforme.
- Les lacunes des « critères de sortie » — CI ? Dockerfile ? GitHub Release ? listé sur Glama / les répertoires awesome ? matériel promotionnel à jour ? Établissez une liste de contrôle de ce qui manque. Cette liste pilote le reste.
Sortie : un court rapport d'écart + un plan. Obtenez une confirmation avant la Phase 1 si les écarts sont importants.
Phase 1 — Base technique
Critère de sortie : CI verte sur la branche par défaut, métadonnées du package correctes, Dockerfile présent (s'il s'agit d'un serveur MCP/CLI).
- CI : ajoutez GitHub Actions. Python : matrice sur les versions supportées, mais faites
attention aux extras qui nécessitent un interpréteur plus récent (par ex.
mcp>=2.0nécessite py3.10+ — exécutez la base sur 3.9, les extras sur 3.12). Incluez toujours lint + tests + un job de poignée de main MCP conteneurisé si un serveur est livré. - Dockerfile : nécessaire pour Glama et les utilisateurs de conteneurs. Pour les serveurs
MCP stdio : image de base + installation du package +
CMD [la-commande-du-serveur]. Construisez à partir des sources (COPY src) sauf si le package publié est vérifié comme bon — une version PyPI/npm obsolète cassera silencieusement l'introspection. .dockerignore: gardez l'image minimale (pas de.git, tests, promo, docs).- Version depuis les métadonnées :
serverInfo.versionde MCP et--versiondu CLI doivent lire la version du package, pas une chaîne codée en dur. - Seuil de dépendance : si votre code cible une nouvelle API du SDK, fixez le seuil de
dépendance (
mcp>=2.0), ne laissez pas>=1.0— pip/npm résolvent la dernière version et cassent les nouvelles installations.
Vérifiez : pip install .[extras] / npm install propre dans un venv temporaire, puis
lancez la poignée de main MCP (initialize + tools/list) contre le conteneur.
Phase 2 — Publication
Critère de sortie : package sur le registre, GitHub Release avec tag + notes, installation dans un environnement propre vérifiée.
- Incrémentation de version → artefacts de build (
python -m build/npm pack). - Tag + GitHub Release : titre
vX.Y.Z, notes avec Changements / Installation / Corrections. Laissezgh release createrattacher au tag. - Publication sur le registre :
- PyPI : nécessite un token (granulaire, limité au package, permission Upload).
Si le token est mal formé, PyPI renvoie
403 Invalid or non-existent authentication information— les chaînes au format UUID sont erronées ; les vrais tokens PyPI commencent parpypi-.twine uploadavec--username __token__. - npm : les noms scopés nécessitent l'existence de l'organisation ; token granulaire avec
contournement de la 2FA pour l'automatisation ;
--//registry.npmjs.org/:_authTokenen ligne évite d'écrire les identifiants sur le disque.
- PyPI : nécessite un token (granulaire, limité au package, permission Upload).
Si le token est mal formé, PyPI renvoie
- Vérification d'installation fraîche (non négociable) : créez un venv / répertoire propre, installez depuis le registre, importez le module / exécutez le CLI / faites la poignée de main MCP. Cela détecte les bugs d'empaquetage « ça marche sur ma machine ».
- Pièges :
- Le CDN npm sert des 404 en cache pendant plusieurs minutes après la première publication — pas de panique, videz le cache avec un paramètre de requête.
File already existslors d'une nouvelle tentative signifie généralement que la première tentative a réussi.- Dérive du fichier de verrouillage : renommer les packages → toujours
npm installpour regénérer le lock ounpm ciéchoue dans le CI.
Phase 3 — Inscriptions dans les annuaires
Critère de sortie : listé sur Glama avec un badge de score et PR awesome ouverte (ou fusionnée).
- Glama (
glama.ai/mcp/servers) : l'utilisateur soumet via le navigateur (OAuth GitHub — ne peut pas être automatisé). Avant de soumettre : le Dockerfile doit exister et passer l'introspection (voir Phase 1). Après la soumission : la page met quelques minutes à quelques heures à apparaître — interrogezhttps://glama.ai/mcp/servers/<propriétaire>/<dépôt>et/badges/score.svg. Ajoutez le badge au README du dépôt une fois en ligne :[](https://glama.ai/mcp/servers/propriétaire/dépôt) - awesome-mcp-servers (et listes organisées similaires) : les PR sont triées par des bots.
Formatez selon la convention actuelle de la liste (badge + lang + scope + OS + commande
d'installation). Les mainteneurs exigent désormais le badge Glama dans l'entrée — soumettez
Glama en premier. Ajoutez
🤖🤖🤖au titre de la PR pour opter pour la voie rapide agent. Fork → branche à partir du dernier main en amont → ajoutez l'entrée → PR. Si une PR précédente a été fermée pour inactivité, force-push la branche ou recréez-la. - Autres annuaires (Smithery, PulseMCP, mcp.so…) : Smithery lit un
smithery.yamlà la racine du dépôt (commande de démarrage stdio + schéma d'environnement optionnel).
Phase 4 — Matériel promotionnel
Critère de sortie : les versions/liens/numéros de PR des documents promotionnels correspondent à la réalité ; les publications par plateforme sont prêtes à coller (l'utilisateur publie manuellement — pas d'automatisation factice).
- Maintenez
promo/avec des fichiers par plateforme (V2EX, Zhihu, Reddit, X, communauté). - Vérification de fraîcheur (à exécuter quand les versions/PR changent) : grep les fichiers promo pour les anciens numéros de version, les liens de PR morts, les URL de release obsolètes. Mettez à jour ou marquez comme obsolètes.
- Discipline des faits : vérifiez chaque nombre/affirmation avant de publier — réexécutez l'outil et comparez la sortie. Des affirmations erronées sont démolies dans les commentaires (par exemple, une affirmation « pas de LICENSE » qui n'est en fait qu'un caprice des métadonnées GitHub).
- Gardez les commandes d'installation non épinglées (
pip install pkg) pour que la promo ne pourrisse pas.
Référence rapide du CLI (shipit-skill)
Exécutez ces commandes pour faire passer un dépôt à travers les phases. Tout est print
seulement par défaut ; les variantes avec effets de bord sont activées via --execute.
| Commande | Fait | Auto / print |
|---|---|---|
doctor [--json] | auto-vérification de l'environnement : gh authentifié, tokens définis, arbre propre sur main | print ; exit 1 si lacunes |
preflight [--dir .] [--version X.Y.Z] [--json] | rapport d'écart pour le lancement | |
init <dir> --server <srv> --pkg <pkg> [--force] [--dry-run] | échafaudage CI/Dockerfile/smithery.yaml/promo | écrit des fichiers |
ci --lang python [--server srv] [--write chemin] [--release] | génère ci.yml ; --release génère release.yml | print / écrit |
| `bump patch | minor | major |
release --lang python --pkg <pkg> [--repo o/r] [--execute] | doctor gate → bump→build→publication→tag→gh release→vérification promo. Tag/Release créés uniquement après la réussite de la publication ; l'échec de la publication annule le commit ; les réexécutions ignorent les tags/releases existants ; notes depuis CHANGELOG | print / execute |
publish --lang python --pkg <pkg> [--server srv] [--execute] | upload sur le registre (token depuis la variable d'env PYPI_TOKEN/NPM_TOKEN) + vérification d'installation fraîche | print / execute |
check-promo --dir promo --version X.Y.Z [--prs id=état,...] [--no-links] [--report] [--fix] | versions obsolètes / PR inconnues / liens brisés ; --report émet du JSON ; --fix réécrit les versions obsolètes + marque les PR inconnues | print / JSON / fix |
check-glama --repo o/r [--poll N] [--add-badge] [--json] | attendre l'inscription Glama ; --add-badge écrit le badge README une fois en ligne ; --json structuré | print / écrit |
awesome-pr --upstream o/r --repo o/r --fork o/r --branch b [--execute --category C --description D --install I] | recette PR, ou en fait fork→edit→push→gh pr create | print / execute |
Tokens : jamais stockés sur le disque. publish/release --execute lit PYPI_TOKEN
ou NPM_TOKEN depuis l'environnement ; demandez le token à l'utilisateur et passez-le en ligne.
Périmètre d'automatisation
| Étape | Qui l'exécute |
|---|---|
| Fichiers CI, Dockerfile, métadonnées, corrections de code | Agent |
| Artéfacts de build, vérification d'installation fraîche | Agent |
| Publication sur le registre (PyPI/npm) | Agent, avec un token fourni par l'utilisateur |
| Soumission Glama via navigateur | Utilisateur (OAuth) |
| Création de PR awesome/autre | Agent |
| Publication sur les plateformes | Utilisateur |
Ne fabriquez jamais d'identifiants ; demandez le token explicitement et utilisez-le en ligne, ne l'écrivez jamais dans un fichier.
Cicatrices du monde réel (issues de la livraison de wheel-hub + zspace-cli)
mcp>=1.0dans les extras + nouveau SDK → les nouvelles installations plantent. Fixez des seuils.- Python 3.9 ne peut pas installer
mcp>=2.0; la matrice CI doit séparer la base vs les extras. - YAML block scalar + heredoc python en ligne = workflow cassé. Utilisez un fichier script.
- L'objet
ServerMCP 2.x n'a paslist_tools— utilisez les décorateurs@server.tool(). - L'introspection Glama nécessite que stdin reste ouvert un instant (
sleep 1) dans les tests de fumée. - Formats de token PyPI :
pypi-...réel, UUID = erroné. - Le typosquatting npm bloque
wheel-hubà côté dewheelhub; les noms scopés fonctionnent. .dockerignoremanquant → images géantes / secrets dans le contexte de build.