Zheat Logo
    RadjivRadjivSenior AI Engineer

    Livre blanc Rocky: MCP d'ingénierie agentique

    Livre blanc Rocky: gateway devkit, agents vs skills, profils d'architecture, workflow senior, économies de tokens mesurées.

    Suivre sur LinkedIn

    Version 1.0 | Août 2026 Auteurs: Radjiv, hellozheat Dépôt: github.com/hellozheat/rocky Source docs: docs/ Référence: Livre blanc technique public

    Résumé

    Rocky est un serveur MCP pour l'ingénierie agentique assistée. Le modele écrit toujours le code dans votre repo. Rocky fournit un handbook partage (agents + rules + skills), une gateway devkit, une discovery graphify-first, et une quality gate pre-PR avec verdict ready / not_ready.

    Ce n'est pas de l'autonome. La valeur produit, c'est moins de thrashing: conventions partagees, JSON d'outils structure au lieu de terminaux colles, tests scopes, gate avant review humaine.

    Sur une feature mesuree (monorepo React de production, même modele, même tâche), les tokens de session (milieu) passent d'environ 255k à environ 89k (environ 65% de moins). La discovery seule chute d'environ 89%. Cout Sonnet 4.6 (exemple OpenRouter): environ $1.62 a $0.85.

    Endpoint MCP: https://userocky.zheat.xyz/mcp Inspector: userocky.zheat.xyz/inspector Licence: MIT

    Table des matières

    1. Problème
    2. Principes de conception
    3. Architecture
    4. Gateway devkit
    5. Handbook: agents, skills, rules
    6. Profils d'architecture
    7. Workflow senior
    8. Rapport de valeur mesure
    9. Économie tokens et coûts
    10. Install et sécurité
    11. Clients et prompts
    12. Solo vs équipe
    13. Limites et suite
    14. Insights liés
    15. Annexes

    1. Problème

    Les outils de code IA sont rapides. Une grande partie de ce qu'ils génèrent se fait quand même rejeter: mauvaises conventions, patterns inconsistants, tests manquants, structure qu'un reviewer n'accepte pas.

    Sans outillage partage, chaque session rediscouvre le repo, re-devine les standards, et relance d'énormes cycles test/lint. Vous brûlez du temps de review et des tokens.

    Rocky comble ce trou: handbook de niveau équipe + petites actions repo sures, même en solo sur le serveur public.

    2. Principes de conception

    PrincipeSens
    Assiste, pas autonomeLe modele edite vos fichiers; Rocky route, briefe, verifie
    Une gatewayPréférer devkit + action a des dizaines de schemas
    Graphify avant grepStructure d'abord; lectures full-file ensuite
    Détecter avant d'imposerMatcher hexagonal / Next / API depuis le repo
    Agents courts, skills profondesPorte d'entrée petite; templates a la demande
    Gate avant PRLint, tests, heuristiques → ready / not_ready
    Sécurité par cheminsDEVKIT_ALLOWED_REPO_ROOTS + safe-run allowliste
    La CI reste reineMCP ne remplace pas votre pipeline de merge

    3. Architecture

    Serveur MCP HTTP. Les clients se connectent a /mcp. Resources, prompts, tools.

    Host (Cursor / Claude / VS Code / ChatGPT)
  → MCP userocky.zheat.xyz/mcp
    → Handbook serveur (24 agents, 26 skills, rules)
    → Actions repo si chemins allowlistes
    → pre_pr_quality_gate → ready / not_ready

    4. Gateway devkit

    Un seul outil devkit avec un champ action. Le modele apprend via devkit://capabilities, puis reutilise un schema.

    Tradeoff: chaque appel envoie encore le schema devkit complet. Sur de longues sessions, c'est en general moins cher que 15+ definitions separees.

    Préférer devkit en chat. Les outils standalone surtout pour Inspector / debug.

    5. Handbook: agents, skills, rules

    Idee en une phrase: les agents sont la porte d'entrée courte; les skills sont la reference profonde, chargee seulement quand la tâche a besoin de templates.

    Session disciplinée: environ 4k-6k tokens d'overhead handbook, pas tout le corpus.

    devkit-start-task route (zone de tâche → agent + rules) avec un plafond: lire au plus 2-3 resources. devkit-review-code pointe exactement trois resources: code-reviewer, human-readable-code, tests.

    6. Profils d'architecture

    Détecter le repo avant d'imposer une structure. Préférer hexagonal si src/domain/ existe.

    Ordre: Next app/ → hexagonal (Nest / FastAPI / React) → layered-react-spa legacy → node-api-only → sinon graphify + voisins.

    7. Workflow senior

    Connecter → devkit-start-task → codebase-discovery → 1 agent + 1-2 rules → editer le repo → repo_test / repo_lint → pre_pr_quality_gate jusqu'a ready → repo_open_pr si demande.

    8. Rapport de valeur mesure

    Meme tâche, même modele, monorepo React de production:

    MetriqueSans MCPAvec MCP
    Tokens (milieu)~255k~89k (−65%)
    Discovery~125k~14k (−89%)
    Attente Vitest ×8~232 s~77 s
    Sonnet 4.6 (ex.)~$1.62~$0.85

    Detail et tableaux de phase: using-mcp-devkit-report.md et rapport Insights.

    9. Économie tokens et coûts

    Ce qui économise: router (2-3 fichiers), JSON gateway, tests scopes, graphify resume-first, une gate avant PR.

    Ce qui gaspille: lire tous les agents après list_handbook, ignorer le router, coller tout graphify-out/ dans le chat.

    10. Install et sécurité

    claude mcp add --transport http "rocky" https://userocky.zheat.xyz/mcp

    Cursor: URL dans ~/.cursor/mcp.json.

    Prod: pas d'auth MCP par défaut; préférer hosting handbook-only sans GITHUB_TOKEN ni roots larges; DEVKIT_ALLOWED_REPO_ROOTS minimal si outils repo activés; safe-run allowliste seulement.

    Detail: INSTALL.md.

    11. Clients et prompts

    Cursor, Claude Code, VS Code, ChatGPT. Prompts: devkit-start-task, devkit-review-code, devkit-before-pr, devkit-learn-the-stack.

    12. Solo vs équipe

    Le handbook public marche pour n'importe quel repo. Votre code reste local. Les actions repo demandent un allowlist de chemins, pas une appartenance d'équipe.

    13. Limites et suite

    Le modele doit suivre le router. Les outils repo ont besoin d'accès chemin. MCP ne remplace pas la CI. Les chiffres mesurés sont une feature; re-mesurer chez vous. Pas d'auth MCP par défaut.

    14. Insights liés

    15. Annexes

    A. Carte des docs

    INSTALL, senior-workflow, using-mcp-devkit-report, token-cost-breakdown, architecture-profiles, why-agents-and-skills-are-split : tous sous docs/.

    B. One-liner manager

    Meme modele, environ 40-50% de tokens en moins sur une feature typique si Rocky est connecte et que le modele suit le router. Exemple mesure: environ 65% de tokens en moins, environ $1.62 → $0.85.

    C. Checklist ingenieur

    1. Connecter Rocky (vert).
    2. devkit-start-task ou prompt README.
    3. codebase-discovery une fois; une ligne de router.
    4. Tests scopes, pas full suite a chaque message.
    5. pre_pr_quality_gate avant repo_open_pr.

    Rocky tel que documente dans [github.com/hellozheat/rocky](https://github.com/hellozheat/rocky) `docs/`. Les comptes, prompts et chiffres mesurés évoluent avec le source.

    ← Tous les insights