docs(mcp): clarify external repo-context mcp vs sdd-mcp

Author: juanklagos

README.es.md

@@ -45,6 +45,11 @@ Si tu cliente de IA soporta MCP, este repositorio ya incluye un servidor local `
 Si quieres la explicación más simple primero:
 - [Guía fácil de MCP](./docs/es/43-guia-mcp-facil.md)
 
+Diferencia importante:
+- `GitMCP` o similar puede ayudar a una IA a leer y entender este repositorio público gratis.
+- No reemplaza el comportamiento propio de `sdd-mcp` dentro del framework.
+- Usa `GitMCP` para contexto remoto del repo y `sdd-mcp` para el flujo real guiado de SDD.
+
 Ruta rápida:
 1. Compila el servidor:
 

README.md

@@ -45,6 +45,11 @@ If your AI client supports MCP, this repository now includes a local `sdd-mcp` s
 If you want the simplest explanation first:
 - [Easy MCP Guide](./docs/en/43-easy-mcp-guide.md)
 
+Important distinction:
+- `GitMCP` or similar can help an AI read and understand this public repository for free.
+- It does not replace this framework's own `sdd-mcp` behavior.
+- Use `GitMCP` for remote repo context and `sdd-mcp` for the real guided SDD workflow.
+
 Quick path:
 1. Build the server:
 

docs/en/43-easy-mcp-guide.md

@@ -74,6 +74,71 @@ Important:
 - others may show them as prompt templates or actions
 - if your client does not show them, write the request in plain language instead
 
+## External MCP, explained simply
+
+There are 2 very different things that may look similar:
+
+1. an external repo-context MCP such as `GitMCP`
+2. this framework's own operational MCP, `sdd-mcp`
+
+Think of them like this:
+- `GitMCP` is like a public librarian for your repository
+- `sdd-mcp` is like the project operator that can guide and organize work
+
+### What `GitMCP` is good for
+
+Use `GitMCP` when you want:
+- a free and immediate external MCP
+- AI to read your public repository
+- AI to understand your README, docs, templates, and structure
+- easier diffusion and discovery
+
+What the user gets:
+- quick remote context
+- no server hosting work from your side
+- a simple URL form based on the GitHub repository
+
+### What `GitMCP` does not replace
+
+`GitMCP` does not replace your own MCP product layer.
+
+It does not give you:
+- your custom tools
+- your custom prompts as a controlled product surface
+- your own project rules as an owned service
+- real local file writes in the user's project
+
+So the right mental model is:
+- `GitMCP` = remote reading and understanding
+- `sdd-mcp` = guided SDD operations and framework behavior
+
+## The recommended combination
+
+For this framework, the easiest professional setup is:
+
+```mermaid
+flowchart LR
+  A["Public repo on GitHub"] --> B["GitMCP or similar"]
+  A --> C["Local sdd-mcp"]
+  B --> D["AI understands the framework"]
+  C --> E["AI can guide real SDD actions"]
+  E --> F["Project files and traceability"]
+```
+
+This means:
+- use `GitMCP` if you want free external understanding of the repo
+- use `sdd-mcp` if you want the real framework workflow
+- combine both if you want the easiest operator experience
+
+## What to tell a user in plain language
+
+```text
+There are two MCP layers.
+One layer helps the AI read and understand the public repository.
+The other layer helps the AI guide the real SDD workflow.
+If you only use a repo-context MCP like GitMCP, the AI can understand the template better, but it does not replace the framework's own MCP behavior.
+```
+
 ## What the user should expect every time
 
 For beginner-friendly use, the AI should answer in this order:

docs/en/44-hosted-mcp-onboarding-model.md

@@ -97,6 +97,7 @@ Short term:
 - keep `sdd-mcp` local for operations
 - publish docs that define the hosted layer contract
 - use the current HTTP transport as the conceptual base
+- optionally use `GitMCP` as the free external repo-context layer for public understanding
 
 Mid term:
 - host a read-oriented onboarding MCP endpoint
@@ -106,6 +107,25 @@ Mid term:
 Long term:
 - offer a one-click launcher or thin local bridge that the hosted layer can orchestrate through the client
 
+## Where `GitMCP` fits
+
+`GitMCP` is useful as a free external layer for public repositories.
+
+What it can do well:
+- let AI clients read and understand this repository remotely
+- expose public docs and structure with almost no setup
+- help with discovery, demos, and diffusion
+
+What it should not be treated as:
+- a replacement for `sdd-mcp`
+- a replacement for your custom prompts and product behavior
+- a safe writer into the user's local project
+
+So the recommended framing is:
+- `GitMCP` or similar = external repo context
+- hosted onboarding MCP = your owned remote guidance layer
+- local `sdd-mcp` = operational local execution layer
+
 ## Minimum hosted contract
 
 The hosted onboarding MCP should provide at least:

docs/es/43-guia-mcp-facil.md

@@ -74,6 +74,71 @@ Importante:
 - otros pueden mostrarlos como plantillas de prompt o acciones
 - si tu cliente no los muestra, escribe la petición en lenguaje natural
 
+## MCP externo, explicado simple
+
+Hay 2 cosas muy distintas que pueden parecer parecidas:
+
+1. un MCP externo de contexto de repositorio como `GitMCP`
+2. el MCP operativo de este framework, `sdd-mcp`
+
+Piensa en ellas así:
+- `GitMCP` es como un bibliotecario público del repositorio
+- `sdd-mcp` es como el operador del proyecto que puede guiar y organizar el trabajo
+
+### Para qué sí sirve `GitMCP`
+
+Usa `GitMCP` cuando quieres:
+- un MCP externo gratuito e inmediato
+- que la IA lea tu repositorio público
+- que la IA entienda el README, docs, templates y estructura
+- facilitar difusión y descubrimiento
+
+Qué obtiene el usuario:
+- contexto remoto rápido
+- cero trabajo de hosting de tu lado
+- una URL simple basada en el repositorio GitHub
+
+### Qué no reemplaza `GitMCP`
+
+`GitMCP` no reemplaza la capa de producto MCP propia.
+
+No te da:
+- tus tools personalizados
+- tus prompts personalizados como superficie de producto controlada
+- tus reglas del proyecto como servicio propio
+- escrituras reales en archivos locales del proyecto del usuario
+
+Entonces el modelo correcto es:
+- `GitMCP` = lectura y entendimiento remoto
+- `sdd-mcp` = operaciones guiadas de SDD y comportamiento del framework
+
+## La combinación recomendada
+
+Para este framework, la configuración profesional más fácil es:
+
+```mermaid
+flowchart LR
+  A["Repo público en GitHub"] --> B["GitMCP o similar"]
+  A --> C["sdd-mcp local"]
+  B --> D["La IA entiende el framework"]
+  C --> E["La IA puede guiar acciones SDD reales"]
+  E --> F["Archivos del proyecto y trazabilidad"]
+```
+
+Esto significa:
+- usa `GitMCP` si quieres entendimiento externo y gratuito del repo
+- usa `sdd-mcp` si quieres el flujo real del framework
+- combina ambos si quieres la experiencia más fácil para el operador
+
+## Qué decirle a un usuario en lenguaje simple
+
+```text
+Hay dos capas MCP.
+Una capa ayuda a la IA a leer y entender el repositorio público.
+La otra capa ayuda a la IA a guiar el flujo real de SDD.
+Si solo usas un MCP de contexto de repositorio como GitMCP, la IA puede entender mejor el template, pero no reemplaza el comportamiento propio del MCP del framework.
+```
+
 ## Qué debe esperar el usuario siempre
 
 Para un uso amigable de principiante, la IA debe responder en este orden:

docs/es/44-modelo-onboarding-mcp-alojado.md

@@ -97,6 +97,7 @@ Corto plazo:
 - mantener `sdd-mcp` local para operaciones
 - publicar docs que definan el contrato de la capa alojada
 - usar el transporte HTTP actual como base conceptual
+- usar opcionalmente `GitMCP` como capa externa gratuita de contexto del repo público
 
 Mediano plazo:
 - alojar un endpoint MCP de onboarding orientado a lectura
@@ -106,6 +107,25 @@ Mediano plazo:
 Largo plazo:
 - ofrecer un launcher de un clic o un bridge local delgado que la capa alojada pueda orquestar a través del cliente
 
+## Dónde encaja `GitMCP`
+
+`GitMCP` sirve como capa externa gratuita para repositorios públicos.
+
+Qué sí puede hacer bien:
+- permitir que clientes IA lean y entiendan este repositorio de forma remota
+- exponer docs y estructura pública con casi cero setup
+- ayudar en descubrimiento, demos y difusión
+
+Qué no debe considerarse:
+- un reemplazo de `sdd-mcp`
+- un reemplazo de tus prompts y comportamiento de producto
+- un escritor seguro dentro del proyecto local del usuario
+
+Entonces la forma correcta de explicarlo es:
+- `GitMCP` o similar = contexto externo del repo
+- MCP alojado de onboarding = tu capa remota propia de guía
+- `sdd-mcp` local = capa operativa local de ejecución
+
 ## Contrato mínimo alojado
 
 El MCP alojado de onboarding debería ofrecer al menos: