Skip to main content
Glama
mambari

visbug-mcp

by mambari
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

VisBug MCP Bridge

Capture les modifications visuelles faites avec VisBug et les expose à Claude Code via le protocole MCP.

Architecture

Chrome (VisBug + Extension)
        │  WebSocket ws://127.0.0.1:4844
        ▼
┌─────────────────┐      ~/.visbug-mcp/changes.json
│  ws-daemon.js   │ ◄──────────────────────────────►  src/server.js (MCP stdio)
│  (pm2, always   │                                    └─ démarré par Claude Code
│   running)      │                                       à la demande
└─────────────────┘

  • src/ws-daemon.js — serveur WebSocket autonome, tourne en permanence via pm2. Reçoit les mutations de l'extension, les persiste dans ~/.visbug-mcp/changes.json.

  • src/server.js — serveur MCP (stdio). Démarré par Claude Code à la demande. Lit et écrit le fichier store. N'ouvre pas de WebSocket.

  • extension/ — extension Chrome. Injecte un content-script sur localhost pour observer les mutations DOM, et expose un popup de contrôle.

Related MCP server: gotham-browser

Installation

1. Dépendances

cd /path/to/visbug-mcp
npm install

2. Daemon WebSocket (pm2)

# Installer pm2 globalement
npm install -g pm2

# Démarrer le daemon
pm2 start src/ws-daemon.js --name visbug-ws

# Démarrage automatique au login Mac
pm2 startup    # copier-coller la commande sudo affichée
pm2 save

Le daemon écoute sur ws://127.0.0.1:4844. Il se relance automatiquement en cas de crash.

3. Extension Chrome

  1. Ouvrir chrome://extensions

  2. Activer le mode développeur (toggle en haut à droite)

  3. Cliquer "Charger l'extension non empaquetée"

  4. Sélectionner le dossier extension/

Le popup s'affiche via l'icône dans la barre Chrome et indique le statut de connexion au daemon.

4. Serveur MCP (Claude Code)

claude mcp add visbug-mcp -- node /path/to/visbug-mcp/src/server.js

Ou manuellement dans .claude.json du projet :

{
  "mcpServers": {
    "visbug-mcp": {
      "command": "node",
      "args": ["/path/to/visbug-mcp/src/server.js"]
    }
  }
}

Utilisation

Flux de travail

  1. Ouvrir la page sur localhost dans Chrome — le content-script se connecte automatiquement au daemon

  2. Faire des modifications avec VisBug (couleurs, espacements, typographie…)

  3. Dans Claude Code, utiliser /visbug ou appeler un outil MCP pour récupérer et appliquer les changements

Popup Chrome

Indicateur

Signification

🟢 Connecté au serveur MCP

Daemon en ligne, capture active

🔴 Serveur MCP non démarré

Daemon arrêté — relancer avec pm2 start src/ws-daemon.js --name visbug-ws

N mutation(s) capturée(s)

Nombre de changements en attente (non appliqués)

Bouton

Action

Copier les changements

Copie la liste formatée dans le presse-papier (sans passer par MCP)

Vider les changements

Efface le store et réinitialise le storage VisBug

Outils MCP

get_changes

Retourne les modifications visuelles capturées (non encore appliquées).

Paramètres :
  filter  (optionnel) : "style" | "attribute" | "text" | "node-added" | "node-removed"

Exemple de sortie :

[0] .card > h2 → CSS: font-size: 18px (était: 16px)
[1] .btn--primary → CSS: background: rgb(59, 130, 246) (était: rgb(99, 102, 241))
[2] #hero-title → texte: "Nouveau titre" (était: "Ancien titre")

apply_changes

Marque des changements comme appliqués (après les avoir écrits dans les fichiers source).

Paramètres :
  ids  (optionnel) : tableau d'indices — vide = marquer tout

clear_changes

Vide complètement le store.

Comportement technique

Période de grâce (2 secondes)

À chaque rechargement de page, VisBug re-applique automatiquement ses changements persistés depuis son propre storage (chrome.storage.local). Ces mutations arrivent dans la première seconde et sont indiscernables des actions utilisateur.

Le daemon refuse toutes les mutations reçues dans les 2 premières secondes après la connexion WebSocket du content-script pour les ignorer.

Déduplication

Le parser (src/parser.js) maintient un Map en mémoire (seen) indexé par selector|type|propriété. Si la même propriété est modifiée plusieurs fois sur le même élément, seule la dernière valeur est conservée.

Persistance (file store)

Les changements sont sauvegardés dans ~/.visbug-mcp/changes.json après chaque nouvelle mutation. Ce fichier est la source de vérité partagée entre le daemon et le serveur MCP.

{
  "changes": [
    {
      "type": "style",
      "selector": ".card > h2",
      "property": "font-size",
      "oldValue": "16px",
      "newValue": "18px",
      "tag": "H2",
      "url": "http://localhost:5173/dashboard",
      "timestamp": 1711234567890,
      "applied": false
    }
  ]
}

Filtrage du bruit

Le parser ignore automatiquement :

  • Les sélecteurs internes VisBug (#vibe-annotations-root, vis-bug, etc.)

  • Les variables CSS scopées Vue (--dc13a441-…)

  • Les classes Vue Router (router-link-active, transitions)

  • Les mutations node-added / node-removed (rendu Vue)

  • Les textes initiaux longs (dump de rendu initial)

  • Les attributs contenteditable (usage interne VisBug)

Commandes utiles

# Statut du daemon
pm2 status visbug-ws

# Logs en temps réel
pm2 logs visbug-ws

# Redémarrer le daemon
pm2 restart visbug-ws

# Développement avec rechargement automatique
npm run daemon:watch

# Vider le store manuellement
echo '{"changes":[]}' > ~/.visbug-mcp/changes.json

Structure du projet

visbug-mcp/
├── src/
│   ├── ws-daemon.js      # Serveur WebSocket autonome (pm2)
│   ├── server.js         # Serveur MCP stdio (Claude Code)
│   └── parser.js         # Parsing, déduplication, formatage
├── extension/
│   ├── manifest.json     # Manifest Chrome v3
│   ├── content-script.js # Observateur DOM + client WebSocket
│   ├── popup.html        # Interface popup Chrome
│   ├── popup.js          # Logique popup
│   └── background.js     # Service worker (minimal)
└── .claude/
    └── commands/
        └── visbug.md     # Skill Claude Code /visbug

Available Tools

3 tools
apply_changesB

Marque les changements comme appliqués après écriture dans les fichiers source.

ParametersJSON Schema
NameRequiredDescriptionDefault
idsNoIndices des changements à marquer. Vide = tous.

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It only states the action (mark changes as applied) without mentioning side effects, required state, idempotency, or reversibility. This leaves the agent uncertain about consequences.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise and front-loaded. However, it omits important behavioral details, sacrificing completeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter, no output schema, no annotations), the description provides minimal but adequate coverage. It misses behavioral transparency, but is otherwise functional.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description of the 'ids' parameter. The tool description adds context ('after writing to source files'), but does not enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool marks changes as applied after writing to source files. It distinguishes from siblings by implying a specific action (applying changes) rather than clearing or retrieving them, but does not explicitly contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage after writing changes to source files, but provides no explicit guidance on when to use this tool versus alternatives (clear_changes, get_changes) or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

clear_changesA

Vide complètement le buffer de changements.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full responsibility for behavioral disclosure. It states the tool empties the buffer 'completely,' but fails to mention whether the action is reversible, what impacts pending changes, or any authorization needs. This is insufficient for a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, short sentence with no unnecessary words. It is front-loaded and wastes no space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description is minimal but adequate for a clear operation. However, the lack of annotations or detail about consequences makes it incomplete for a destructive action.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema already covers everything. The description adds no additional parameter semantics, but the baseline for zero-parameter tools is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Vide complètement le buffer de changements' clearly states the action (clearing) and the resource (change buffer). It effectively distinguishes from sibling tools get_changes and apply_changes, which handle retrieval and application respectively.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequirements, side effects, or appropriate contexts for clearing the buffer, leaving the agent without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_changesA

Retourne toutes les modifications visuelles capturées par VisBug. Chaque entrée contient : selector CSS, propriété, ancienne valeur, nouvelle valeur, tag HTML, url.

ParametersJSON Schema
NameRequiredDescriptionDefault
filterNoFiltrer par type : "style" | "attribute" | "text" | "node-added" | "node-removed". Optionnel.

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It describes the return structure but does not mention any side effects, rate limits, or potential costs. It is adequate for a read-only tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no wasted words. Clearly structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description fully explains the return structure. Complexity is low, and the description covers what the tool returns and accepts.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'filter' is described in the schema with an enum. The description adds value by explaining the filter types in plain language ('style', 'attribute', etc.) and noting it is optional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns all visual changes captured by VisBug and lists the contents of each entry (CSS selector, property, old/new value, HTML tag, URL). It is distinct from siblings 'clear_changes' and 'apply_changes'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for retrieving changes, while siblings are for clearing or applying. However, it does not explicitly state when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedapply_changes
    • First observedclear_changes
    • First observedget_changes
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation5/5

Les trois outils ciblent des actions distinctes et non chevauchantes : vider le buffer, récupérer les modifications, marquer comme appliquées. Aucune ambiguïté.

Naming Consistency5/5

Tous les noms suivent le même modèle verbe_nom en snake_case : clear_changes, get_changes, apply_changes. Très cohérent.

Tool Count5/5

Avec 3 outils, le serveur est bien dimensionné pour son objectif simple de gestion des modifications VisBug. Ni trop peu, ni trop.

Completeness4/5

Le jeu d'outils couvre les opérations de base (lire, effacer, marquer). Il manque peut-être un outil pour appliquer réellement les modifications dans les fichiers source, mais cela peut être externe. Lacune mineure.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mambari/visbug-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server