From 1be8cabbb30fa1216fa57a482635a8d619e83f4a Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 16:07:38 -0300 Subject: [PATCH 01/51] docs: refactor MCP Mesh to decocms branding Renamed product from "MCP Mesh" to "decocms" across all documentation, removed MCP Studio references, and updated navigation. This establishes consistent branding before other documentation work. Changes: - Replaced all "MCP Mesh" references with "decocms" in en/ and pt-br/ - Removed MCP Studio documentation and navigation entries - Updated sidebar labels and navigation structure - Fixed internal links from mcp-gateways to virtual-mcps - Preserved Legacy Admin documentation as requested Closes beads-main-km6 Co-Authored-By: Claude Sonnet 4.5 --- .../client/src/components/ui/Sidebar.astro | 15 +++----- .../docs/client/src/components/ui/Sidebar.tsx | 8 ++--- .../client/src/content/en/introduction.mdx | 34 +++++++------------ .../mcp-mesh/deploy/kubernetes-helm-chart.mdx | 6 ++-- .../mcp-mesh/deploy/local-docker-compose.mdx | 8 ++--- .../src/content/en/mcp-mesh/mcp-servers.mdx | 2 +- .../src/content/en/mcp-mesh/overview.mdx | 22 ++++++------ .../{mcp-gateways.mdx => virtual-mcps.mdx} | 0 .../src/content/en/mcp-studio/overview.mdx | 32 ----------------- .../client/src/content/pt-br/introduction.mdx | 28 +++++---------- .../mcp-mesh/deploy/kubernetes-helm-chart.mdx | 6 ++-- .../mcp-mesh/deploy/local-docker-compose.mdx | 10 +++--- .../src/content/pt-br/mcp-mesh/overview.mdx | 22 ++++++------ .../{mcp-gateways.mdx => virtual-mcps.mdx} | 0 .../src/content/pt-br/mcp-studio/overview.mdx | 32 ----------------- apps/docs/client/src/i18n/ui.ts | 6 ++-- apps/docs/client/src/utils/navigation.ts | 4 +-- 17 files changed, 71 insertions(+), 164 deletions(-) rename apps/docs/client/src/content/en/mcp-mesh/{mcp-gateways.mdx => virtual-mcps.mdx} (100%) delete mode 100644 apps/docs/client/src/content/en/mcp-studio/overview.mdx rename apps/docs/client/src/content/pt-br/mcp-mesh/{mcp-gateways.mdx => virtual-mcps.mdx} (100%) delete mode 100644 apps/docs/client/src/content/pt-br/mcp-studio/overview.mdx diff --git a/apps/docs/client/src/components/ui/Sidebar.astro b/apps/docs/client/src/components/ui/Sidebar.astro index b05f95a351..524fc98904 100644 --- a/apps/docs/client/src/components/ui/Sidebar.astro +++ b/apps/docs/client/src/components/ui/Sidebar.astro @@ -65,7 +65,7 @@ function buildTree(docs: any[]): TreeNode[] { // Get parent folder to determine which order to use const parentPath = a.path[a.path.length - 2]; - // Custom order for MCP Mesh top-level pages + // Custom order for decocms top-level pages if (parentPath === "mcp-mesh") { // NOTE: doc IDs do not include ".mdx" (e.g. "overview", not "overview.mdx") const mcpMeshOrder = [ @@ -76,7 +76,7 @@ function buildTree(docs: any[]): TreeNode[] { "authentication", "authorization-and-roles", "mcp-servers", - "mcp-gateways", + "virtual-mcps", "api-keys", "monitoring", "api-reference", @@ -120,7 +120,7 @@ function buildTree(docs: any[]): TreeNode[] { if (bIndex !== -1) return 1; } - // Custom order for MCP Mesh deploy docs + // Custom order for decocms deploy docs const rootPath = a.path[0]; if (rootPath === "mcp-mesh" && parentPath === "deploy") { const deployOrder = ["local-docker-compose", "kubernetes-helm-chart"]; @@ -137,12 +137,11 @@ function buildTree(docs: any[]): TreeNode[] { // For folders - custom ordering if (a.type === "folder" && b.type === "folder") { const folderOrder: Record = { - // Put Mesh docs first + // Put decocms docs first "mcp-mesh": 0, "getting-started": 1, "no-code-guides": 2, "full-code-guides": 3, - "mcp-studio": 4, }; const aOrder = folderOrder[a.name] ?? Number.POSITIVE_INFINITY; @@ -180,10 +179,7 @@ function groupLegacyAdminSections(nodes: TreeNode[]): TreeNode[] { const folders = nodes.filter((n) => n.type === "folder"); const mcpMesh = folders.find((f) => f.name === "mcp-mesh"); - const mcpStudio = folders.find((f) => f.name === "mcp-studio"); - const legacyChildren = folders.filter( - (f) => f.name !== "mcp-mesh" && f.name !== "mcp-studio", - ); + const legacyChildren = folders.filter((f) => f.name !== "mcp-mesh"); const legacyFolder: TreeNode | null = legacyChildren.length > 0 @@ -205,7 +201,6 @@ function groupLegacyAdminSections(nodes: TreeNode[]): TreeNode[] { const next: TreeNode[] = []; if (introduction) next.push(introduction); if (mcpMesh) next.push(mcpMesh); - if (mcpStudio) next.push(mcpStudio); next.push(...otherFiles); if (legacyFolder) next.push(legacyFolder); return next; diff --git a/apps/docs/client/src/components/ui/Sidebar.tsx b/apps/docs/client/src/components/ui/Sidebar.tsx index 927d0e5b81..3d8e4a1b87 100644 --- a/apps/docs/client/src/components/ui/Sidebar.tsx +++ b/apps/docs/client/src/components/ui/Sidebar.tsx @@ -140,11 +140,9 @@ function TreeItem({ name={ node.id === "mcp-mesh" ? "Network" - : node.id === "mcp-studio" - ? "LayoutDashboard" - : node.id === "mcp-mesh/deploy" - ? "Rocket" - : "Folder" + : node.id === "mcp-mesh/deploy" + ? "Rocket" + : "Folder" } size={16} className={`shrink-0 ${active ? "text-primary" : ""}`} diff --git a/apps/docs/client/src/content/en/introduction.mdx b/apps/docs/client/src/content/en/introduction.mdx index bca92a27ee..31f11baf9f 100644 --- a/apps/docs/client/src/content/en/introduction.mdx +++ b/apps/docs/client/src/content/en/introduction.mdx @@ -1,6 +1,6 @@ --- title: Introduction -description: Developer docs for the MCP Mesh and the deco CMS platform +description: Developer docs for decocms and the deco CMS platform icon: Rocket --- @@ -12,17 +12,16 @@ import Callout from "../../components/ui/Callout.astro"; **deco CMS** is an open-source **Context Management System** for AI-native operations. -If MCP is the standard interface for tool access, deco CMS is the **production layer around it**: connect MCP servers, enforce governance, and get observability as usage scales across teams and environments. The broader platform also includes a **builder framework** (MCP Studio — coming soon) and **distribution capabilities** (pre-built modules and store). +If MCP is the standard interface for tool access, deco CMS is the **production layer around it**: connect MCP servers, enforce governance, and get observability as usage scales across teams and environments. **Official links:** - **deco CMS**: [decocms.com](https://www.decocms.com/) -- **The MCP Mesh**: [decocms.com/mesh](https://www.decocms.com/mesh) -- **MCP Studio**: [decocms.com/mcp-studio](https://www.decocms.com/mcp-studio) +- **decocms**: [decocms.com/mesh](https://www.decocms.com/mesh) -If you know us from before (as **deco.cx**) and you’re looking for **headless CMS + storefront** capabilities, visit [deco.cx](https://www.decocms.com/use-case/deco-cx). See the deco.cx docs at [docs.deco.cx](https://docs.deco.cx/en/getting-started/overview). +If you know us from before (as **deco.cx**) and you're looking for **headless CMS + storefront** capabilities, visit [deco.cx](https://www.decocms.com/use-case/deco-cx). See the deco.cx docs at [docs.deco.cx](https://docs.deco.cx/en/getting-started/overview). -## Start with the MCP Mesh +## Start with decocms Choose one: @@ -87,23 +86,21 @@ The application will be available at `http://localhost:8080`. **More details:** [Kubernetes: Helm Chart](/en/mcp-mesh/deploy/kubernetes-helm-chart) -## Learn the Mesh (concepts + product surfaces) +## Learn decocms (concepts + product surfaces) -- **[MCP Mesh Overview](/en/mcp-mesh/overview)** +- **[decocms Overview](/en/mcp-mesh/overview)** - **[Quickstart](/en/mcp-mesh/quickstart)** - **[Concepts](/en/mcp-mesh/concepts)** - **[MCP Servers (Connections)](/en/mcp-mesh/mcp-servers)** -- **[MCP Agents](/en/mcp-mesh/mcp-gateways)** +- **[Virtual MCPs](/en/mcp-mesh/virtual-mcps)** - **[API Keys](/en/mcp-mesh/api-keys)** - **[Monitoring](/en/mcp-mesh/monitoring)** **Docs split (quick guide):** - - **The MCP Mesh** → Self-hosting, deploying, and operating the Mesh (recommended). - - **Legacy Admin** → If you’re using `admin.decocms.com` (still supported, **deprecated soon**). - - We’re launching **MCP Studio** (on top of the Mesh), which will bring the current SaaS admin capabilities to the Mesh (including a hosted option by us) and replace the legacy SaaS over time. + - **decocms** → Self-hosting, deploying, and operating decocms (recommended). + - **Legacy Admin** → If you're using `admin.decocms.com` (still supported, **deprecated soon**). ## Problem: the production gap @@ -118,18 +115,11 @@ As tool surfaces and teams grow, most orgs run into the same production constrai For more context on our platform-level thesis, read [The architecture of an AI-native company](https://www.decocms.com/blog/post/ai-native-company). -## Platform structure: Mesh → Studio → Apps & Store +## Platform structure: Core → Apps & Store -### The MCP Mesh (foundation) +### decocms (foundation) An open-source **control plane for MCP traffic**. It sits between your MCP clients (Cursor, Claude, VS Code, custom agents) and your MCP servers, providing a unified layer for auth, policy, and observability. -### MCP Studio (development) -A no-code admin + SDK to package MCP capabilities as reusable building blocks. - - - **Coming soon:** This is the successor to the current SaaS admin, built on top of the MCP Mesh. - - ### MCP Apps & Store (distribution) A path to distribute reusable MCP-native capabilities across teams (and eventually a store). diff --git a/apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx b/apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx index 3c696a1d88..ff4cee2aef 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/deploy/kubernetes-helm-chart.mdx @@ -1,14 +1,14 @@ --- title: "Kubernetes: Helm Chart" -description: Deploy the MCP Mesh on Kubernetes using the Helm chart +description: Deploy decocms on Kubernetes using the Helm chart icon: Rocket --- import Callout from "../../../../components/ui/Callout.astro"; -This guide explains how to deploy the MCP Mesh on Kubernetes using the Helm chart. +This guide explains how to deploy decocms on Kubernetes using the Helm chart. -Learn more: [the MCP Mesh product page](https://www.decocms.com/mesh) +Learn more: [the decocms product page](https://www.decocms.com/mesh) Helm chart source: [decocms/helm-chart-deco-mcp-mesh](https://github.com/decocms/helm-chart-deco-mcp-mesh) diff --git a/apps/docs/client/src/content/en/mcp-mesh/deploy/local-docker-compose.mdx b/apps/docs/client/src/content/en/mcp-mesh/deploy/local-docker-compose.mdx index 7f0a3d9c3d..90450b544e 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/deploy/local-docker-compose.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/deploy/local-docker-compose.mdx @@ -1,14 +1,14 @@ --- title: "Local: Docker Compose" -description: Deploy the MCP Mesh locally using Docker Compose for testing and development +description: Deploy the decocms locally using Docker Compose for testing and development icon: Container --- import Callout from "../../../../components/ui/Callout.astro"; -This guide covers deploying the MCP Mesh locally using Docker Compose for quick testing and development. +This guide covers deploying the decocms locally using Docker Compose for quick testing and development. -Learn more: [the MCP Mesh product page](https://www.decocms.com/mesh) +Learn more: [the decocms product page](https://www.decocms.com/mesh) Source (Docker Compose + README): [decocms/mesh/deploy](https://github.com/decocms/mesh/tree/main/deploy) @@ -47,7 +47,7 @@ open http://localhost:3000 ``` - These configurations are all you need to start testing with MCP-MESH. If you need other options, check the sections below. + These configurations are all you need to start testing with decocms. If you need other options, check the sections below. ### Minimum Configuration diff --git a/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx b/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx index 3014f280a9..d88cbdc714 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx @@ -33,7 +33,7 @@ The Mesh will: 5. log a monitoring event - If you need a single aggregated endpoint for multiple connections, use [Agents](/en/mcp-mesh/mcp-gateways) instead. + If you need a single aggregated endpoint for multiple connections, use [Agents](/en/mcp-mesh/virtual-mcps) instead. diff --git a/apps/docs/client/src/content/en/mcp-mesh/overview.mdx b/apps/docs/client/src/content/en/mcp-mesh/overview.mdx index ebb5e57b9c..7af1240a4a 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/overview.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/overview.mdx @@ -1,14 +1,14 @@ --- title: Overview -description: What the MCP Mesh is, what it solves, and the main product surfaces +description: What decocms is, what it solves, and the main product surfaces icon: Network --- import Callout from "../../../components/ui/Callout.astro"; -## What is the MCP Mesh? +## What is decocms? -The **MCP Mesh** is a **control plane for MCP traffic**. It sits between MCP clients (Cursor, Claude Desktop, custom agents) and MCP servers, providing a centralized layer for **authentication, authorization, credential management, and observability**. +**decocms** is a **control plane for MCP traffic**. It sits between MCP clients (Cursor, Claude Desktop, custom agents) and MCP servers, providing a centralized layer for **authentication, authorization, credential management, and observability**. ## The problem @@ -19,26 +19,26 @@ When MCP moves from a few PoCs to production usage, teams start paying an “int - **Operational blind spots**: no unified logs/traces to debug failures end-to-end - **Tool surface explosion**: too many tools increases context size, latency, and tool-selection errors -The Mesh centralizes these concerns once, so you can operate MCP traffic like any other production surface. +decocms centralizes these concerns once, so you can operate MCP traffic like any other production surface. ## High-level architecture ``` ┌───────────────────┐ ┌──────────────────┐ ┌────────────────────┐ -│ MCP Clients │ │ MCP Mesh (Proxy) │ │ Downstream MCPs │ +│ MCP Clients │ │ decocms (Proxy) │ │ Downstream MCPs │ │ - Cursor │──▶│ - AuthN/AuthZ │──▶│ - Slack / Gmail │ │ - Claude Desktop │ │ - Vault │ │ - Notion / Stripe │ -│ - Custom agents │ │ - Agents │ │ - Your MCP servers │ +│ - Custom agents │ │ - Virtual MCPs │ │ - Your MCP servers │ └───────────────────┘ │ - Monitoring │ └────────────────────┘ └──────────────────┘ ``` -## What the Mesh centralizes +## What decocms centralizes - **Routing + execution**: which MCP to call and how to authenticate it -- **Policy enforcement**: who can access which tools (and through which agents) +- **Policy enforcement**: who can access which tools (and through which virtual MCPs) - **Observability**: logs, latency, errors, and request context across tool calls -- **Runtime strategies (agents)**: different exposure strategies as tool surfaces grow +- **Runtime strategies (virtual MCPs)**: different exposure strategies as tool surfaces grow ## Product surfaces (what you can do today) @@ -51,8 +51,8 @@ The Mesh centralizes these concerns once, so you can operate MCP traffic like an - **Deploy**: self-host locally (npx / Docker Compose) or on Kubernetes (Helm). - We’re releasing the MCP Mesh to the open-source community in **December 2025**. - It’s new, so these docs reflect what exists **in production today** — but we ship new features every week and will keep updating this documentation as those features land. + We're releasing decocms to the open-source community in **December 2025**. + It's new, so these docs reflect what exists **in production today** — but we ship new features every week and will keep updating this documentation as those features land. diff --git a/apps/docs/client/src/content/en/mcp-mesh/mcp-gateways.mdx b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx similarity index 100% rename from apps/docs/client/src/content/en/mcp-mesh/mcp-gateways.mdx rename to apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx diff --git a/apps/docs/client/src/content/en/mcp-studio/overview.mdx b/apps/docs/client/src/content/en/mcp-studio/overview.mdx deleted file mode 100644 index 4c53ba02c9..0000000000 --- a/apps/docs/client/src/content/en/mcp-studio/overview.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Overview -description: No-code admin + SDK to package MCP capabilities as reusable building blocks (coming soon) -icon: LayoutDashboard ---- - -import Callout from "../../../components/ui/Callout.astro"; - -## What is MCP Studio? - -**MCP Studio** is the development layer of deco CMS: a **no-code admin + SDK** to package MCP-native capabilities into durable, reusable building blocks. - -Learn more: [MCP Studio product page](https://www.decocms.com/mcp-studio) - -Use it to turn **tools + schemas + workflows** into apps with: - -- Consistent interfaces -- Explicit permissions and policies -- Versioning and curation -- A safe path for other teams to adopt what works - - - **Coming soon:** MCP Studio is being built on top of **the MCP Mesh** and will replace the legacy SaaS admin (`admin.decocms.com`) over time (including a hosted option by us). - - -## Where does it fit? - -- **The MCP Mesh (foundation):** connect, govern, and observe MCP traffic -- **MCP Studio (development):** package and curate reusable capabilities -- **MCP Apps & Store (distribution):** distribute what works across teams - - diff --git a/apps/docs/client/src/content/pt-br/introduction.mdx b/apps/docs/client/src/content/pt-br/introduction.mdx index 40b34276b6..50b8b38ab8 100644 --- a/apps/docs/client/src/content/pt-br/introduction.mdx +++ b/apps/docs/client/src/content/pt-br/introduction.mdx @@ -1,6 +1,6 @@ --- title: Introdução -description: Documentação de desenvolvimento do MCP Mesh e da plataforma deco CMS +description: Documentação de desenvolvimento do decocms e da plataforma deco CMS icon: Rocket --- @@ -12,17 +12,16 @@ import Callout from "../../components/ui/Callout.astro"; **deco CMS** é um **Context Management System** open-source para operações nativas de IA. -Se MCP é a interface padrão para acesso a tools, o deco CMS é a **camada de produção ao redor disso**: conectar servidores MCP, aplicar governança e ter observabilidade conforme o uso escala entre times e ambientes. A plataforma mais ampla também inclui um **framework de builder** (MCP Studio — em breve, substituindo o admin legado) e **capacidades de distribuição** (módulos pré-construidos e uma store). +Se MCP é a interface padrão para acesso a tools, o deco CMS é a **camada de produção ao redor disso**: conectar servidores MCP, aplicar governança e ter observabilidade conforme o uso escala entre times e ambientes. **Links oficiais:** - **deco CMS**: [decocms.com](https://www.decocms.com/) -- **O MCP Mesh**: [decocms.com/mesh](https://www.decocms.com/mesh) -- **MCP Studio**: [decocms.com/mcp-studio](https://www.decocms.com/mcp-studio) +- **decocms**: [decocms.com/mesh](https://www.decocms.com/mesh) Se você conheceu a gente antes, como **deco.cx**, e está buscando **headless CMS + storefront**, visite [deco.cx](https://www.decocms.com/use-case/deco-cx). Veja a documentação do deco.cx em [docs.deco.cx](https://docs.deco.cx/en/getting-started/overview). -## Comece pelo MCP Mesh +## Comece com decocms Escolha uma opção: @@ -87,13 +86,13 @@ A aplicação ficará disponível em `http://localhost:8080`. **Mais detalhes:** [Kubernetes: Helm Chart](/pt-br/mcp-mesh/deploy/kubernetes-helm-chart) -## Aprenda o Mesh (conceitos + superfícies do produto) +## Aprenda decocms (conceitos + superfícies do produto) - **[Visão geral](/pt-br/mcp-mesh/overview)** - **[Quickstart](/pt-br/mcp-mesh/quickstart)** - **[Conceitos](/pt-br/mcp-mesh/concepts)** - **[MCP Servers](/pt-br/mcp-mesh/mcp-servers)** -- **[MCP Agents](/pt-br/mcp-mesh/mcp-gateways)** +- **[Virtual MCPs](/pt-br/mcp-mesh/virtual-mcps)** - **[API Keys](/pt-br/mcp-mesh/api-keys)** - **[Monitoring](/pt-br/mcp-mesh/monitoring)** - **[API Reference](/pt-br/mcp-mesh/api-reference)** @@ -101,10 +100,8 @@ A aplicação ficará disponível em `http://localhost:8080`. **Divisão da documentação (guia rápido):** - - **O MCP Mesh** → Auto-hospedagem, deploy e operação do Mesh (recomendado). + - **decocms** → Auto-hospedagem, deploy e operação do decocms (recomendado). - **Admin Legado** → Se você usa `admin.decocms.com` (ainda suportado, **em breve descontinuado**). - - Estamos lançando o **MCP Studio** (em cima do Mesh), que vai trazer as capacidades do admin SaaS atual para o Mesh (incluindo uma versão hospedada por nós) e substituir o SaaS legado ao longo do tempo. ## Problema: a lacuna entre demo e produção @@ -119,18 +116,11 @@ IA é fácil de demonstrar e difícil de **operar**. Para contexto sobre a visão da plataforma, leia [The architecture of an AI-native company](https://www.decocms.com/blog/post/ai-native-company). -## Estrutura da plataforma: Mesh → Studio → Apps & Store +## Estrutura da plataforma: Core → Apps & Store -### O MCP Mesh (fundação) +### decocms (fundação) Um **control plane** open-source para tráfego MCP. Ele fica entre seus clientes MCP (Cursor, Claude, VS Code, agentes customizados) e seus servidores MCP, oferecendo uma camada unificada de auth, policy e observabilidade. -### MCP Studio (desenvolvimento) -Um admin no-code + SDK para empacotar capacidades MCP como blocos reutilizáveis. - - - **Em breve:** este é o sucessor do admin SaaS atual, construído em cima do MCP Mesh. - - ### MCP Apps & Store (distribuição) Um caminho para distribuir capacidades MCP-native reutilizáveis entre times (e eventualmente uma store). diff --git a/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/kubernetes-helm-chart.mdx b/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/kubernetes-helm-chart.mdx index 9952104397..9c266f57db 100644 --- a/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/kubernetes-helm-chart.mdx +++ b/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/kubernetes-helm-chart.mdx @@ -1,14 +1,14 @@ --- title: "Kubernetes: Helm Chart" -description: Deploy do MCP Mesh no Kubernetes usando o Helm chart +description: Deploy do decocms no Kubernetes usando o Helm chart icon: Rocket --- import Callout from "../../../../components/ui/Callout.astro"; -Este guia explica como fazer deploy do MCP Mesh no Kubernetes usando o Helm chart. +Este guia explica como fazer deploy do decocms no Kubernetes usando o Helm chart. -Saiba mais: [página do MCP Mesh](https://www.decocms.com/mesh) +Saiba mais: [página do decocms](https://www.decocms.com/mesh) Código-fonte do Helm chart: [decocms/helm-chart-deco-mcp-mesh](https://github.com/decocms/helm-chart-deco-mcp-mesh) diff --git a/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/local-docker-compose.mdx b/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/local-docker-compose.mdx index 33b04c5640..af3cef27ef 100644 --- a/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/local-docker-compose.mdx +++ b/apps/docs/client/src/content/pt-br/mcp-mesh/deploy/local-docker-compose.mdx @@ -1,14 +1,14 @@ --- title: "Local: Docker Compose" -description: Deploy do MCP Mesh localmente usando Docker Compose para testes e desenvolvimento +description: Deploy do decocms localmente usando Docker Compose para testes e desenvolvimento icon: Container --- import Callout from "../../../../components/ui/Callout.astro"; -Este guia cobre o deploy do MCP Mesh localmente usando Docker Compose para testes rápidos e desenvolvimento. +Este guia cobre o deploy do decocms localmente usando Docker Compose para testes rápidos e desenvolvimento. -Saiba mais: [página do MCP Mesh](https://www.decocms.com/mesh) +Saiba mais: [página do decocms](https://www.decocms.com/mesh) Código-fonte (Docker Compose + README): [decocms/mesh/deploy](https://github.com/decocms/mesh/tree/main/deploy) @@ -47,7 +47,7 @@ open http://localhost:3000 ``` - Essas configurações são tudo que você precisa para começar a testar com o MCP-MESH. Se precisar de outras opções, confira as seções abaixo. + Essas configurações são tudo que você precisa para começar a testar com o decocms. Se precisar de outras opções, confira as seções abaixo. ### Configuração Mínima @@ -187,7 +187,7 @@ volumes: #### Quando é Carregado -A aplicação Mesh carrega este arquivo na inicialização para configurar: +A aplicação decocms carrega este arquivo na inicialização para configurar: - Autenticação por Email/Senha - Provedores sociais (Google, GitHub) diff --git a/apps/docs/client/src/content/pt-br/mcp-mesh/overview.mdx b/apps/docs/client/src/content/pt-br/mcp-mesh/overview.mdx index 15a961c739..47f89d90cc 100644 --- a/apps/docs/client/src/content/pt-br/mcp-mesh/overview.mdx +++ b/apps/docs/client/src/content/pt-br/mcp-mesh/overview.mdx @@ -1,14 +1,14 @@ --- title: Visão geral -description: O que é o MCP Mesh, o problema que ele resolve e as principais superfícies do produto +description: O que é decocms, o problema que ele resolve e as principais superfícies do produto icon: Network --- import Callout from "../../../components/ui/Callout.astro"; -## O que é o MCP Mesh? +## O que é decocms? -O **MCP Mesh** é um **control plane para tráfego MCP**. Ele fica entre clientes MCP (Cursor, Claude Desktop, agentes) e servidores MCP, oferecendo uma camada centralizada de **autenticação, autorização, vault de credenciais e observabilidade**. +**decocms** é um **control plane para tráfego MCP**. Ele fica entre clientes MCP (Cursor, Claude Desktop, agentes) e servidores MCP, oferecendo uma camada centralizada de **autenticação, autorização, vault de credenciais e observabilidade**. ## O problema @@ -19,39 +19,39 @@ Quando MCP sai de alguns PoCs e vai para produção, os times começam a pagar u - **Pontos cegos operacionais**: falta um lugar único para ver logs/traces e depurar ponta a ponta - **Explosão de tools**: muitas tools aumentam contexto, latência e pioram a seleção de tool -O Mesh centraliza isso uma vez, para você operar MCP como qualquer outra superfície de produção. +decocms centraliza isso uma vez, para você operar MCP como qualquer outra superfície de produção. ## Arquitetura (alto nível) ``` ┌───────────────────┐ ┌──────────────────┐ ┌────────────────────┐ -│ MCP Clients │ │ MCP Mesh (Proxy) │ │ Downstream MCPs │ +│ MCP Clients │ │ decocms (Proxy) │ │ Downstream MCPs │ │ - Cursor │──▶│ - AuthN/AuthZ │──▶│ - Slack / Gmail │ │ - Claude Desktop │ │ - Vault │ │ - Notion / Stripe │ -│ - Custom agents │ │ - Agents │ │ - Seus MCP servers │ +│ - Custom agents │ │ - Virtual MCPs │ │ - Seus MCP servers │ └───────────────────┘ │ - Monitoring │ └────────────────────┘ └──────────────────┘ ``` -## O que o Mesh centraliza +## O que decocms centraliza - **Roteamento + execução**: qual MCP chamar e como autenticar -- **Policy enforcement**: quem pode acessar quais tools (e via quais agents) +- **Policy enforcement**: quem pode acessar quais tools (e via quais virtual MCPs) - **Observabilidade**: logs, latência, erros e contexto de requisição -- **Runtime strategies (agents)**: diferentes estratégias de exposição de tools conforme a superfície cresce +- **Runtime strategies (virtual MCPs)**: diferentes estratégias de exposição de tools conforme a superfície cresce ## Superfícies do produto (o que dá para fazer hoje) - **Store**: catálogo de Conexões para conectar (por padrão: o **MCP Registry** oficial). - **Conexões**: conectar e gerenciar MCP servers (endpoints MCP via HTTP). -- **Agents**: publicar um "MCP virtual" curado que agrega tools/resources/prompts de múltiplas conexões. +- **Virtual MCPs**: publicar um "MCP virtual" curado que agrega tools/resources/prompts de múltiplas conexões. - **API Keys**: criar chaves com permissões explícitas. - **Members & Roles**: convidar pessoas e gerenciar roles + permissões. - **Monitoring**: logs de tool calls, erros, latência, filtros e streaming. - **Deploy**: auto-hospedar localmente (npx / Docker Compose) ou em Kubernetes (Helm). - Estamos lançando o MCP Mesh para a comunidade open-source em **dezembro de 2025**. + Estamos lançando decocms para a comunidade open-source em **dezembro de 2025**. Ele ainda é novo: esta documentação reflete o que existe **em produção hoje**, mas estamos lançando features toda semana e vamos atualizar os docs conforme elas forem chegando. diff --git a/apps/docs/client/src/content/pt-br/mcp-mesh/mcp-gateways.mdx b/apps/docs/client/src/content/pt-br/mcp-mesh/virtual-mcps.mdx similarity index 100% rename from apps/docs/client/src/content/pt-br/mcp-mesh/mcp-gateways.mdx rename to apps/docs/client/src/content/pt-br/mcp-mesh/virtual-mcps.mdx diff --git a/apps/docs/client/src/content/pt-br/mcp-studio/overview.mdx b/apps/docs/client/src/content/pt-br/mcp-studio/overview.mdx deleted file mode 100644 index ecd1f0c309..0000000000 --- a/apps/docs/client/src/content/pt-br/mcp-studio/overview.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Visão Geral -description: Admin no-code + SDK para empacotar capacidades MCP como blocos reutilizáveis (em breve) -icon: LayoutDashboard ---- - -import Callout from "../../../components/ui/Callout.astro"; - -## O que é MCP Studio? - -**MCP Studio** é a camada de desenvolvimento do deco CMS: um **admin no-code + SDK** para empacotar capacidades MCP-native como blocos duráveis e reutilizáveis. - -Saiba mais: [página do MCP Studio](https://www.decocms.com/mcp-studio) - -Ele transforma **tools + schemas + workflows** em apps com: - -- Interfaces consistentes -- Permissões e políticas explícitas -- Versionamento e curadoria -- Um caminho seguro para outros times adotarem o que funciona - - - **Em breve:** o MCP Studio está sendo construído em cima do **MCP Mesh** e vai substituir o admin SaaS legado (`admin.decocms.com`) ao longo do tempo (incluindo uma versão hospedada por nós). - - -## Onde isso se encaixa? - -- **O MCP Mesh (fundação):** conectar, governar e observar tráfego MCP -- **MCP Studio (desenvolvimento):** empacotar e curar capacidades reutilizáveis -- **MCP Apps & Store (distribuição):** distribuir o que funciona entre times - - diff --git a/apps/docs/client/src/i18n/ui.ts b/apps/docs/client/src/i18n/ui.ts index 9490d6c438..93bc6437d8 100644 --- a/apps/docs/client/src/i18n/ui.ts +++ b/apps/docs/client/src/i18n/ui.ts @@ -12,8 +12,7 @@ export const ui = { "sidebar.section.getting-started": "Getting Started", "sidebar.section.no-code-guides": "No-Code Guides", "sidebar.section.full-code-guides": "Full-Code Guides", - "sidebar.section.mcp-mesh": "MCP Mesh", - "sidebar.section.mcp-studio": "MCP Studio", + "sidebar.section.mcp-mesh": "decocms", "sidebar.section.deploy": "Deploy", "hero.title": "Build AI Agents That Connect Everything", "hero.subtitle": @@ -30,8 +29,7 @@ export const ui = { "sidebar.section.getting-started": "Primeiros Passos", "sidebar.section.no-code-guides": "Guias No-Code", "sidebar.section.full-code-guides": "Guias Full-Code", - "sidebar.section.mcp-mesh": "MCP Mesh", - "sidebar.section.mcp-studio": "MCP Studio", + "sidebar.section.mcp-mesh": "decocms", "sidebar.section.deploy": "Deploy", "hero.title": "Construa Agentes de IA Que Conectam Tudo", "hero.subtitle": diff --git a/apps/docs/client/src/utils/navigation.ts b/apps/docs/client/src/utils/navigation.ts index 5b676c92b4..c0da3e0f70 100644 --- a/apps/docs/client/src/utils/navigation.ts +++ b/apps/docs/client/src/utils/navigation.ts @@ -16,7 +16,7 @@ export async function getNavigationLinks( // Define the correct order for navigation const order = [ "introduction", - // MCP Mesh (product docs) + // decocms (product docs) "mcp-mesh/overview", "mcp-mesh/quickstart", "mcp-mesh/concepts", @@ -24,7 +24,7 @@ export async function getNavigationLinks( "mcp-mesh/authentication", "mcp-mesh/authorization-and-roles", "mcp-mesh/mcp-servers", - "mcp-mesh/mcp-gateways", + "mcp-mesh/virtual-mcps", "mcp-mesh/api-keys", "mcp-mesh/monitoring", "mcp-mesh/api-reference", From a1dab270bf1be394e0e4031e1f915471c0a324d3 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 16:12:58 -0300 Subject: [PATCH 02/51] docs: refactor agents/gateways terminology to Virtual MCPs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update English documentation to use consistent "Virtual MCPs" terminology: - Replace all "Agent" and "Gateway" references with "Virtual MCP" - Update endpoints: /mcp/gateway/:gatewayId → /mcp/virtual/:virtualId - Update tool names: GATEWAY_* → VIRTUAL_* - Establish Virtual MCPs as foundational concept This aligns documentation with planned system architecture and unblocks narrative documentation work in main-54j. Closes beads-main-o55 Co-Authored-By: Claude Sonnet 4.5 --- .../src/content/en/mcp-mesh/virtual-mcps.mdx | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx index 757ee00b60..dc4b5af50d 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx @@ -1,14 +1,14 @@ --- -title: Agents +title: Virtual MCPs description: Publish a virtual MCP server that aggregates tools/resources/prompts from multiple connections icon: Waypoints --- import Callout from "../../../components/ui/Callout.astro"; -## What is an Agent? +## What is a Virtual MCP? -An **Agent** is a **virtual MCP server** that aggregates multiple connections into a single MCP surface: +A **Virtual MCP** is a foundational concept in MCP Mesh—it's a **virtual MCP server** that aggregates multiple connections into a single MCP surface: - tools (`tools/list`, `tools/call`) - resources (`resources/list`, `resources/read`) @@ -18,9 +18,9 @@ This is how you create a curated endpoint for clients without exposing every too ## Endpoint -- `POST /mcp/gateway/:gatewayId` +- `POST /mcp/virtual/:virtualId` -You can also omit `:gatewayId` and rely on the organization's default Agent by providing one of these headers: +You can also omit `:virtualId` and rely on the organization's default Virtual MCP by providing one of these headers: - `x-org-id`, or - `x-org-slug` @@ -32,44 +32,44 @@ You can also omit `:gatewayId` and rely on the organization's default Agent by p ## Tool exposure strategies -Agents also control **how tools are exposed** to clients (useful when tool surfaces get large). +Virtual MCPs also control **how tools are exposed** to clients (useful when tool surfaces get large). These strategies ship by default: ### Passthrough (baseline) -- Exposes all agent tools directly via `tools/list`. +- Exposes all Virtual MCP tools directly via `tools/list`. - Best for small tool surfaces and deterministic behavior. ### Smart tool selection - Exposes meta-tools for discovery and targeted execution: - - `GATEWAY_SEARCH_TOOLS` (keyword search) - - `GATEWAY_DESCRIBE_TOOLS` (fetch full schemas) - - `GATEWAY_CALL_TOOL` (execute a chosen tool) + - `VIRTUAL_SEARCH_TOOLS` (keyword search) + - `VIRTUAL_DESCRIBE_TOOLS` (fetch full schemas) + - `VIRTUAL_CALL_TOOL` (execute a chosen tool) - Goal: keep the tool list small and let the client request details on demand. ### Code execution - Exposes meta-tools for discovery + sandboxed execution: - - `GATEWAY_SEARCH_TOOLS` - - `GATEWAY_DESCRIBE_TOOLS` - - `GATEWAY_RUN_CODE` (run JS in a sandbox that can call tools) + - `VIRTUAL_SEARCH_TOOLS` + - `VIRTUAL_DESCRIBE_TOOLS` + - `VIRTUAL_RUN_CODE` (run JS in a sandbox that can call tools) - Goal: reduce tool exposure overhead on large surfaces by shifting work into a constrained runtime. -## The default Agent (auto-created per org) +## The default Virtual MCP (auto-created per org) -Every new organization gets a **Default Agent**: +Every new organization gets a **Default Virtual MCP**: - **Strategy**: `passthrough` - **Mode**: `exclusion` - **Default exclusions**: the built-in **Mesh MCP** connection (management tools) and the **Store/Registry** connection are excluded by default -- **Default behavior**: everything else in the org is included — so as you connect Integrations, this endpoint becomes the "all tools in the org" Agent +- **Default behavior**: everything else in the org is included — so as you connect Integrations, this endpoint becomes the "all tools in the org" Virtual MCP This is the endpoint most teams use as the single aggregated MCP surface for an org. ## Benchmark: strategy tradeoffs -We ran an agent strategy benchmark here: [MCP Agent Benchmark (GitHub Actions run)](https://github.com/decocms/mesh/actions/runs/20584203227). +We ran a Virtual MCP strategy benchmark here: [MCP Virtual MCP Benchmark (GitHub Actions run)](https://github.com/decocms/mesh/actions/runs/20584203227). **Summary (high level):** @@ -84,7 +84,7 @@ If you want the raw numbers, open the run and download the **benchmark-results** ## Code Execution Tools in the Management MCP -In addition to gateway strategies, you can use code execution tools directly from the **Management MCP** (`/mcp`): +In addition to Virtual MCP strategies, you can use code execution tools directly from the **Management MCP** (`/mcp`): - `CODE_EXECUTION_SEARCH_TOOLS` - search tools by name or description - `CODE_EXECUTION_DESCRIBE_TOOLS` - get detailed tool schemas @@ -92,7 +92,7 @@ In addition to gateway strategies, you can use code execution tools directly fro These tools operate on: - All active connections in the organization (by default) -- Agent-specific connections (if `gatewayId` is set in context) +- Virtual MCP-specific connections (if `virtualId` is set in context) -This lets you use the code execution paradigm without configuring a specific gateway strategy. +This lets you use the code execution paradigm without configuring a specific Virtual MCP strategy. From c52ab3137a1d334cf5afd20bb70920bb89ab6914 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 16:29:43 -0300 Subject: [PATCH 03/51] docs: document virtual MCPs with narrative structure Created comprehensive documentation for Virtual MCPs following clear narrative: - MCP compliance and benefits (protocol for action) - Challenge of traditional MCP servers (infrastructure overhead) - Solution: Virtual MCPs (on-demand, no server code) - Two approaches: Composition (mix existing) + Inline (create directly) - Hybrid capability combining both approaches - Configuration and tool exposure strategies - Code examples for all three patterns Target: 700-900 words, achieved exactly 900 words Fixed broken links, clarified terminology throughout Closes beads-main-54j Co-Authored-By: Claude Sonnet 4.5 --- .../src/content/en/mcp-mesh/virtual-mcps.mdx | 238 ++++++++++++------ 1 file changed, 162 insertions(+), 76 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx index dc4b5af50d..6dee49ba85 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx @@ -1,98 +1,184 @@ --- title: Virtual MCPs -description: Publish a virtual MCP server that aggregates tools/resources/prompts from multiple connections +description: Create MCP servers on the spot without writing server code or managing infrastructure icon: Waypoints --- import Callout from "../../../components/ui/Callout.astro"; -## What is a Virtual MCP? +## MCP Compliance & Benefits + +decocms is fully **MCP compliant**, following the Model Context Protocol specification. MCPs let AI agents work beyond your computer—acting on databases, APIs, SaaS tools, and production systems. MCP is a **protocol for action**, enabling agents to read, write, and orchestrate across your infrastructure. + +## The Challenge -A **Virtual MCP** is a foundational concept in MCP Mesh—it's a **virtual MCP server** that aggregates multiple connections into a single MCP surface: +Creating traditional MCP servers requires writing server code, managing infrastructure, and maintaining updates—a barrier that prevents many teams from leveraging MCP's full potential. -- tools (`tools/list`, `tools/call`) -- resources (`resources/list`, `resources/read`) -- prompts (`prompts/list`, `prompts/get`) +## Virtual MCPs: The Solution -This is how you create a curated endpoint for clients without exposing every tool from every connected integration. +**Virtual MCPs** are decocms's answer to this challenge. They let you **create MCP servers on the spot**, without writing server code or managing infrastructure. + +A Virtual MCP is a **virtual MCP server** that aggregates tools, resources, and prompts into a single MCP-compliant endpoint. Instead of writing and deploying server code, you configure what capabilities to expose—and decocms handles the rest. + +Virtual MCPs are: + +- **Dynamically created**: spin up new MCPs through configuration, not code +- **Production-ready**: fully MCP-compliant endpoints that work with any MCP client +- **Instantly updated**: attach new tools or resources without redeploying servers +- **Foundation for advanced features**: the building block for agents and organizational tooling + +## How Virtual MCPs Work + +Virtual MCPs can be created in two fundamental ways, and you can mix both approaches as needed. + +### Approach 1: Composition (Mix Existing Connections) + +**Composition** lets you aggregate capabilities from multiple connected MCP servers into a unified virtual MCP. + +Here's how it works: + +1. **Connect MCP servers** to your decocms instance (GitHub, Slack, databases, etc.) +2. **Select tools** from one or more connections you want to expose +3. **Configure the virtual MCP** to include these selected capabilities +4. **Get a single endpoint** that exposes the aggregated toolset + +**Example**: Create a "deployment" virtual MCP that combines: +- GitHub tools (create PRs, merge, tag releases) +- Slack tools (post updates, create threads) +- Database tools (run migrations, verify schema) + +Your AI agent connects to one virtual MCP endpoint and gets access to all three systems. + +```typescript +// Configuration example: composition approach +{ + "name": "deployment-virtual-mcp", + "mode": "include", + "connections": [ + { + "connectionId": "github-conn-123", + "tools": ["CREATE_PR", "MERGE_PR", "CREATE_TAG"] + }, + { + "connectionId": "slack-conn-456", + "tools": ["POST_MESSAGE", "CREATE_THREAD"] + }, + { + "connectionId": "database-conn-789", + "tools": ["RUN_MIGRATION", "VERIFY_SCHEMA"] + } + ] +} +``` -## Endpoint +### Approach 2: Inline Creation -- `POST /mcp/virtual/:virtualId` +**Inline creation** lets you create resources, prompts, and tools directly within decocms—no external MCP server needed. -You can also omit `:virtualId` and rely on the organization's default Virtual MCP by providing one of these headers: +This is perfect for: -- `x-org-id`, or -- `x-org-slug` +- **Custom prompts** tailored to your team's workflows +- **Resources** like documentation, guidelines, or context +- **Tools** that orchestrate other tools or implement custom logic -## Selection modes +**Example**: Create a virtual MCP with inline prompts for code review: -- **Include**: only the listed connections/tools are exposed. -- **Exclude**: expose the whole org surface *except* excluded connections/tools. +```typescript +// Configuration example: inline approach +{ + "name": "code-review-virtual-mcp", + "prompts": [ + { + "name": "security-review", + "description": "Review code for security vulnerabilities", + "template": "Analyze this code for security issues:\n- SQL injection\n- XSS vulnerabilities\n- Auth bypasses\n\nCode:\n{{code}}" + }, + { + "name": "performance-review", + "description": "Review code for performance issues", + "template": "Analyze this code for performance problems:\n- N+1 queries\n- Memory leaks\n- Inefficient algorithms\n\nCode:\n{{code}}" + } + ], + "resources": [ + { + "uri": "review://guidelines", + "name": "Code Review Guidelines", + "mimeType": "text/markdown", + "content": "# Review Guidelines\n\n1. Security first\n2. Performance matters\n..." + } + ] +} +``` -## Tool exposure strategies +### Hybrid: Mix Both Approaches -Virtual MCPs also control **how tools are exposed** to clients (useful when tool surfaces get large). -These strategies ship by default: +Combine composition and inline creation in the same virtual MCP: -### Passthrough (baseline) +```typescript +// Hybrid example: external tools + inline prompts +{ + "name": "development-assistant", + "connections": [ + { + "connectionId": "github-conn-123", + "tools": ["CREATE_PR", "LIST_ISSUES"] + } + ], + "prompts": [ + { + "name": "pr-template", + "description": "Generate PR description from commits", + "template": "Create a PR description from these commits:\n{{commits}}" + } + ] +} +``` + +This virtual MCP exposes GitHub tools from an external connection alongside custom prompts defined inline. + +## Virtual MCP Configuration + +Virtual MCPs are dynamically configurable: + +- **Tool selection**: `include` (whitelist specific tools) or `exclude` (blacklist specific tools) +- **Runtime strategies**: control how tools are exposed (see Tool Exposure Strategies below) +- **Dynamic updates**: attach new tools, resources, or prompts +- **Endpoint**: Each virtual MCP gets a unique endpoint at `/mcp/virtual/:virtualId` + +Every organization gets a **default virtual MCP** that aggregates all connections using `passthrough` strategy and `exclude` selection (management MCP excluded by default). + +## Tool Exposure Strategies + +Virtual MCPs offer different runtime strategies for exposing tools: + +- **Passthrough**: Exposes all tools via `tools/list`. Best for small surfaces. +- **Smart Selection**: Exposes meta-tools (`VIRTUAL_SEARCH_TOOLS`, `VIRTUAL_DESCRIBE_TOOLS`, `VIRTUAL_CALL_TOOL`) for on-demand discovery. +- **Code Execution**: Adds sandboxed `VIRTUAL_RUN_CODE` for JavaScript-based tool orchestration. + +## Concepts Built on Virtual MCPs + +Virtual MCPs are the **foundational feature** for specialized capabilities: + +- **Agents**: Single-purpose virtual MCPs optimized for specific tasks (see [Concepts](/en/mcp-mesh/concepts)) +- **Organization MCP**: Default virtual MCP that aggregates all your connections + +## Use Cases + +- **Unified Deployment**: Mix GitHub, Slack, and database MCPs into one endpoint for CI/CD workflows +- **Custom Code Review**: Define inline prompts tailored to your team's review process +- **Hybrid Development Assistant**: Combine external tools (GitHub, Jira) with inline prompts for contextual guidance + +## Benefits Summary -- Exposes all Virtual MCP tools directly via `tools/list`. -- Best for small tool surfaces and deterministic behavior. +Virtual MCPs eliminate infrastructure barriers: + +- **No server code or infrastructure**: configure capabilities, decocms handles hosting +- **Dynamic updates**: modify tools and resources without downtime +- **Composition and inline creation**: aggregate existing MCPs or define custom logic +- **Foundation for advanced workflows**: building block for agents and organizational tooling + +Virtual MCPs make MCP accessible to every team—no DevOps required. -### Smart tool selection - -- Exposes meta-tools for discovery and targeted execution: - - `VIRTUAL_SEARCH_TOOLS` (keyword search) - - `VIRTUAL_DESCRIBE_TOOLS` (fetch full schemas) - - `VIRTUAL_CALL_TOOL` (execute a chosen tool) -- Goal: keep the tool list small and let the client request details on demand. - -### Code execution - -- Exposes meta-tools for discovery + sandboxed execution: - - `VIRTUAL_SEARCH_TOOLS` - - `VIRTUAL_DESCRIBE_TOOLS` - - `VIRTUAL_RUN_CODE` (run JS in a sandbox that can call tools) -- Goal: reduce tool exposure overhead on large surfaces by shifting work into a constrained runtime. - -## The default Virtual MCP (auto-created per org) - -Every new organization gets a **Default Virtual MCP**: - -- **Strategy**: `passthrough` -- **Mode**: `exclusion` -- **Default exclusions**: the built-in **Mesh MCP** connection (management tools) and the **Store/Registry** connection are excluded by default -- **Default behavior**: everything else in the org is included — so as you connect Integrations, this endpoint becomes the "all tools in the org" Virtual MCP - -This is the endpoint most teams use as the single aggregated MCP surface for an org. - -## Benchmark: strategy tradeoffs - -We ran a Virtual MCP strategy benchmark here: [MCP Virtual MCP Benchmark (GitHub Actions run)](https://github.com/decocms/mesh/actions/runs/20584203227). - -**Summary (high level):** - -- **Small tool surface (~10 tools)**: - - **Passthrough** used fewer tokens, but had lower success than **Code execution** - - **Smart tool selection** was the least reliable in this run -- **Large tool surface (~128 tools)**: - - **Code execution** reduced token usage substantially vs **Passthrough** and had the highest success - - **Smart tool selection** was the most expensive in tokens in this run - -If you want the raw numbers, open the run and download the **benchmark-results** artifact. - -## Code Execution Tools in the Management MCP - -In addition to Virtual MCP strategies, you can use code execution tools directly from the **Management MCP** (`/mcp`): - -- `CODE_EXECUTION_SEARCH_TOOLS` - search tools by name or description -- `CODE_EXECUTION_DESCRIBE_TOOLS` - get detailed tool schemas -- `CODE_EXECUTION_RUN_CODE` - run JS in a sandbox with tool access - -These tools operate on: -- All active connections in the organization (by default) -- Virtual MCP-specific connections (if `virtualId` is set in context) - -This lets you use the code execution paradigm without configuring a specific Virtual MCP strategy. +--- +**Ready to create your first virtual MCP?** Head to the [Quickstart](/en/mcp-mesh/quickstart) to get started, or learn about [Connections](/en/mcp-mesh/mcp-servers) to understand how to wire up external MCP servers. From c756eebbeb6a237f3dfb1e3d8b0b85148588b122 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 16:38:38 -0300 Subject: [PATCH 04/51] docs: simplify virtual MCPs configuration section Removed exclusion mode documentation - only document inclusion mode Removed tool exposure strategies section (planned for removal in future) Simplified default virtual MCP explanation Word count: 830 (within 700-900 target) Co-Authored-By: Claude Sonnet 4.5 --- .../client/src/content/en/mcp-mesh/virtual-mcps.mdx | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx index 6dee49ba85..d535bbc306 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx @@ -140,20 +140,11 @@ This virtual MCP exposes GitHub tools from an external connection alongside cust Virtual MCPs are dynamically configurable: -- **Tool selection**: `include` (whitelist specific tools) or `exclude` (blacklist specific tools) -- **Runtime strategies**: control how tools are exposed (see Tool Exposure Strategies below) +- **Tool selection**: Specify which tools to include from each connection - **Dynamic updates**: attach new tools, resources, or prompts - **Endpoint**: Each virtual MCP gets a unique endpoint at `/mcp/virtual/:virtualId` -Every organization gets a **default virtual MCP** that aggregates all connections using `passthrough` strategy and `exclude` selection (management MCP excluded by default). - -## Tool Exposure Strategies - -Virtual MCPs offer different runtime strategies for exposing tools: - -- **Passthrough**: Exposes all tools via `tools/list`. Best for small surfaces. -- **Smart Selection**: Exposes meta-tools (`VIRTUAL_SEARCH_TOOLS`, `VIRTUAL_DESCRIBE_TOOLS`, `VIRTUAL_CALL_TOOL`) for on-demand discovery. -- **Code Execution**: Adds sandboxed `VIRTUAL_RUN_CODE` for JavaScript-based tool orchestration. +Every organization gets a **default virtual MCP** that aggregates all connections. ## Concepts Built on Virtual MCPs From 20ccfd27a71f0a7e4f66b5169418e483da7f938f Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 16:47:58 -0300 Subject: [PATCH 05/51] docs: document MCP Mesh projects concept Create comprehensive documentation for projects as virtual MCPs at the organization level. Projects are organizational units that ARE virtual MCPs themselves and can aggregate capabilities from other virtual MCPs within their scope. Key sections: - Projects as virtual MCPs with composition capabilities - Configuration hierarchy (project-level vs org-admin) - Project scope and routing (/:org/projects/:project_id) - CLAUDE.md and AGENTS.md support at both levels - MCP client operation within project scope - Practical examples and use cases Includes planned architecture callout and comparison to Claude Code's .claude/ configuration pattern. Closes beads-main-ko2 Co-Authored-By: Claude Sonnet 4.5 --- .../src/content/en/mcp-mesh/projects.mdx | 182 ++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 apps/docs/client/src/content/en/mcp-mesh/projects.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/projects.mdx b/apps/docs/client/src/content/en/mcp-mesh/projects.mdx new file mode 100644 index 0000000000..8a7764a083 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/projects.mdx @@ -0,0 +1,182 @@ +--- +title: Projects +description: Organizational units that are virtual MCPs with their own tools, resources, and configuration +icon: FolderTree +--- + +import Callout from "../../../components/ui/Callout.astro"; + + + This page documents the **planned architecture** for projects in MCP Mesh. The implementation is in development. + + +## What are Projects? + +**Projects** are organizational units that **are virtual MCPs themselves**. Unlike traditional project management systems where projects are mere containers, in MCP Mesh a project is a fully-functional virtual MCP server with its own tools, resources, and configuration. + +Projects enable teams to: + +- **Organize work** by product, client, or initiative +- **Scope capabilities** to specific contexts +- **Configure connections** at both project and organization levels +- **Operate within boundaries** that match your organizational structure + +Each project is accessible at `/:org/projects/:project_id` and operates as a self-contained virtual MCP. + +## Projects as Virtual MCPs + +Projects are virtual MCPs at the organization level—they are the primary organizational container for work. Each project has: + +- **Tools**: Project-specific tools or aggregated from connected MCPs +- **Resources**: Documentation, guidelines, context files +- **Prompts**: Custom templates for common workflows + +Projects can connect to other virtual MCPs (including agents), compose capabilities from multiple sources, and define inline tools—just like any [Virtual MCP](/en/mcp-mesh/virtual-mcps). The key distinction: projects ARE virtual MCPs themselves, and they can aggregate capabilities from other virtual MCPs within their scope. + +```typescript +// Example: Project as virtual MCP +{ + "projectId": "mobile-app-rewrite", + "name": "Mobile App Rewrite", + "connections": [ + { + "connectionId": "github-conn-123", + "tools": ["CREATE_PR", "LIST_ISSUES", "CREATE_BRANCH"] + }, + { + "connectionId": "figma-conn-456", + "tools": ["GET_DESIGN", "EXPORT_ASSETS"] + } + ], + "prompts": [ + { + "name": "mobile-pr-template", + "description": "PR template for mobile features", + "template": "## Mobile Feature PR\n\n### Changes\n{{changes}}\n\n### Testing\n- [ ] iOS tested\n- [ ] Android tested" + } + ], + "resources": [ + { + "uri": "project://mobile-app-rewrite/guidelines", + "name": "Mobile Development Guidelines", + "mimeType": "text/markdown", + "content": "# Mobile Guidelines\n\n- Always test on both platforms..." + } + ] +} +``` + +## Configuration Hierarchy + +MCP Mesh supports **two levels of configuration**: + +**Project-level** (`/:org/projects/:project_id`): +- Project-specific tools and resources +- Project's `CLAUDE.md` and `AGENTS.md` +- Connections configured for this project + +**Organization-level** (`/:org`): +- Organization-wide tools available across all projects +- Shared resources and prompts +- Organization `CLAUDE.md` and `AGENTS.md` + +This mirrors Claude Code's familiar pattern: **`.claude/`** (project) and **`~/.claude/`** (global). + +## Project Scope and Routing + +The route determines the operational scope. When connecting to: + +``` +/:org/projects/:project_id +``` + +MCP clients operate within that project's virtual MCP boundary, accessing: + +- Project's own resources, tools, and prompts +- Connections dynamically wired to the project +- Project-specific context from `CLAUDE.md` and `AGENTS.md` + + + Scope isolation ensures that project A cannot access project B's tools or credentials, while still allowing shared organization-level capabilities. + + +## CLAUDE.md and AGENTS.md Support + +Both levels support configuration files loaded into context: + +**CLAUDE.md**: Provides contextual instructions for AI agents +- **Project-level**: Project-specific coding standards, domain knowledge, workflows +- **Organization-level**: Company-wide guidelines, security policies, best practices + +**AGENTS.md**: Defines specialized capabilities via MCP server instructions +- **Project-level**: Project-specific agent configurations +- **Organization-level**: Cross-project agent configurations + +## MCP Clients in Project Scope + +When MCP clients connect to a project, they become scope-aware: + +```typescript +// MCP client operation in project scope +{ + "scope": "/:org/projects/mobile-app-rewrite", + "availableTools": [ + "CREATE_PR", // from GitHub connection + "GET_DESIGN", // from Figma connection + "RUN_MOBILE_TESTS" // project-specific tool + ], + "availableResources": [ + "project://mobile-app-rewrite/guidelines" + ] +} +``` + +AI agents can use any organization-level or project-specific capabilities to accomplish tasks, always operating within the project's boundary. + +## Example: E-commerce Redesign Project + +```typescript +{ + "projectId": "ecommerce-redesign", + "name": "E-commerce Platform Redesign", + "connections": [ + { + "connectionId": "shopify-conn-789", + "tools": ["GET_PRODUCTS", "UPDATE_THEME", "DEPLOY_STOREFRONT"] + }, + { + "connectionId": "analytics-conn-101", + "tools": ["GET_CONVERSION_RATE", "GET_USER_FLOW"] + } + ], + "resources": [ + { + "uri": "project://ecommerce-redesign/brand-guidelines", + "name": "Brand Guidelines", + "mimeType": "text/markdown" + } + ] +} +``` + +AI agents can deploy storefronts, analyze conversion metrics, and reference brand guidelines—all within the project's scope. + +## Use Cases + +- **Client Projects**: Agencies can create one project per client, each with client-specific tools and credentials +- **Product Lines**: Separate projects for web, mobile, and backend with different toolsets +- **Feature Development**: Temporary projects for major features, with curated tools for that work +- **Multi-tenant SaaS**: Projects as tenant boundaries with isolated capabilities + +## Benefits + +Projects as virtual MCPs provide: + +- **Clear boundaries**: Scope isolation prevents cross-contamination +- **Flexible configuration**: Two-level hierarchy matches organizational structure +- **Dynamic capabilities**: Add or remove tools without infrastructure changes +- **Familiar patterns**: Mirrors `.claude/` local and `~/.claude/` global convention + +--- + +**Ready to create your first project?** Projects are built on [Virtual MCPs](/en/mcp-mesh/virtual-mcps)—start there to understand the underlying system. For authorization details, see [Authorization and Roles](/en/mcp-mesh/authorization-and-roles). From 84544cd2d1c84c4535fa480a9db661dbc2d09310 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 17:10:04 -0300 Subject: [PATCH 06/51] docs: document agents as single-purpose virtual MCPs Create comprehensive documentation for agents concept in MCP Mesh. Agents are single-purpose virtual MCPs designed for specific tasks, distinguished from general-purpose projects. Key content: - Agent fundamentals as virtual MCPs - Distinction between agents and projects - Creating agents (composition, inline, hybrid modes) - Agent configuration and AGENTS.md support - Built-in agents and mesh MCP concept (self-referential) - Agent types and patterns (research, development, testing, deployment) - Single-purpose design philosophy - Agent scope and usage Includes 8 TypeScript configuration examples and comprehensive documentation of 5 built-in agents (agent management, connection management, permission management, MCP store, user management). Note: Documents PLANNED decopilot architecture for development guidance. Closes beads-main-589 Co-Authored-By: Claude Sonnet 4.5 --- .../client/src/content/en/mcp-mesh/agents.mdx | 490 ++++++++++++++++++ 1 file changed, 490 insertions(+) create mode 100644 apps/docs/client/src/content/en/mcp-mesh/agents.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx new file mode 100644 index 0000000000..551efe8d91 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx @@ -0,0 +1,490 @@ +--- +title: Agents +description: Single-purpose virtual MCPs designed for specific tasks +icon: Bot +--- + +import Callout from "../../../components/ui/Callout.astro"; + + + This page documents the **planned architecture** for agents in MCP Mesh. The implementation is in development. + + +## What Are Agents? + +**Agents** are single-purpose virtual MCPs optimized for specific tasks. While [Projects](/en/mcp-mesh/projects) provide general-purpose, project-level work environments, agents are narrowly focused on accomplishing one thing well. + +An agent is a complete virtual MCP with its own: + +- **Tools**: Curated for the agent's specific purpose +- **Resources**: Context and documentation relevant to the task +- **Prompts**: Templates tailored to the agent's workflow +- **Configuration**: Agent-specific settings and constraints + +Agents are built on the [Virtual MCP](/en/mcp-mesh/virtual-mcps) foundation—they ARE virtual MCPs, not just connections to them. This means agents can expose tools, resources, and prompts through the MCP protocol, making them first-class participants in your MCP ecosystem. + +## Agents vs. Projects + +Understanding the distinction between agents and projects is key: + +**Projects** are general-purpose organizational units for ongoing work: +- Broad scope covering multiple workflows +- Long-lived, evolving over time +- Team collaboration hub +- Example: "Mobile App Rewrite" project with design, development, and deployment tools + +**Agents** are single-purpose virtual MCPs for specific tasks: +- Narrow scope with clear, focused objective +- Designed for particular operations +- Can be spawned on-demand with fresh context +- Example: "Agent Management Agent" that only creates/edits/deletes agents + +## Agents as Virtual MCPs + +Because agents are virtual MCPs, they have the same capabilities and configuration options as any virtual MCP. Each agent: + +- Exposes a unique MCP-compliant endpoint at `/:org/agents/:agent_id` +- Can aggregate tools from multiple connections (composition) +- Can define inline resources, prompts, and tools +- Can be configured and updated dynamically +- Operates within its defined scope and boundaries + +```typescript +// Example: Research agent configuration +{ + "agentId": "research-agent-001", + "name": "Codebase Research Agent", + "purpose": "Explore and analyze codebase structure", + "connections": [ + { + "connectionId": "github-conn-123", + "tools": ["LIST_FILES", "READ_FILE", "SEARCH_CODE"] + }, + { + "connectionId": "docs-conn-456", + "tools": ["SEARCH_DOCS", "GET_API_REFERENCE"] + } + ], + "prompts": [ + { + "name": "analyze-architecture", + "description": "Analyze codebase architecture patterns", + "template": "Analyze the architecture of:\n{{filepath}}\n\nFocus on:\n- Design patterns\n- Dependencies\n- Module organization" + } + ], + "resources": [ + { + "uri": "agent://research-agent-001/guidelines", + "name": "Research Guidelines", + "mimeType": "text/markdown", + "content": "# Research Guidelines\n\n- Read-only operations\n- Document findings clearly\n- Focus on structure and patterns" + } + ] +} +``` + +## Creating Agents + +Agents are created similarly to projects, with configuration determining their behavior. The key is defining a clear, single purpose for the agent. + +### Composition Mode + +Mix tools from multiple existing connections: + +```typescript +// Deployment agent using composition +{ + "agentId": "deployment-agent-001", + "name": "Production Deployment Agent", + "purpose": "Deploy applications to production", + "connections": [ + { + "connectionId": "github-conn-123", + "tools": ["CREATE_TAG", "MERGE_PR", "CREATE_RELEASE"] + }, + { + "connectionId": "slack-conn-456", + "tools": ["POST_MESSAGE"] + }, + { + "connectionId": "monitoring-conn-789", + "tools": ["CHECK_HEALTH", "GET_METRICS"] + } + ] +} +``` + +### Inline Mode + +Define agent capabilities directly within MCP Mesh: + +```typescript +// Testing agent with inline prompts +{ + "agentId": "testing-agent-001", + "name": "Test Analysis Agent", + "purpose": "Analyze test coverage and quality", + "prompts": [ + { + "name": "coverage-report", + "description": "Generate test coverage analysis", + "template": "Analyze test coverage for:\n{{files}}\n\nReport:\n- Coverage percentage\n- Untested paths\n- Recommendations" + }, + { + "name": "test-quality", + "description": "Assess test quality", + "template": "Review test quality:\n{{test_files}}\n\nCheck for:\n- Clear assertions\n- Edge cases\n- Maintainability" + } + ] +} +``` + +### Hybrid Mode + +Combine external tools with inline configuration: + +```typescript +// Development agent mixing both approaches +{ + "agentId": "dev-agent-001", + "name": "Development Assistant Agent", + "purpose": "Assist with feature development", + "connections": [ + { + "connectionId": "github-conn-123", + "tools": ["CREATE_BRANCH", "CREATE_PR", "LIST_ISSUES"] + } + ], + "prompts": [ + { + "name": "feature-pr-template", + "description": "Generate feature PR description", + "template": "Create PR for feature:\n{{feature_name}}\n\nInclude:\n- Summary\n- Testing checklist\n- Breaking changes" + } + ], + "resources": [ + { + "uri": "agent://dev-agent-001/workflow", + "name": "Development Workflow", + "mimeType": "text/markdown", + "content": "# Development Workflow\n\n1. Create feature branch\n2. Implement changes\n3. Write tests\n4. Create PR with checklist" + } + ] +} +``` + +## Agent Configuration + +Agents support the same configuration capabilities as virtual MCPs, plus agent-specific features. + +### AGENTS.md Support + +Each agent can have an `AGENTS.md` file that provides context and instructions specific to that agent's purpose. This file is loaded into the agent's context and guides its behavior. + +```markdown +# Research Agent Instructions + +## Purpose +Explore and analyze codebases for architectural patterns and structure. + +## Constraints +- Read-only operations only +- Document all findings +- Focus on high-level patterns, not implementation details + +## Workflow +1. Start with entry points (main files, index files) +2. Map module dependencies +3. Identify design patterns +4. Document architectural decisions +``` + +### Tool Selection + +Choose tools that align with the agent's purpose. Overly broad tool access dilutes the agent's focus. + +**Good**: Research agent with read-only tools +**Bad**: Research agent with write, deploy, and admin tools + +### Resource Configuration + +Provide resources that give the agent domain-specific context: + +- Guidelines specific to the agent's task +- Templates for common outputs +- Reference documentation +- Domain knowledge + +## Built-in Agents + +MCP Mesh includes several built-in agents for common mesh operations. These agents use the **Mesh MCP**—a self-referential MCP that exposes mesh management capabilities through the MCP protocol. + +### The Mesh MCP + +The Mesh MCP is a powerful concept: **mesh has an MCP for managing itself**. This MCP provides tools for: + +- Managing agents (create, edit, delete) +- Managing connections (add, remove, configure) +- Managing permissions (roles, access control) +- Managing users (invite, remove) +- Installing MCPs from the store + +Built-in agents leverage these mesh MCP tools, which are available in the organization's virtual MCP at the org-admin level. + +### Agent Management Agent + +**Purpose**: Create, edit, and delete agents + +**Tools**: Agent CRUD operations from mesh MCP + +**Use cases**: +- "Create a new research agent for analyzing this codebase" +- "Edit the deployment agent to add database migration tools" +- "Delete the testing agent that's no longer needed" + +**Scope**: Organization-level operations + +**How it works**: Uses mesh MCP tools (`CREATE_AGENT`, `UPDATE_AGENT`, `DELETE_AGENT`) to manage agents. The agent has access to the org's virtual MCP at admin level, allowing it to perform agent management operations. + +```typescript +// Example: Using agent management agent +{ + "agentId": "agent-manager-001", + "name": "Agent Management Agent", + "purpose": "Manage agent lifecycle", + "connections": [ + { + "connectionId": "mesh-mcp-conn", + "tools": ["CREATE_AGENT", "UPDATE_AGENT", "DELETE_AGENT", "LIST_AGENTS"] + } + ], + "prompts": [ + { + "name": "create-agent-from-description", + "description": "Create agent from natural language description", + "template": "Create an agent for: {{description}}\n\nDetermine:\n- Agent name and purpose\n- Required tools\n- Relevant prompts and resources" + } + ] +} +``` + +### Connection Management Agent + +**Purpose**: Manage MCP connections + +**Tools**: Connection management from mesh MCP + +**Use cases**: +- "Connect to the GitHub MCP server with these credentials" +- "Remove the unused Slack connection" +- "Update authentication settings for the database MCP" + +**Scope**: Organization-level operations + +**How it works**: Uses mesh MCP tools (`CREATE_CONNECTION`, `UPDATE_CONNECTION`, `DELETE_CONNECTION`) to manage connections in the organization. + +### Permission Management Agent + +**Purpose**: Manage permissions and access control + +**Tools**: Permission management from mesh MCP + +**Use cases**: +- "Grant developer role to this user" +- "Restrict access to production connections" +- "Update permissions for the deployment agent" + +**Scope**: Organization-level operations + +**How it works**: Uses mesh MCP tools for permission management (`GRANT_PERMISSION`, `REVOKE_PERMISSION`, `LIST_PERMISSIONS`) to control access within the organization. + +### MCP Store Agent + +**Purpose**: Install and manage MCPs from the store + +**Tools**: Store browsing and MCP installation from mesh MCP + +**Use cases**: +- "Install the GitHub MCP from the store" +- "Browse available database integration MCPs" +- "Update the Slack MCP to the latest version" + +**Scope**: Organization-level operations + +**How it works**: Uses mesh MCP tools (`BROWSE_STORE`, `INSTALL_MCP`, `UPDATE_MCP`) to interact with the MCP store and install servers. + +### User Management Agent + +**Purpose**: Invite and manage organization users + +**Tools**: User management from mesh MCP + +**Use cases**: +- "Invite a new developer to the organization" +- "Remove user access for this email" +- "Update user roles and permissions" + +**Scope**: Organization-level operations + +**How it works**: Uses mesh MCP tools (`INVITE_USER`, `REMOVE_USER`, `UPDATE_USER_ROLE`) to manage organization membership. + +### Characteristics of Built-in Agents + +Built-in agents share common characteristics: + +- **Use org's virtual MCP**: Access mesh MCP tools at org-admin level +- **Pre-configured**: Tools, prompts, and resources tailored for specific mesh operations +- **Available out-of-the-box**: No setup required, ready to use immediately +- **Customizable**: Can be modified or used as templates for custom agents +- **Org-level scope**: Operate at organization level, not project or agent scope + +Built-in agents make mesh operations accessible through the same MCP interface used for application development, creating a consistent experience. + +## Agent Types and Patterns + +Common agent patterns emerge based on purpose: + +### Research Agents + +**Focus**: Exploration and analysis + +**Tools**: Read-only operations, search, documentation access + +**Example**: Codebase architecture analysis agent + +**Characteristics**: +- No write or mutating operations +- Comprehensive read access +- Documentation and analysis prompts + +### Development Agents + +**Focus**: Building and implementing features + +**Tools**: Full read/write access, branching, committing, testing + +**Example**: Feature implementation agent + +**Characteristics**: +- Code modification tools +- Git operations +- Testing and validation tools + +### Testing Agents + +**Focus**: Verification and validation + +**Tools**: Test execution, coverage analysis, quality checks + +**Example**: Test coverage agent + +**Characteristics**: +- Testing framework tools +- Coverage reporting +- Quality metrics + +### Deployment Agents + +**Focus**: Operations and releases + +**Tools**: Deployment commands, monitoring, rollback + +**Example**: Production deployment agent + +**Characteristics**: +- Production access (carefully scoped) +- Deployment and rollback tools +- Health check and monitoring + +### Custom Agents + +**Focus**: Domain-specific tasks + +**Tools**: Tailored to specific use case + +**Example**: Customer support agent with CRM and ticket tools + +**Characteristics**: +- Highly specialized toolset +- Domain-specific prompts and resources +- Often combines multiple systems + +## Single-Purpose Design Principle + +The power of agents comes from their focused design. An agent should do one thing well. + +### Why Single-Purpose? + +**Clarity**: The agent's purpose is immediately clear +**Reliability**: Narrow scope reduces unexpected behavior +**Maintainability**: Simpler to update and debug +**Reusability**: Single-purpose agents compose better + +### Good vs. Overly Broad + +**Good**: "Agent Management Agent" (creates/edits/deletes agents) +**Too broad**: "Mesh Admin Agent" (manages agents, connections, permissions, users, billing, settings...) + +**Good**: "Production Deployment Agent" (deploys to production) +**Too broad**: "DevOps Agent" (deploys, monitors, manages infrastructure, handles incidents...) + +### Defining Clear Purpose + +When creating an agent, start with a purpose statement: + +``` +Purpose: [Verb] + [Object] + [Context] + +Examples: +- "Deploy applications to production environments" +- "Analyze test coverage for code quality" +- "Research codebase architecture patterns" +- "Manage agent lifecycle in the organization" +``` + +A clear purpose guides tool selection, resource configuration, and prompt design. + +## Agent Scope + +When working within an agent, you operate in **agent scope**. The agent's route determines this: + +``` +/:org/agents/:agent_id +``` + +In agent scope: +- Tools are limited to those configured for the agent +- Resources are agent-specific plus organization-level +- Prompts are tailored to the agent's purpose +- Operations are bounded by the agent's capabilities + +For more details on how scopes work, see the decopilot documentation on [Scopes](/en/mcp-mesh/decopilot/scopes). + +## Using Agents + +Agents can be used in several ways: + +**Spawned by decopilot**: When working in decopilot, agents can be spawned on-demand with fresh context. + +**Built-in agents**: Use pre-configured agents for common mesh operations without any setup. + +**Custom agents**: Create domain-specific agents for your team's unique workflows. + +**Direct connection**: Connect MCP clients directly to agent endpoints for focused work sessions. + +Agents provide focused capabilities with fresh context, making them ideal for specific, well-defined tasks. + +## Benefits Summary + +Agents bring several advantages: + +- **Focused capabilities**: Single-purpose design ensures clarity and reliability +- **Fresh context**: Spawned agents start with clean context for their specific task +- **Reusable patterns**: Define once, use across projects and workflows +- **Built-in operations**: Pre-configured agents for common mesh tasks +- **Composable design**: Combine multiple agents for complex workflows +- **Self-referential management**: Mesh MCP enables agents to manage mesh itself + +--- + +**Ready to create your first agent?** Start by understanding [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to grasp the foundation, then explore built-in agents to see common patterns. From e6b5221a831319206924849548d1eb76f472c50d Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 17:10:13 -0300 Subject: [PATCH 07/51] docs: document decopilot scope concept Create comprehensive documentation explaining scope as the fundamental concept in decopilot. Covers three scope types (org, project, agent), route-to-scope mapping, scope-sensitive operations, and virtual MCPs at every level. Includes Mermaid diagram, route mapping table, and practical code examples. Closes beads-main-8f1 Co-Authored-By: Claude Sonnet 4.5 --- .../content/en/mcp-mesh/decopilot/scopes.mdx | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx new file mode 100644 index 0000000000..296893e997 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx @@ -0,0 +1,151 @@ +--- +title: Scopes +description: Understanding scope-based routing and how decopilot operates across different virtual MCP contexts +icon: Target +--- + +import Callout from "../../../../components/ui/Callout.astro"; + + + This page documents the **planned architecture** for decopilot scopes. The implementation is in development. + + +## What is Scope? + +**Scope** is the current virtual MCP context in which decopilot operates. It determines what tools, resources, and prompts are available, and how decopilot behaves when you interact with it. + +Unlike traditional tools that operate in a single global context, decopilot is **scope-sensitive**—it automatically adapts based on where you are in the application. Think of scope as your current working environment that changes as you navigate routes in decocms. + +Scope affects every operation: tool availability, resource reading, prompt loading, and tool execution. This architecture ensures isolation (projects cannot access each other's tools), security (access control at the scope level), and clarity (you always know what capabilities are available). + +## Three Scope Types + +Decopilot operates in three distinct scopes, each a **virtual MCP** with its own capabilities. + +### Org Scope + +**Route**: `/:org/settings`, `/:org/connections` + +**Behavior**: Operates like an org-admin, similar to `~/.claude` in Claude Code. Provides org-wide resources, prompts, and tools accessible across all projects and agents. This is the foundation level where shared context is defined. + +### Project Scope + +**Route**: `/:org/projects/:project_id` + +**Behavior**: Projects **ARE virtual MCPs**, not containers. Each project is a self-contained MCP server with project-specific tools, resources, and connected MCPs (GitHub, Figma, etc.). Mirrors Claude Code's `.claude/` pattern—isolated work context. + +### Agent Scope + +**Route**: `/:org/agents/:agent_id` + +**Behavior**: Agents **ARE virtual MCPs** optimized for single-purpose tasks. They are bounded and focused, with agent-specific capabilities and resources. Most narrowly focused scope for repeatable, well-defined tasks. + +## How Scope is Determined + +Scope is **automatically determined by the route** you navigate to in decocms. As you move through the application, decopilot seamlessly adapts to the new context. + +```mermaid +graph LR + A[Route: /:org/settings] --> B[Org Scope] + C[Route: /:org/projects/:id] --> D[Project Scope] + E[Route: /:org/agents/:id] --> F[Agent Scope] + + B --> G[Org Virtual MCP] + D --> H[Project Virtual MCP] + F --> I[Agent Virtual MCP] + + G --> J[Org Tools/Resources/Prompts] + H --> K[Project Tools/Resources/Prompts] + I --> L[Agent Tools/Resources/Prompts] +``` + +### Route-to-Scope Mapping + +| Route Pattern | Scope Type | Virtual MCP | +|---|---|---| +| `/:org/settings` | Org | Organization virtual MCP | +| `/:org/connections` | Org | Organization virtual MCP | +| `/:org/projects/:project_id` | Project | Project-specific virtual MCP | +| `/:org/projects/:project_id/settings` | Project | Project-specific virtual MCP | +| `/:org/agents/:agent_id` | Agent | Agent-specific virtual MCP | +| `/:org/agents/:agent_id/config` | Agent | Agent-specific virtual MCP | + +## Scope-Sensitive Operations + +All decopilot operations are **scope-aware**. The current scope determines what happens when you execute commands, read resources, or invoke tools. + + + The examples below use conceptual API syntax to illustrate scope behavior. + + +### Reading Resources + +```typescript +// Resources are read from the current scope's virtual MCP +decopilot.readResource("org://guidelines") // Org scope +decopilot.readResource("project://mobile-app/arch") // Project scope +decopilot.readResource("agent://reviewer/checklist") // Agent scope +``` + +### Tool Availability + +```typescript +// Tools depend on the current scope +decopilot.listTools() +// Org: ["ORG_CONNECTION_CREATE", "ORG_RESOURCE_CREATE", ...] +// Project: ["CREATE_PR", "GET_DESIGN", "RUN_TESTS", ...] +// Agent: ["REVIEW_CODE", "ANALYZE_SECURITY", ...] +``` + +## Virtual MCPs at Every Level + +**Everything in decocms is a virtual MCP**. Orgs, projects, and agents are all virtual MCPs with tools, resources, prompts, and configuration. The scope hierarchy creates an inheritance model where projects and agents access org-level capabilities while maintaining their own scope-specific additions. + +## Practical Examples + +### Project Scope Example + +Working on a mobile app project (`/:org/projects/mobile-app`): + +```typescript +// Tools include GitHub, Figma, project-specific capabilities +decopilot.listTools() +// Returns: CREATE_PR, GET_DESIGN, RUN_MOBILE_TESTS + +// Read project context +decopilot.readResource("project://mobile-app/guidelines") + +// Create PR using project's GitHub connection +decopilot.invokeTool("CREATE_PR", { + title: "Add login screen" +}) +``` + +### Agent Scope Example + +Using a code review agent (`/:org/agents/code-reviewer`): + +```typescript +// Bounded tools for specific task +decopilot.listTools() +// Returns: SECURITY_REVIEW, PERFORMANCE_REVIEW, CODE_ANALYSIS + +// Execute security analysis +decopilot.invokeTool("SECURITY_REVIEW", { + code: "const query = `SELECT * FROM users WHERE id = ${userId}`" +}) +``` + +## Key Takeaways + +- **Scope is fundamental**: Every operation happens within a scope +- **Routes determine scope**: Navigation automatically changes context +- **Three scope types**: Org, Project, Agent +- **Everything is a virtual MCP**: Each level has tools, resources, and prompts +- **Automatic adaptation**: Decopilot adjusts behavior as you navigate + +Understanding scope is essential to using decopilot effectively—it ensures clarity, security, and organization. + +--- + +**Ready to dive deeper?** Learn about [Virtual MCPs](/en/mcp-mesh/virtual-mcps) or explore [Projects](/en/mcp-mesh/projects). From 0f3253d780b2617e2a4cf0a20828ec5d4bedd0d1 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 17:18:48 -0300 Subject: [PATCH 08/51] docs: document decopilot overview with Claude Code comparison Create comprehensive decopilot overview documentation that establishes the fundamental architecture: decopilot only works with virtual MCPs (editable environments). Includes comparison table for Claude Code users, explains scope-sensitive operations (org/project/agent), task-based agent spawning, and links to foundational concepts. Key sections: opening hook, why virtual MCPs, Claude Code comparison, key capabilities, how it works, examples, and next steps. Closes beads-main-pas Co-Authored-By: Claude Sonnet 4.5 --- .../en/mcp-mesh/decopilot/overview.mdx | 153 ++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx new file mode 100644 index 0000000000..899f388cd8 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx @@ -0,0 +1,153 @@ +--- +title: Decopilot Overview +description: MCP-native AI agent for web-based development that operates on virtual MCPs +icon: Sparkles +--- + +import Callout from "../../../../components/ui/Callout.astro"; + + + This page documents the **planned architecture** for decopilot. The implementation is in development. + + +## What is Decopilot? + +**Decopilot** is an MCP-native AI agent designed for web-based development within MCP Mesh. Unlike traditional AI coding assistants that operate on local filesystems, decopilot is built from the ground up to work with the Model Context Protocol—operating through MCP servers, virtual MCPs, and distributed capabilities. + +The defining characteristic of decopilot is that **it only works with virtual MCPs**. This is a fundamental architectural constraint: decopilot needs to operate and edit the MCP configurations dynamically, which is only possible with virtual MCPs. External MCP servers (like traditional GitHub or Slack servers) are read-only connections that decopilot cannot modify. This is why projects, agents, and organization scopes are all virtual MCPs—they provide the editable, configurable foundation that decopilot requires. + +Decopilot is part of the MCP Mesh infrastructure, operating within the scope-based routing system to provide context-aware assistance across organization, project, and agent levels. + +## Why Virtual MCPs? + +Decopilot's foundation is built on [Virtual MCPs](/en/mcp-mesh/virtual-mcps), and understanding why is crucial: + +**Virtual MCPs are editable and configurable**. When decopilot operates in a project, it can dynamically add tools, create resources, update prompts, and modify the virtual MCP configuration. This enables decopilot to: + +- Add new tools to the current context on the fly +- Create documentation resources as it works +- Update project prompts based on workflow patterns +- Configure agent capabilities dynamically + +**Regular MCP servers are read-only**. External MCP servers like GitHub or Slack provide fixed capabilities through the MCP protocol. Decopilot can use these tools, but it cannot modify the server configuration. These external connections are composed into virtual MCPs to make them part of the editable context. + +**Projects, agents, and org scopes are all virtual MCPs**. This ensures decopilot always has an editable foundation. When you work in a project (`/:org/projects/:id`), that project IS a virtual MCP that decopilot can operate on and modify. The same is true for agents and organization scope. + +This architecture makes decopilot fundamentally different from traditional AI assistants—it doesn't just use tools, it can reshape the environment it operates in. + + + If you're familiar with Claude Code, here's how decopilot concepts map to what you know: + +| Claude Code | Decopilot | +|-------------|-----------| +| Skills | Virtual MCPs (agents) | +| `project/.claude/` | Project scope (`/:org/projects/:id`) | +| `~/.claude/` | Org scope (org routes) | +| Subagents | Task-based agent spawning | +| CLAUDE.md | CLAUDE.md + AGENTS.md | +| Skill references/assets | MCP resources | +| `/command` invocation | MCP commands | + +The key difference: decopilot operates through the MCP protocol on virtual MCPs, making it web-native and composable across your infrastructure. + + +## Key Capabilities + +**Virtual MCP Foundation**: Decopilot operates exclusively on virtual MCPs, enabling it to edit and configure the environment as it works. This is not just a feature—it's the architectural foundation that makes decopilot's dynamic behavior possible. + +**Scope-Sensitive Operations**: Decopilot automatically adapts based on where you are in the application. Operating in org scope (`/:org/settings`) gives you organization-wide capabilities. Working in project scope (`/:org/projects/:id`) provides project-specific tools and context. Agent scope (`/:org/agents/:id`) bounds operations to the agent's focused purpose. + +**Task-Based Agent Spawning**: Decopilot can spawn agents on specific tasks with fresh context. Agents run until they respond, then the main decopilot loop continues. This enables parallel work and focused execution without context pollution. + +**Agent Selection**: When spawning agents, decopilot can pick any agent configured in your organization to accomplish the task. This allows delegation to specialized agents optimized for particular operations. + +**Built-in Tools**: Comprehensive toolset for MCP management, including tools for reading and editing resources, prompts, and tools within the current virtual MCP scope. + +## How It Works + +Decopilot operates in **three distinct scopes**, each corresponding to a different virtual MCP: + +**Org Scope** (`/:org/settings`, `/:org/connections`): Operates like an org-admin with organization-wide resources, prompts, and tools. Comparable to `~/.claude/` in Claude Code—this is the foundation level where shared context lives. + +**Project Scope** (`/:org/projects/:id`): Projects ARE virtual MCPs, not just containers. Each project has project-specific tools, resources, and connected MCPs. Comparable to `.claude/` in Claude Code—isolated work context for the project. + +**Agent Scope** (`/:org/agents/:id`): Agents ARE virtual MCPs optimized for single-purpose tasks. Most narrowly focused scope for repeatable, well-defined operations. + +The route determines the scope automatically. As you navigate through the application, decopilot seamlessly adapts to the new context. Each scope is a virtual MCP that decopilot can operate on and edit, providing the foundation for its dynamic capabilities. + +### Task-Based Agent Spawning + +Decopilot can spawn agents to handle specific tasks: + +```typescript +// Conceptual example: spawning an agent +decopilot.spawnAgent({ + agentId: "research-agent-001", + task: "Analyze the authentication architecture in this codebase", + context: { projectId: "mobile-app-rewrite" } +}) +// Agent runs until it responds, then main loop continues +``` + +This enables parallel execution and focused work without polluting the main decopilot context. + +### Editing Virtual MCPs + +Because decopilot operates on virtual MCPs, it can modify them dynamically: + +```typescript +// Conceptual example: editing the current virtual MCP +decopilot.addTool({ + name: "DEPLOY_STAGING", + description: "Deploy to staging environment", + // ... tool configuration +}) + +decopilot.createResource({ + uri: "project://mobile-app/deployment-checklist", + name: "Deployment Checklist", + content: "# Deployment Checklist\n\n- [ ] Run tests\n- [ ] Update changelog\n..." +}) +``` + +This is only possible because projects, agents, and org scopes are all virtual MCPs—editable and configurable in real-time. + +## Quick Examples + +**Working in Project Scope**: + +When editing a project's virtual MCP, decopilot can: +- Add GitHub tools for creating pull requests +- Create project-specific resources like architecture documentation +- Update prompts for code review templates +- Configure connections to external MCP servers + +**Spawning an Agent on a Task**: + +When analyzing a large codebase, spawn a research agent: +- Agent gets fresh context for the specific task +- Agent has read-only tools to explore code +- Agent reports findings back to main decopilot loop +- Main context remains clean and focused + +For detailed information on how scopes work, see [Scopes](/en/mcp-mesh/decopilot/scopes). + +## Next Steps + +**Virtual MCPs** (foundational): Understand why decopilot uses virtual MCPs and how they enable dynamic configuration. Start here: [Virtual MCPs](/en/mcp-mesh/virtual-mcps) + +**Scopes**: Learn how org/project/agent scopes work and how routing determines context. See: [Scopes](/en/mcp-mesh/decopilot/scopes) + +**Projects**: Understand projects as virtual MCPs and how they organize work. Read: [Projects](/en/mcp-mesh/projects) + +**Agents**: Explore single-purpose virtual MCPs and how they provide focused capabilities. Check: [Agents](/en/mcp-mesh/agents) + +**Architecture**: Deep-dive into decopilot's technical architecture and implementation (coming soon) + +**Context Management**: Learn how decopilot maintains context across scopes and agent spawning (coming soon) + +**Built-in Tools**: Explore the comprehensive toolset for MCP management (coming soon) + +--- + +Decopilot represents a new approach to AI-assisted development—web-native, MCP-first, and built on the foundation of virtual MCPs. By operating exclusively on virtual MCPs, it can dynamically reshape the environment as it works, providing capabilities that traditional filesystem-based assistants cannot match. From c9d28bd31f499084f1d3ec27df30a3af3f41dcde Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 17:31:27 -0300 Subject: [PATCH 09/51] docs: document decopilot core architecture Create comprehensive architecture documentation covering core architectural concepts including Virtual MCPs Only constraint, scope-based architecture, task-based agent spawning, and tool scope sensitivity. Key sections: - Architectural constraint explaining why decopilot requires virtual MCPs - Virtual MCP foundation (org/projects/agents) - Scope-based architecture with route determination - Task/thread system with lifecycle and UI integration - External vs virtual MCP comparison - Dynamic virtual MCP features and extensibility - 4 Mermaid diagrams illustrating architecture - 5 TypeScript code examples Closes beads-main-4lk Co-Authored-By: Claude Sonnet 4.5 --- .../en/mcp-mesh/decopilot/architecture.mdx | 1501 +++++++++++++++++ 1 file changed, 1501 insertions(+) create mode 100644 apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx new file mode 100644 index 0000000000..65bd33c345 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx @@ -0,0 +1,1501 @@ +--- +title: Architecture +description: Deep-dive into decopilot's core architectural concepts and implementation design +icon: Building2 +--- + +import Callout from "../../../../components/ui/Callout.astro"; + + + This page documents the **planned architecture** for decopilot. The implementation is in development. + + +## Overview + +Decopilot is an MCP-native AI agent that operates through a scope-sensitive architecture where **everything is a virtual MCP**. Unlike traditional AI coding assistants that work with local filesystems, decopilot is built from the ground up to operate on virtual MCPs—editable, configurable MCP servers that can be dynamically modified at runtime. + +The architecture is fundamentally defined by three core principles: + +**Scope-based operation**: Decopilot's behavior adapts based on the current route—operating in org scope (`/:org/settings`), project scope (`/:org/projects/:id`), or agent scope (`/:org/agents/:id`). Each scope corresponds to a different virtual MCP with distinct capabilities. + +**Virtual MCP foundation**: Organizations, projects, and agents are all virtual MCPs. This isn't just an implementation detail—it's the architectural constraint that enables decopilot's dynamic capabilities. + +**Task-based execution model**: Decopilot spawns agents on specific tasks with isolated contexts, enabling parallel work and focused execution without context pollution. + +This architecture enables decopilot to dynamically reshape the environment as it works, adding tools, creating resources, and configuring capabilities on the fly—operations that are only possible with editable virtual MCPs. + +## Architectural Constraint: Virtual MCPs Only + +Decopilot has a fundamental architectural constraint: **it only works with virtual MCPs**. This constraint exists for a critical reason—decopilot needs to operate on and edit the MCP configurations dynamically. + +### Why This Constraint Exists + +Traditional MCP servers (external servers like GitHub, Slack, or database MCPs) are **read-only connections** from decopilot's perspective. These servers expose a fixed set of tools through the MCP protocol, but their configuration cannot be modified by clients. Decopilot can invoke their tools, but it cannot add new tools, create resources, or update prompts on these servers. + +Virtual MCPs, by contrast, are **editable and configurable**. When decopilot operates in a project scope, that project IS a virtual MCP that decopilot can modify. This means decopilot can: + +- Add new tools to the current context +- Create documentation resources as it works +- Update prompts based on workflow patterns +- Configure connections dynamically +- Modify the virtual MCP structure itself + +Without this editability, decopilot would be limited to using predefined tools—essentially a chatbot with access to APIs. The virtual MCP constraint enables decopilot to be an active participant in shaping the environment, not just consuming it. + +### What This Means + +The constraint means that **every context decopilot operates in must be a virtual MCP**: + +- **Organization scope** (`/:org/settings`): The organization itself is a virtual MCP +- **Project scope** (`/:org/projects/:id`): Each project is a virtual MCP +- **Agent scope** (`/:org/agents/:id`): Each agent is a virtual MCP + +External MCP servers (GitHub, Slack, databases) are connected TO these virtual MCPs, not operated on BY decopilot. Decopilot uses the tools from external MCPs, but it operates on the virtual MCP that aggregates them. + +```typescript +// External MCP: read-only from decopilot's perspective +const githubMCP = { + tools: ["CREATE_PR", "LIST_ISSUES"], // Fixed toolset + // Decopilot can invoke these tools but cannot modify this server +} + +// Virtual MCP: editable by decopilot +const projectVirtualMCP = { + connections: [githubMCP], // Compose external MCPs + tools: ["DEPLOY_STAGING"], // Inline tools decopilot can add/remove + resources: [], // Resources decopilot can create + prompts: [], // Prompts decopilot can update + // Decopilot can modify this structure dynamically +} +``` + +### Benefits + +This architectural constraint provides: + +**Dynamic tool management**: Decopilot can add tools to the current scope as needed, creating workflows on the fly rather than requiring pre-configuration. + +**Resource creation**: As decopilot works, it can create documentation resources, guidelines, and context that persist in the virtual MCP for future use. + +**Prompt evolution**: Decopilot can update prompt templates based on successful patterns, continuously improving the virtual MCP. + +**Composable capabilities**: External MCPs remain isolated and secure, while virtual MCPs provide the editable layer that composes them. + +**Clear separation of concerns**: External MCPs focus on providing stable, secure tools. Virtual MCPs focus on dynamic aggregation and configuration. + +The constraint turns a potential limitation into a powerful architectural pattern—by requiring virtual MCPs, decopilot gains the editability foundation that makes its dynamic behavior possible. + +## The Virtual MCP Foundation + +At the core of decopilot's architecture is a simple but powerful concept: **everything is a virtual MCP**. Organizations, projects, and agents are all virtual MCP servers with tools, resources, prompts, and configuration. + +### Organizations as Virtual MCPs + +When you operate in org scope (`/:org/settings` or `/:org/connections`), you're working within the organization's virtual MCP. This virtual MCP contains: + +- **Organization-wide tools**: Capabilities available across all projects and agents +- **Shared resources**: Guidelines, policies, documentation that apply org-wide +- **Global prompts**: Templates and workflows for the entire organization +- **Connection registry**: All external MCP connections managed at the org level + +The organization virtual MCP serves as the foundation layer, comparable to `~/.claude/` in Claude Code—the global context that underlies all work. + +```typescript +// Organization virtual MCP structure +{ + "organizationId": "acme-corp", + "virtualMCPId": "org-acme-corp", + "tools": [ + "ORG_CONNECTION_CREATE", + "ORG_RESOURCE_CREATE", + "ORG_PROMPT_UPDATE" + ], + "resources": [ + { + "uri": "org://acme-corp/security-policy", + "name": "Security Policy", + "mimeType": "text/markdown" + }, + { + "uri": "org://acme-corp/coding-standards", + "name": "Coding Standards", + "mimeType": "text/markdown" + } + ], + "connections": ["github-conn-123", "slack-conn-456"] +} +``` + +### Projects as Virtual MCPs + +Projects ARE virtual MCPs, not containers for other resources. Each project (`/:org/projects/:id`) is a self-contained virtual MCP server with its own capabilities: + +- **Project-specific tools**: Inline tools or composed from connected MCPs +- **Project resources**: Documentation, architecture diagrams, guidelines +- **Project prompts**: Custom templates for the project's workflows +- **Project connections**: External MCPs wired to this project's scope + +Projects are the primary organizational unit for work, comparable to `.claude/` in Claude Code—the project-local context that isolates work. + +```typescript +// Project virtual MCP structure +{ + "projectId": "mobile-app-rewrite", + "virtualMCPId": "project-mobile-app-rewrite", + "organizationId": "acme-corp", + "connections": [ + { + "connectionId": "github-conn-123", + "tools": ["CREATE_PR", "LIST_ISSUES"] + }, + { + "connectionId": "figma-conn-456", + "tools": ["GET_DESIGN", "EXPORT_ASSETS"] + } + ], + "tools": [ + { + "name": "DEPLOY_STAGING", + "description": "Deploy mobile app to staging environment", + "inputSchema": {/* ... */} + } + ], + "resources": [ + { + "uri": "project://mobile-app-rewrite/architecture", + "name": "Mobile Architecture", + "mimeType": "text/markdown" + } + ], + "prompts": [ + { + "name": "mobile-pr-template", + "description": "PR template for mobile features", + "template": "## Mobile Feature PR\n\n{{description}}" + } + ] +} +``` + +### Agents as Virtual MCPs + +Agents ARE virtual MCPs optimized for single-purpose tasks. Each agent (`/:org/agents/:id`) is a focused virtual MCP with: + +- **Bounded tools**: Limited toolset specific to the agent's purpose +- **Agent-specific resources**: Documentation and context for the agent's task +- **Task prompts**: Specialized templates for the agent's workflows +- **Single-purpose focus**: Narrow scope ensures predictable, repeatable behavior + +Agents are the most focused scope level, providing specialized capabilities for well-defined tasks. + +```typescript +// Agent virtual MCP structure +{ + "agentId": "security-reviewer-001", + "virtualMCPId": "agent-security-reviewer-001", + "organizationId": "acme-corp", + "purpose": "Review code for security vulnerabilities", + "tools": [ + { + "name": "SECURITY_SCAN", + "description": "Scan code for security issues" + }, + { + "name": "CVE_LOOKUP", + "description": "Look up known vulnerabilities" + } + ], + "resources": [ + { + "uri": "agent://security-reviewer-001/checklist", + "name": "Security Review Checklist", + "mimeType": "text/markdown" + } + ], + "prompts": [ + { + "name": "security-analysis", + "description": "Analyze code for security issues", + "template": "Review this code for:\n- SQL injection\n- XSS\n- Auth bypasses\n\nCode:\n{{code}}" + } + ] +} +``` + +### Virtual MCP Hierarchy + +Virtual MCPs form a hierarchy where capabilities flow from org to project to agent: + +- **Org virtual MCP**: Foundation layer, provides org-wide capabilities +- **Project virtual MCP**: Inherits org capabilities, adds project-specific tools +- **Agent virtual MCP**: Most focused, bounded toolset for specific task + +This hierarchy ensures consistency while enabling specialization at each level. + +## Scope-Based Architecture + +Decopilot's behavior is determined by **scope**—the current virtual MCP context in which it operates. Scope is automatically determined by the route, and as you navigate through the application, decopilot seamlessly adapts to the new context. + +### Route-Based Scope Determination + +The route determines which virtual MCP decopilot operates on: + +```typescript +// Route-to-scope mapping +const SCOPE_ROUTES = { + // Organization scope + "/:org/settings": { + scopeType: "org", + virtualMCPId: "org-{orgId}" + }, + "/:org/connections": { + scopeType: "org", + virtualMCPId: "org-{orgId}" + }, + + // Project scope + "/:org/projects/:projectId": { + scopeType: "project", + virtualMCPId: "project-{projectId}" + }, + "/:org/projects/:projectId/settings": { + scopeType: "project", + virtualMCPId: "project-{projectId}" + }, + + // Agent scope + "/:org/agents/:agentId": { + scopeType: "agent", + virtualMCPId: "agent-{agentId}" + }, + "/:org/agents/:agentId/config": { + scopeType: "agent", + virtualMCPId: "agent-{agentId}" + } +} + +// Route parsing determines scope +function getScopeFromRoute(route: string) { + const match = matchRoute(route, SCOPE_ROUTES) + if (!match) throw new Error("Invalid route") + + return { + scopeType: match.scopeType, + virtualMCPId: match.virtualMCPId, + params: match.params + } +} +``` + +### Scope Characteristics + +Each scope type has distinct characteristics: + +**Org Scope**: +- **Breadth**: Organization-wide capabilities +- **Tools**: Connection management, org resource creation, global configuration +- **Resources**: Security policies, coding standards, org guidelines +- **Behavior**: Operates like an org-admin, managing shared infrastructure + +**Project Scope**: +- **Breadth**: Project-specific capabilities +- **Tools**: Project tools + composed from connected MCPs (GitHub, Figma, etc.) +- **Resources**: Project documentation, architecture diagrams, guidelines +- **Behavior**: Focused on project work, isolated from other projects + +**Agent Scope**: +- **Breadth**: Task-specific capabilities +- **Tools**: Bounded toolset for the agent's single purpose +- **Resources**: Agent-specific checklists and context +- **Behavior**: Highly focused, predictable execution for well-defined tasks + +### Scope Diagram + +```mermaid +graph TD + A[Route: /:org/settings] --> B[Org Scope] + C[Route: /:org/projects/:id] --> D[Project Scope] + E[Route: /:org/agents/:id] --> F[Agent Scope] + + B --> G[Org Virtual MCP] + D --> H[Project Virtual MCP] + F --> I[Agent Virtual MCP] + + G --> J[Org-wide Tools
Shared Resources
Global Prompts] + H --> K[Project Tools
Project Resources
Connected MCPs] + I --> L[Bounded Tools
Agent Resources
Task Prompts] + + style G fill:#e1f5ff + style H fill:#fff4e1 + style I fill:#ffe1e1 +``` + +## How Decopilot Operates + +Decopilot's operation changes based on the current scope. Each scope provides a different virtual MCP for decopilot to operate on, and the available tools, resources, and behavior adapt accordingly. + +### Operating in Org Scope + +In org scope (`/:org/settings`, `/:org/connections`), decopilot has access to organization-wide capabilities: + +```typescript +// Org scope operations +const orgScope = { + virtualMCPId: "org-acme-corp", + + availableTools: [ + "ORG_CONNECTION_CREATE", // Add external MCP connections + "ORG_RESOURCE_CREATE", // Create org-wide resources + "ORG_PROMPT_UPDATE", // Update global prompts + "ORG_PROJECT_CREATE" // Create new projects + ], + + availableResources: [ + "org://acme-corp/security-policy", + "org://acme-corp/coding-standards", + "org://acme-corp/deployment-guide" + ] +} + +// Example: Creating an org-wide resource +decopilot.invokeTool("ORG_RESOURCE_CREATE", { + uri: "org://acme-corp/api-guidelines", + name: "API Design Guidelines", + content: "# API Guidelines\n\n- RESTful design\n- Versioning strategy\n..." +}) +``` + +### Operating in Project Scope + +In project scope (`/:org/projects/:projectId`), decopilot operates on the project's virtual MCP: + +```typescript +// Project scope operations +const projectScope = { + virtualMCPId: "project-mobile-app-rewrite", + + availableTools: [ + // From connected GitHub MCP + "CREATE_PR", + "LIST_ISSUES", + "CREATE_BRANCH", + + // From connected Figma MCP + "GET_DESIGN", + "EXPORT_ASSETS", + + // Inline project tools + "DEPLOY_STAGING", + "RUN_MOBILE_TESTS" + ], + + availableResources: [ + "project://mobile-app-rewrite/architecture", + "project://mobile-app-rewrite/testing-guide", + // Also inherits org resources + "org://acme-corp/security-policy" + ] +} + +// Example: Creating a PR using project's GitHub connection +decopilot.invokeTool("CREATE_PR", { + title: "Add biometric authentication", + body: "Implements face ID and fingerprint authentication for iOS and Android", + base: "main", + head: "feature/biometric-auth" +}) +``` + +### Operating in Agent Scope + +In agent scope (`/:org/agents/:agentId`), decopilot operates on the agent's bounded virtual MCP: + +```typescript +// Agent scope operations +const agentScope = { + virtualMCPId: "agent-security-reviewer-001", + + availableTools: [ + "SECURITY_SCAN", // Bounded to agent's purpose + "CVE_LOOKUP", + "GENERATE_SECURITY_REPORT" + ], + + availableResources: [ + "agent://security-reviewer-001/checklist", + "agent://security-reviewer-001/patterns", + // Also inherits org and project resources if spawned in project context + "org://acme-corp/security-policy" + ] +} + +// Example: Running security scan with agent's tools +decopilot.invokeTool("SECURITY_SCAN", { + code: "SELECT * FROM users WHERE id = " + userId, + language: "sql" +}) +``` + +### Scope Inheritance + +Scopes inherit capabilities from their parent levels: + +- **Agent scope** inherits from project scope (if spawned in project) and org scope +- **Project scope** inherits from org scope +- **Org scope** is the foundation level + +This inheritance ensures consistency while enabling specialization. + +## External MCP Servers vs Virtual MCPs + +Understanding the distinction between external MCP servers and virtual MCPs is crucial to decopilot's architecture. + +### External MCP Servers + +External MCP servers are traditional MCP servers that expose tools through the MCP protocol: + +**Characteristics**: +- Fixed toolset defined by server implementation +- Cannot be modified by clients +- Provide stable, secure access to external systems +- Examples: GitHub MCP, Slack MCP, database MCPs + +**From decopilot's perspective**: +- **Read-only**: Can invoke tools but cannot modify the server +- **Consumed, not operated on**: Used for their capabilities, not edited +- **Connected TO virtual MCPs**: Aggregated into virtual MCPs for use + +```typescript +// External MCP server (GitHub) +const githubMCP = { + serverUrl: "https://github-mcp.example.com", + tools: [ + "CREATE_PR", + "LIST_ISSUES", + "CREATE_BRANCH", + "MERGE_PR" + ], + // This toolset is fixed and cannot be modified by decopilot +} +``` + +### Virtual MCPs + +Virtual MCPs are editable, configurable MCP servers managed by MCP Mesh: + +**Characteristics**: +- Dynamic toolset that can be modified at runtime +- Can aggregate tools from multiple external MCPs +- Can define inline tools, resources, and prompts +- Fully MCP-compliant endpoints + +**From decopilot's perspective**: +- **Editable**: Can add tools, create resources, update prompts +- **Operated on**: Decopilot modifies the virtual MCP as it works +- **Compose external MCPs**: Aggregate capabilities from external servers + +```typescript +// Virtual MCP (project) +const projectVirtualMCP = { + virtualMCPId: "project-mobile-app-rewrite", + + // Composed external MCPs + connections: [ + { + connectionId: "github-conn-123", + tools: ["CREATE_PR", "LIST_ISSUES"] // Selected from external MCP + }, + { + connectionId: "figma-conn-456", + tools: ["GET_DESIGN"] // Selected from external MCP + } + ], + + // Inline tools (editable by decopilot) + tools: [ + { + name: "DEPLOY_STAGING", + description: "Deploy to staging environment", + handler: async (input) => {/* ... */} + } + ], + + // Resources (created by decopilot) + resources: [ + { + uri: "project://mobile-app-rewrite/architecture", + name: "Architecture Documentation", + content: "# Architecture\n\n..." + } + ] +} +``` + +### Interaction Pattern + +External MCPs and virtual MCPs interact through composition: + +```typescript +// External MCP connection to virtual MCP +const externalToVirtual = { + // 1. Connect external MCP to MCP Mesh + externalMCP: { + id: "github-conn-123", + serverUrl: "https://github-mcp.example.com", + tools: ["CREATE_PR", "LIST_ISSUES", "CREATE_BRANCH", "MERGE_PR"] + }, + + // 2. Compose into virtual MCP (select tools) + virtualMCP: { + id: "project-mobile-app-rewrite", + connections: [ + { + connectionId: "github-conn-123", + tools: ["CREATE_PR", "LIST_ISSUES"] // Subset of external MCP tools + } + ] + }, + + // 3. Decopilot operates on virtual MCP + // - Can invoke CREATE_PR (from external MCP) + // - Can add new inline tools to virtual MCP + // - Cannot modify github-conn-123 (external MCP) +} +``` + +### Why This Separation Matters + +**Security**: External MCPs remain isolated and secure. Decopilot cannot modify their configuration or access unauthorized tools. + +**Flexibility**: Virtual MCPs can be edited dynamically, enabling decopilot to reshape the environment without touching external infrastructure. + +**Composition**: Multiple external MCPs can be aggregated into a single virtual MCP, providing unified access. + +**Clear boundaries**: External MCPs are stable, production systems. Virtual MCPs are dynamic, configurable contexts. + +### Diagram: External vs Virtual MCPs + +```mermaid +graph LR + A[External MCP
GitHub Server] -->|Connected to| B[Virtual MCP
Project] + C[External MCP
Figma Server] -->|Connected to| B + D[External MCP
Database] -->|Connected to| B + + B -->|Editable by| E[Decopilot] + + A -.->|Read-only| E + C -.->|Read-only| E + D -.->|Read-only| E + + E -->|Can modify| B + E -->|Can invoke tools from| A + E -->|Can invoke tools from| C + E -->|Can invoke tools from| D + + style A fill:#e1e1e1 + style C fill:#e1e1e1 + style D fill:#e1e1e1 + style B fill:#e1f5ff + style E fill:#ffe1e1 +``` + +## Task-Based Agent Spawning + +Decopilot uses a task-based execution model where agents are spawned on specific tasks with isolated contexts. This enables parallel work, focused execution, and clear separation of concerns. + +### Task System Overview + +The task system (also called the thread system—terminology is migrating from "tasks" to "threads") manages asynchronous agent execution: + +**Task types**: +- **Top-level tasks**: Initiated by users, represent primary work threads +- **Child tasks**: Spawned by agents or decopilot, represent sub-tasks + +**Task states**: +- **Active**: Task is currently being processed +- **Needs Input**: Task requires user input to continue +- **Successful**: Task completed successfully +- **Failed**: Task encountered an error + +### Spawning Agents on Tasks + +When decopilot spawns an agent, it creates a new task with isolated context: + +```typescript +// Task-based agent spawning +const spawnAgentTask = { + // Spawn agent on specific task + taskId: "task-001", + taskType: "child", // Spawned by parent (user or decopilot) + + agentId: "security-reviewer-001", + instruction: "Review authentication implementation for security vulnerabilities", + + context: { + // Isolated context for this task + projectId: "mobile-app-rewrite", + files: ["src/auth/login.ts", "src/auth/session.ts"], + scope: "project" // Agent runs in project scope + }, + + // Task runs until agent responds + status: "active" +} + +// Agent executes in isolated context +// Returns result when complete +const result = await agent.execute(spawnAgentTask) + +// Main decopilot loop continues +decopilot.continue() +``` + +### Task Isolation + +Each task has isolated context: + +```typescript +// Task context isolation +const taskContext = { + taskId: "task-001", + + // Isolated conversation history + messages: [ + { role: "user", content: "Review this authentication code" }, + { role: "agent", content: "Analyzing authentication implementation..." } + ], + + // Isolated tool invocations + toolInvocations: [ + { tool: "SECURITY_SCAN", input: {/* ... */}, output: {/* ... */} } + ], + + // Task-specific state + state: "active", + + // Parent task reference (if child task) + parentTaskId: "task-root" +} +``` + +### Tool Availability Per Task Type + +Different task types have different tool availability: + +**Top-level tasks** (user-initiated): +- Full tool access +- Can use `user_ask_question` to prompt user for input +- Can spawn child tasks + +**Child tasks** (agent-spawned): +- Bounded tool access +- **Cannot use `user_ask_question`** (no user interaction) +- Can spawn grandchild tasks (nested execution) + +```typescript +// Tool availability per task type +const taskTypeTools = { + topLevel: { + availableTools: [ + "CREATE_PR", + "SECURITY_SCAN", + "user_ask_question", // User interaction allowed + "spawn_agent" + ] + }, + + child: { + availableTools: [ + "CREATE_PR", + "SECURITY_SCAN", + // "user_ask_question" DISABLED - no user interaction + "spawn_agent" // Can spawn grandchild tasks + ] + } +} +``` + +### Completion Detection + +A cheap AI model detects task completion: + +```typescript +// Completion detection with cheap model +const detectCompletion = async (task: Task) => { + const prompt = ` +Has this task completed its objective? + +Task: ${task.instruction} + +Conversation: +${task.messages.map(m => `${m.role}: ${m.content}`).join("\n")} + +Tool invocations: +${task.toolInvocations.map(t => `${t.tool}: ${t.output}`).join("\n")} + +Answer: YES or NO +` + + const response = await cheapModel.complete(prompt) + + if (response.includes("YES")) { + task.status = "successful" + } +} +``` + +### UI Integration + +Tasks map to the UI as threads: + +- **Tasks menu**: Lists all tasks (threads), with status indicators +- **Task detail view**: Shows conversation history for a specific task (thread) +- **Active task indicator**: Shows which task is currently being processed + +```typescript +// UI representation of tasks +const tasksUI = { + taskList: [ + { + taskId: "task-001", + title: "Review authentication security", + status: "successful", + type: "child", + agentId: "security-reviewer-001" + }, + { + taskId: "task-002", + title: "Implement biometric auth", + status: "active", + type: "topLevel", + agentId: null // User task, no agent + }, + { + taskId: "task-003", + title: "Deploy to staging", + status: "needs_input", + type: "topLevel", + agentId: null + } + ], + + // Task detail = chat interface + taskDetail: { + taskId: "task-001", + messages: [/* conversation history */], + toolInvocations: [/* tools executed */] + } +} +``` + +### Async Execution Model + +Task-based spawning enables asynchronous execution: + +1. **Decopilot spawns agent on task**: Creates child task with isolated context +2. **Agent executes until complete**: Runs in background, no blocking +3. **Main decopilot loop continues**: Can work on other tasks in parallel +4. **Task completion**: Agent returns result, main loop integrates findings + +This model enables parallel work and ensures the main decopilot context remains clean. + +## Agent Selection + +When spawning agents, decopilot can select from any agent configured in your organization. Agents are single-purpose virtual MCPs optimized for specific tasks. + +### Agent Registry + +Organizations maintain a registry of available agents: + +```typescript +// Organization agent registry +const agentRegistry = { + organizationId: "acme-corp", + + agents: [ + { + agentId: "security-reviewer-001", + name: "Security Reviewer", + purpose: "Review code for security vulnerabilities", + virtualMCPId: "agent-security-reviewer-001", + tools: ["SECURITY_SCAN", "CVE_LOOKUP"], + capabilities: ["security-review", "vulnerability-analysis"] + }, + { + agentId: "performance-analyzer-002", + name: "Performance Analyzer", + purpose: "Analyze code for performance issues", + virtualMCPId: "agent-performance-analyzer-002", + tools: ["PROFILE_CODE", "DETECT_N_PLUS_ONE"], + capabilities: ["performance-analysis", "profiling"] + }, + { + agentId: "documentation-writer-003", + name: "Documentation Writer", + purpose: "Generate and update documentation", + virtualMCPId: "agent-documentation-writer-003", + tools: ["GENERATE_DOCS", "UPDATE_README"], + capabilities: ["documentation", "technical-writing"] + } + ] +} +``` + +### Agent Selection Criteria + +Decopilot selects agents based on task requirements: + +```typescript +// Agent selection based on task +const selectAgent = (task: { + instruction: string + requiredCapabilities: string[] + context: object +}) => { + // Filter agents by required capabilities + const eligibleAgents = agentRegistry.agents.filter(agent => + task.requiredCapabilities.every(cap => + agent.capabilities.includes(cap) + ) + ) + + // Score agents by relevance + const scoredAgents = eligibleAgents.map(agent => ({ + agent, + score: calculateRelevance(agent, task) + })) + + // Select best match + const selectedAgent = scoredAgents.sort((a, b) => b.score - a.score)[0] + + return selectedAgent.agent +} + +// Example: Select security reviewer for auth task +const agent = selectAgent({ + instruction: "Review authentication implementation", + requiredCapabilities: ["security-review"], + context: { files: ["src/auth/login.ts"] } +}) +// Returns: security-reviewer-001 +``` + +### Single-Purpose Virtual MCPs + +Agents are virtual MCPs with bounded, focused capabilities: + +**Characteristics**: +- **Single purpose**: Each agent optimized for one type of task +- **Bounded tools**: Limited toolset prevents scope creep +- **Predictable behavior**: Narrow focus ensures consistent results +- **Reusable**: Agents can be spawned on multiple tasks + +```typescript +// Agent as single-purpose virtual MCP +const securityReviewerAgent = { + agentId: "security-reviewer-001", + virtualMCPId: "agent-security-reviewer-001", + + // Bounded toolset + tools: [ + "SECURITY_SCAN", + "CVE_LOOKUP", + "GENERATE_SECURITY_REPORT" + ], + + // Focused resources + resources: [ + { + uri: "agent://security-reviewer-001/owasp-top-10", + name: "OWASP Top 10 Checklist" + }, + { + uri: "agent://security-reviewer-001/patterns", + name: "Security Anti-patterns" + } + ], + + // Specialized prompts + prompts: [ + { + name: "security-analysis", + template: "Analyze for: SQL injection, XSS, auth bypasses\n\nCode:\n{{code}}" + } + ] +} +``` + +### Agent Spawning Flow + +```mermaid +graph TD + A[Decopilot receives task] --> B{Task requires
specialized agent?} + B -->|Yes| C[Query agent registry] + B -->|No| D[Handle with decopilot] + + C --> E[Filter by capabilities] + E --> F[Score by relevance] + F --> G[Select best agent] + + G --> H[Create child task] + H --> I[Spawn agent on task] + I --> J[Agent executes] + + J --> K{Task complete?} + K -->|No| J + K -->|Yes| L[Return result] + + L --> M[Integrate findings] + M --> N[Continue main loop] + + D --> N + + style G fill:#e1f5ff + style J fill:#ffe1e1 +``` + +## Dynamic Virtual MCP Features + +Virtual MCPs are dynamically configurable, enabling decopilot to reshape the environment as it works. This is the core capability that differentiates decopilot from traditional AI assistants. + +### Inline Prompts + +Decopilot can create and update prompts within the current virtual MCP: + +```typescript +// Creating an inline prompt +decopilot.invokeTool("VIRTUAL_MCP_ADD_PROMPT", { + name: "mobile-pr-checklist", + description: "Checklist for mobile feature PRs", + template: ` +## Mobile Feature PR Checklist + +### Testing +- [ ] iOS device tested +- [ ] Android device tested +- [ ] Tablet layouts verified +- [ ] Dark mode tested + +### Performance +- [ ] Bundle size impact measured +- [ ] Load time profiled +- [ ] Memory usage checked + +### Accessibility +- [ ] Screen reader tested +- [ ] Keyboard navigation verified +- [ ] Color contrast validated + +Description: +{{description}} + `.trim() +}) + +// Using the prompt later +decopilot.invokePrompt("mobile-pr-checklist", { + description: "Add biometric authentication" +}) +``` + +### Inline Resources + +Decopilot can create resources that persist in the virtual MCP: + +```typescript +// Creating a resource as decopilot works +decopilot.invokeTool("VIRTUAL_MCP_ADD_RESOURCE", { + uri: "project://mobile-app-rewrite/auth-architecture", + name: "Authentication Architecture", + mimeType: "text/markdown", + content: ` +# Authentication Architecture + +## Overview +The mobile app uses biometric authentication with fallback to PIN/password. + +## Components +- BiometricAuthManager: Handles face ID / fingerprint +- SessionManager: Manages auth sessions +- TokenStore: Secure storage for tokens + +## Flow +1. User attempts login +2. BiometricAuthManager checks availability +3. If available, prompt for biometric +4. If successful, generate session token +5. SessionManager stores token + `.trim() +}) + +// Resource is now available in project scope +decopilot.readResource("project://mobile-app-rewrite/auth-architecture") +``` + +### Inline Tools + +Decopilot can define new tools within the virtual MCP: + +```typescript +// Defining an inline tool +decopilot.invokeTool("VIRTUAL_MCP_ADD_TOOL", { + name: "MOBILE_TEST_ALL_PLATFORMS", + description: "Run tests on iOS and Android simulators", + inputSchema: { + type: "object", + properties: { + testSuite: { + type: "string", + enum: ["unit", "integration", "e2e"] + } + } + }, + implementation: { + type: "composite", // Orchestrates other tools + steps: [ + { + tool: "RUN_TESTS", + input: { + platform: "ios", + suite: "{{testSuite}}" + } + }, + { + tool: "RUN_TESTS", + input: { + platform: "android", + suite: "{{testSuite}}" + } + } + ] + } +}) + +// Tool is now available in project scope +decopilot.invokeTool("MOBILE_TEST_ALL_PLATFORMS", { + testSuite: "integration" +}) +``` + +### Extensibility Pattern + +The dynamic features follow a consistent pattern: + +1. **Identify need**: Decopilot recognizes a recurring pattern or missing capability +2. **Create inline feature**: Add prompt, resource, or tool to virtual MCP +3. **Persist in scope**: Feature becomes part of the virtual MCP configuration +4. **Reuse**: Feature available for future operations in this scope + +```typescript +// Extensibility pattern example +const workflowPattern = { + // 1. Identify need + observation: "Creating mobile PRs requires same checklist every time", + + // 2. Create inline feature + action: { + tool: "VIRTUAL_MCP_ADD_PROMPT", + input: { + name: "mobile-pr-checklist", + template: "{{checklist}}" + } + }, + + // 3. Persist in scope + result: "Prompt added to project virtual MCP", + + // 4. Reuse + nextTime: "Use mobile-pr-checklist prompt for all mobile PRs" +} +``` + +### Editing Current Virtual MCP + +Decopilot always operates on the **current scope's virtual MCP**: + +```typescript +// Current scope determines which virtual MCP is edited +const editCurrentVirtualMCP = (scope: Scope) => { + // In project scope: edit project virtual MCP + if (scope.type === "project") { + editVirtualMCP(scope.virtualMCPId) // project-mobile-app-rewrite + } + + // In agent scope: edit agent virtual MCP + if (scope.type === "agent") { + editVirtualMCP(scope.virtualMCPId) // agent-security-reviewer-001 + } + + // In org scope: edit org virtual MCP + if (scope.type === "org") { + editVirtualMCP(scope.virtualMCPId) // org-acme-corp + } +} + +// Example: Add resource to current scope +// If in project scope: adds to project virtual MCP +// If in agent scope: adds to agent virtual MCP +decopilot.invokeTool("VIRTUAL_MCP_ADD_RESOURCE", { + uri: "{{scope}}://{{scopeId}}/new-resource", + name: "New Resource", + content: "..." +}) +``` + +## Tool Scope Sensitivity + +All decopilot tools are **scope-sensitive**—they operate on the current scope's virtual MCP. The same tool behaves differently depending on whether you're in org, project, or agent scope. + +### Scope-Sensitive Tool Behavior + +```typescript +// Tool behavior adapts to scope +const READ_RESOURCE_TOOL = { + name: "READ_RESOURCE", + description: "Read a resource from the current scope", + + handler: async (input: { uri: string }, ctx: MeshContext) => { + // Determine current scope + const scope = ctx.getCurrentScope() + + // Resolve resource URI based on scope + if (scope.type === "org") { + // Read from org virtual MCP + return readFromVirtualMCP("org-" + scope.orgId, input.uri) + } + + if (scope.type === "project") { + // Read from project virtual MCP (with org inheritance) + return readFromVirtualMCP("project-" + scope.projectId, input.uri) + } + + if (scope.type === "agent") { + // Read from agent virtual MCP (with project/org inheritance) + return readFromVirtualMCP("agent-" + scope.agentId, input.uri) + } + } +} +``` + +### Scope Resolution Examples + +```typescript +// Same tool, different scope = different behavior + +// In org scope (/:org/settings) +decopilot.readResource("org://acme-corp/security-policy") +// Reads from: org virtual MCP + +// In project scope (/:org/projects/mobile-app) +decopilot.readResource("project://mobile-app/architecture") +// Reads from: project virtual MCP + +// In agent scope (/:org/agents/security-reviewer) +decopilot.readResource("agent://security-reviewer/checklist") +// Reads from: agent virtual MCP +``` + +### Tool Scope Filtering + +Tools are filtered based on scope: + +```typescript +// Tool availability per scope +const toolFilter = (scope: Scope) => { + const allTools = getAllTools() + + return allTools.filter(tool => { + // Org scope: org-level tools only + if (scope.type === "org") { + return tool.scopeLevel === "org" + } + + // Project scope: project + org tools + if (scope.type === "project") { + return ["project", "org"].includes(tool.scopeLevel) + } + + // Agent scope: agent + project + org tools + if (scope.type === "agent") { + return ["agent", "project", "org"].includes(tool.scopeLevel) + } + }) +} + +// Example: List tools in project scope +const projectTools = toolFilter({ type: "project", projectId: "mobile-app" }) +// Returns: CREATE_PR, DEPLOY_STAGING, ORG_RESOURCE_CREATE +``` + +### Operating on Current Scope + +Tools that modify virtual MCPs always operate on the **current scope**: + +```typescript +// Adding a resource to current scope's virtual MCP +decopilot.invokeTool("ADD_RESOURCE", { + // No explicit scope needed - uses current scope + name: "New Documentation", + content: "# Documentation\n\n..." +}) + +// Scope resolution (internal) +const scope = getCurrentScope() +if (scope.type === "project") { + addToVirtualMCP("project-" + scope.projectId, resource) +} +``` + +### Cross-Scope Operations + +Some operations can cross scopes: + +```typescript +// Connecting external MCP to project (from org scope) +// You're in org scope: /:org/connections +decopilot.invokeTool("CONNECT_EXTERNAL_MCP", { + externalMCPUrl: "https://github-mcp.example.com", + targetScope: { + type: "project", + projectId: "mobile-app-rewrite" + } +}) + +// Creates connection and wires to project virtual MCP +``` + +### Scope Context Injection + +Every tool receives scope context: + +```typescript +// Tool definition with scope context +const DEPLOY_TOOL = defineTool({ + name: "DEPLOY_STAGING", + description: "Deploy to staging environment", + + handler: async (input, ctx: MeshContext) => { + // Scope context automatically injected + const scope = ctx.getCurrentScope() + + // Scope determines deployment config + if (scope.type === "project") { + const projectConfig = await ctx.storage.projects.get(scope.projectId) + const stagingUrl = projectConfig.stagingUrl + + return deploy(stagingUrl, input) + } + + throw new Error("DEPLOY_STAGING requires project scope") + } +}) +``` + +## Architecture Diagrams + +### Diagram 1: Decopilot → Virtual MCP vs External MCP + +This diagram illustrates the fundamental architectural constraint: decopilot operates on (editable) virtual MCPs and consumes (read-only) external MCPs. + +```mermaid +graph TB + subgraph "Decopilot Operations" + A[Decopilot] + end + + subgraph "Virtual MCPs (Editable)" + B[Org Virtual MCP] + C[Project Virtual MCP] + D[Agent Virtual MCP] + end + + subgraph "External MCPs (Read-Only)" + E[GitHub MCP Server] + F[Figma MCP Server] + G[Database MCP Server] + end + + A -->|Operates on
Can edit| B + A -->|Operates on
Can edit| C + A -->|Operates on
Can edit| D + + A -.->|Invokes tools
Read-only| E + A -.->|Invokes tools
Read-only| F + A -.->|Invokes tools
Read-only| G + + C -->|Connects to| E + C -->|Connects to| F + C -->|Connects to| G + + style A fill:#ffe1e1 + style B fill:#e1f5ff + style C fill:#e1f5ff + style D fill:#e1f5ff + style E fill:#e1e1e1 + style F fill:#e1e1e1 + style G fill:#e1e1e1 +``` + +### Diagram 2: Routes → Scopes → Virtual MCPs + +This diagram shows how routes automatically determine scope, which determines the virtual MCP decopilot operates on. + +```mermaid +graph LR + subgraph "Routes" + A1[/:org/settings] + A2[/:org/connections] + B1[/:org/projects/:id] + B2[/:org/projects/:id/settings] + C1[/:org/agents/:id] + C2[/:org/agents/:id/config] + end + + subgraph "Scopes" + A[Org Scope] + B[Project Scope] + C[Agent Scope] + end + + subgraph "Virtual MCPs" + D[Org Virtual MCP
org-acme-corp] + E[Project Virtual MCP
project-mobile-app] + F[Agent Virtual MCP
agent-security-reviewer] + end + + A1 --> A + A2 --> A + B1 --> B + B2 --> B + C1 --> C + C2 --> C + + A --> D + B --> E + C --> F + + D --> G[Org-wide
Tools/Resources/Prompts] + E --> H[Project-specific
Tools/Resources/Connected MCPs] + F --> I[Agent-bounded
Tools/Resources/Task Prompts] + + style A fill:#e1f5ff + style B fill:#fff4e1 + style C fill:#ffe1e1 + style D fill:#e1f5ff + style E fill:#fff4e1 + style F fill:#ffe1e1 +``` + +### Diagram 3: Org/Project/Agent as Virtual MCPs + +This diagram illustrates the virtual MCP hierarchy and how capabilities flow from org to project to agent. + +```mermaid +graph TB + subgraph "Org Virtual MCP" + A[Organization
org-acme-corp] + A1[Org Tools] + A2[Org Resources] + A3[Org Prompts] + A4[Connection Registry] + end + + subgraph "Project Virtual MCP" + B[Project
project-mobile-app] + B1[Project Tools] + B2[Project Resources] + B3[Connected MCPs] + B4[Project Prompts] + end + + subgraph "Agent Virtual MCP" + C[Agent
agent-security-reviewer] + C1[Bounded Tools] + C2[Agent Resources] + C3[Task Prompts] + end + + A --> A1 + A --> A2 + A --> A3 + A --> A4 + + B --> B1 + B --> B2 + B --> B3 + B --> B4 + + C --> C1 + C --> C2 + C --> C3 + + A -.->|Inherits| B + B -.->|Inherits| C + + A4 -.->|Provides connections to| B3 + + style A fill:#e1f5ff + style B fill:#fff4e1 + style C fill:#ffe1e1 +``` + +### Diagram 4: Task-Based Agent Spawning + +This diagram shows the async execution model where decopilot spawns agents on tasks with isolated contexts. + +```mermaid +sequenceDiagram + participant U as User + participant D as Decopilot
(Main Loop) + participant R as Agent Registry + participant A as Security Agent
(Child Task) + participant M as Cheap Model
(Completion Detection) + + U->>D: Request: "Review auth code for security" + + D->>D: Determine task requires specialized agent + D->>R: Query agents with "security-review" capability + R-->>D: Return: security-reviewer-001 + + D->>A: Spawn agent on child task + Note over A: Isolated context
Task ID: task-001
Type: child + + par Agent executes async + A->>A: Invoke SECURITY_SCAN + A->>A: Invoke CVE_LOOKUP + A->>A: Generate findings + and Main loop continues + D->>D: Continue with other work + end + + A->>M: Check if task complete + M-->>A: YES - findings generated + + A-->>D: Return result:
"Found 2 vulnerabilities" + + D->>D: Integrate findings into main context + D->>U: Present agent findings + + Note over D,A: Task-001 status: successful +``` + +--- + +## Key Takeaways + +**Virtual MCP constraint**: Decopilot only works with virtual MCPs because it needs editability. External MCPs are read-only; virtual MCPs are the editable foundation. + +**Everything is a virtual MCP**: Organizations, projects, and agents are all virtual MCPs. This consistency enables a unified architecture. + +**Scope determines behavior**: Routes automatically set scope, which determines the virtual MCP decopilot operates on. Same tools, different behavior per scope. + +**Task-based async execution**: Agents spawn on tasks with isolated contexts, enabling parallel work without context pollution. + +**Dynamic capabilities**: Decopilot can add tools, create resources, and update prompts as it works—reshaping the environment rather than just consuming it. + +**Clear separation**: External MCPs provide stable tools. Virtual MCPs provide dynamic aggregation and editability. Decopilot operates on virtual MCPs and invokes tools from external MCPs. + +Understanding this architecture is essential to using decopilot effectively—it's not just a chatbot with API access, it's a system that dynamically configures and operates on virtual MCP infrastructure. + +--- + +**Ready to dive deeper?** Explore [Scopes](/en/mcp-mesh/decopilot/scopes) for scope-based routing details, or learn about [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to understand the foundation layer. For practical implementation, see [Projects](/en/mcp-mesh/projects) and explore how to configure project-level virtual MCPs. From c545b60f503dcc26dc4f364604be2df8c265df56 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 17:36:45 -0300 Subject: [PATCH 10/51] docs: document decopilot context management Create mcp-mesh/decopilot/context-management.mdx explaining how decopilot manages context window, CLAUDE.md/AGENTS.md support, and context isolation. Key content: - Context window composition and priority order - CLAUDE.md support (project and org-admin levels) - AGENTS.md support for agent-specific instructions - Context cost management and tool filtering strategies - Context isolation via agent spawning Closes beads-main-s5c Co-Authored-By: Claude Sonnet 4.5 --- .../mcp-mesh/decopilot/context-management.mdx | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx new file mode 100644 index 0000000000..e9a2944ce3 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx @@ -0,0 +1,138 @@ +--- +title: Context Management +description: How decopilot manages context across scopes and maintains efficient token usage +icon: FileText +--- + +import Callout from "../../../../components/ui/Callout.astro"; + + + This page documents the **planned architecture** for decopilot context management. The implementation is in development. + + +Decopilot manages context through a priority-based system that balances completeness with efficiency. Context includes conversation history, tool definitions, resources, and project-specific instructions—all within the model's limited token window. + +## What Gets Included in Context + +Decopilot builds context in priority order: + +1. **System Instructions** - Core behavior definition (always present) +2. **CLAUDE.md** - Project and org-admin persistent rules +3. **AGENTS.md** - Agent-specific instructions via MCP server instructions property +4. **Conversation History** - Recent messages (automatically truncated) +5. **MCP Tool Definitions** - Filtered by agent type to reduce overhead +6. **Resources** - Loaded on-demand when explicitly requested + +## CLAUDE.md Support + +CLAUDE.md provides persistent context at two levels: org-admin (`/:org` scope) for organization-wide rules, and project (`/:org/projects/:id` scope) for project-specific guidelines. + +**Precedence handling**: When both levels define conflicting rules, project-level CLAUDE.md takes precedence. This allows project-specific overrides while maintaining organization-wide defaults. For example, an org-admin might enforce Conventional Commits across all projects, but a specific project could override commit message format for integration with external systems. + +**Conflict resolution**: Decopilot merges non-conflicting rules. If org-admin specifies testing requirements and project-level adds deployment guidelines, both apply. Only direct conflicts trigger precedence resolution. + +**Best practices**: Keep CLAUDE.md concise (under 500 words), focus on persistent rules rather than one-time instructions, use clear markdown formatting, and update content as patterns emerge across multiple conversations. + +### Example: Project-Level CLAUDE.md + +```markdown +# Mobile App Project + +## Stack +- React Native 0.74, TypeScript 5.9, Expo SDK 52 + +## Code Conventions +- Functional components with hooks +- API calls in `src/services/` +- Colocate tests, use Zod for validation + +## Testing +- Run `bun test` before committing +``` + +### Example: Org-Admin Level CLAUDE.md + +```markdown +# Organization Guidelines + +## Principles +- Security first: validate all inputs +- WCAG 2.1 AA compliance +- Update docs alongside code + +## Git Workflow +- Conventional commits: `type(scope): message` +- PR review required +``` + +## AGENTS.md Support + +AGENTS.md provides agent-specific instructions via the MCP server's `instructions` property. Both project and org-admin virtual MCPs return this content—spawned agents automatically receive targeted guidance for their specific purpose. + +### Example: AGENTS.md Structure + +```markdown +# Agent Instructions + +## Research Agents +**Purpose**: Explore and analyze without modification + +**Guidelines**: +- Read-only operations only +- Document findings in structured format +- Tools: LIST_FILES, READ_FILE, SEARCH_CODE + +## Development Agents +**Purpose**: Implement features and fix bugs + +**Guidelines**: +- Create feature branches +- Write tests alongside implementation +- Tools: CREATE_BRANCH, COMMIT_CHANGES, RUN_TESTS +``` + +## Context Cost Management + +Tool definitions consume significant tokens—a typical MCP server with 50 tools can use 5,000-10,000 tokens just for tool definitions. With Claude's 200K context window, unfiltered tools from multiple servers quickly exhaust available space. + +**Token cost examples**: A single comprehensive tool definition (name, description, parameters with JSON schema) averages 100-200 tokens. A project with 3 MCP servers (filesystem, git, API client) exposing 150 total tools could consume 15,000-30,000 tokens before any conversation begins. This leaves less room for conversation history, code context, and reasoning. + +### Tool Filtering + +Virtual MCPs enable dynamic filtering based on agent type and task requirements. Rather than exposing all tools to every agent, decopilot selectively includes only relevant tools: + +```typescript +// Research agent sees filtered tools +{ + agentType: "research", + tools: ["LIST_FILES", "READ_FILE", "SEARCH_CODE"] + // CREATE_PR, DEPLOY filtered out +} +``` + +**Filtering strategies**: Development agents receive write operations (CREATE_BRANCH, COMMIT_CHANGES), research agents get read-only tools (READ_FILE, SEARCH_CODE), and deployment agents access infrastructure tools (DEPLOY, ROLLBACK). This reduces average tool context from 15,000 tokens to 3,000-5,000 tokens depending on agent type. + +Resources load only when explicitly requested through tool calls, preventing automatic inclusion in base context. This on-demand approach keeps initial context minimal while providing access to full project resources when needed. + +## Context Isolation via Agent Spawning + +Agent spawning provides fresh context for specific tasks. As decopilot works through complex problems, context accumulates—conversation history grows, resources are loaded, and the context window fills. Spawning an agent creates clean context focused on one task, then integrates results back without polluting the parent context. + +**Technical implementation**: Each spawned agent receives a new task ID and isolated context. The parent decopilot maintains its conversation history and resources, while the child agent starts with only essential context. When the agent completes, results are summarized and returned to the parent—typically 200-500 tokens instead of the full 10,000+ token conversation the agent had. + +Spawned agents receive: +- System instructions, CLAUDE.md, AGENTS.md +- Task description and filtered tools +- NO parent conversation history or accumulated resources + +This isolation ensures agents focus on their specific task without distraction from unrelated context. A security review agent doesn't need to know about UI design decisions from earlier in the conversation. A documentation agent doesn't need git history from unrelated branches. + +**Benefits**: Faster processing due to smaller context, better focus on specific objectives, parallel execution of independent tasks, and cleaner results integrated back to parent. See [Task-Based Agent Spawning](/en/mcp-mesh/decopilot/architecture#task-based-agent-spawning) for implementation details. + +## Summary + +Decopilot balances completeness with efficiency through priority-based inclusion, tool filtering, on-demand resources, and agent spawning. Virtual MCPs enable dynamic, scope-aware context management for efficient operation within token limits. + +--- + +Explore [Scopes](/en/mcp-mesh/decopilot/scopes) to understand how routing determines context, or [Task-Based Agent Spawning](/en/mcp-mesh/decopilot/architecture#task-based-agent-spawning) for fresh context isolation. From 980eecece52e834dc7f3be6dbdde58b244cf22a2 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 17:45:42 -0300 Subject: [PATCH 11/51] docs: document decopilot built-in tools Create comprehensive reference documentation for decopilot's 11 built-in tools: - Org-related tools (agent_spawn, agent_search, user_ask_question) - Current virtual MCP tools (resource_*, prompt_*, tools_*) - Target virtual MCP tools (discovery and enablement workflow) Includes tool specifications, scope-sensitive behavior examples, and complete workflows for discovering and enabling external MCP tools. Closes beads-main-ifv Co-Authored-By: Claude Sonnet 4.5 --- .../content/en/mcp-mesh/decopilot/tools.mdx | 1129 +++++++++++++++++ 1 file changed, 1129 insertions(+) create mode 100644 apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx new file mode 100644 index 0000000000..2740b0af30 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx @@ -0,0 +1,1129 @@ +--- +title: Tools +description: Built-in decopilot tools and how to work with target virtual MCP tools +icon: Wrench +--- + +import Callout from "../../../../components/ui/Callout.astro"; + + + This page documents the **planned architecture** for decopilot tools. The specification serves as the implementation guide for the decopilot module. + + +## What are Decopilot Tools? + +Decopilot tools are the mechanism through which decopilot interacts with virtual MCPs, spawns agents, asks users questions, and manages capabilities across different scopes. Tools fall into two fundamental categories with distinct purposes and availability patterns. + +**Built-in tools** are always available to decopilot regardless of scope. These core capabilities enable decopilot to manage agents, interact with users, and manipulate the current virtual MCP's configuration. + +**Target virtual MCP tools** are capabilities from the target virtual MCP (current scope) that decopilot must discover and enable before use. These include tools from connected external MCP servers and inline tools defined within the virtual MCP. + +Understanding the distinction between these two categories is essential—built-in tools provide foundational capabilities, while target virtual MCP tools provide domain-specific operations that vary by scope. + +## Tool Architecture + +Decopilot's tool architecture follows a two-tier model that separates meta-level operations from domain-specific capabilities. + +### Category 1: Built-in Tools (Always Available) + +Built-in tools will be implemented directly in the decopilot module and are always available regardless of the current scope. These tools enable: + +- **Agent management**: Spawning and searching for agents across the organization +- **User interaction**: Asking questions and gathering input (restricted in child tasks) +- **Virtual MCP manipulation**: Reading, editing, searching, and enabling capabilities within the current scope + +Built-in tools operate at the meta level—they manage the environment itself rather than performing domain-specific work. For example, `agent_spawn` doesn't write code or create pull requests; it delegates to another agent that has those capabilities. + +```typescript +// Built-in tool example (specification) +const AGENT_SPAWN = { + name: "agent_spawn", + description: "Spawn an agent with context to work on a specific task", + inputSchema: { + type: "object", + properties: { + agent_id: { + type: "string", + description: "ID of the agent to spawn" + }, + prompt: { + type: "string", + description: "Task description and context for the agent" + } + }, + required: ["agent_id", "prompt"] + }, + outputSchema: { + type: "object", + properties: { + task_id: { + type: "string", + description: "ID of the created task" + } + }, + required: ["task_id"] + } +} +``` + +### Category 2: Target Virtual MCP Tools (Discovered/Enabled) + +Target virtual MCP tools come from the current scope's virtual MCP. These tools must be: + +1. **Discovered** via `tools_search` to find available capabilities +2. **Enabled** via `tool_enable` before they can be invoked +3. **Used** once enabled within the current task + +These tools include: + +- **External MCP tools**: Connected from external servers like GitHub, Slack, or databases +- **Inline tools**: Defined directly within the virtual MCP configuration + +The discovery and enablement requirement ensures decopilot explicitly chooses which capabilities to use, preventing tool overload and maintaining focused execution. + +```typescript +// Workflow: discover and enable tools +// 1. Search for available tools +decopilot.invokeTool("tools_search", { search_term: "github" }) +// Returns: ["CREATE_PR", "LIST_ISSUES", "CREATE_BRANCH"] + +// 2. Enable specific tool +decopilot.invokeTool("tool_enable", { tool_name: "CREATE_PR" }) +// Tool is now available for invocation + +// 3. Use the enabled tool +decopilot.invokeTool("CREATE_PR", { + title: "Add authentication feature", + body: "Implements biometric authentication" +}) +``` + +## Understanding Scope-Sensitive Tools + +All built-in tools that operate on the current virtual MCP are **scope-sensitive**—they adapt behavior based on whether decopilot is in org, project, or agent scope. + +### Scope-Dependent Behavior + +The same tool invocation produces different results depending on the current scope: + +**In org scope** (`/:org/settings`): +- `resource_read("org://acme-corp/security-policy")` reads from org virtual MCP +- `tools_search()` lists org-level tools and all connected external MCPs +- `tool_enable()` enables tools within the org virtual MCP context + +**In project scope** (`/:org/projects/:mobile-app`): +- `resource_read("project://mobile-app/architecture")` reads from project virtual MCP +- `tools_search()` lists project tools, inherited org tools, and project-connected external MCPs +- `tool_enable()` enables tools within the project virtual MCP context + +**In agent scope** (`/:org/agents/:security-reviewer`): +- `resource_read("agent://security-reviewer/checklist")` reads from agent virtual MCP +- `tools_search()` lists bounded agent tools and inherited capabilities +- `tool_enable()` enables tools within the agent virtual MCP context + +The scope determines which virtual MCP the tool operates on. This automatic adaptation ensures tools always work with the correct context without requiring explicit scope parameters. + +### Scope Inheritance + +Virtual MCPs inherit capabilities from parent scopes: + +- **Agent scope** inherits from project (if spawned in project context) and org +- **Project scope** inherits from org +- **Org scope** is the foundation level + +When `tools_search` runs in project scope, it returns project-specific tools AND org-level tools. When `resource_read` looks for a resource, it checks the current scope first, then falls back to parent scopes. + +## Tool Categories + +Built-in tools are organized by functional category based on their purpose. + +### Org-Related Tools (Always Available) + +These tools manage agents and user interaction across the organization. + +**`agent_spawn`**: Spawn an agent with context to execute a specific task. Creates a child task with isolated context. Agent runs until completion, then returns results to the main decopilot loop. + +**`agent_search`**: Search or list agents configured in the current organization. Empty search term returns all agents. Used to discover available agents before spawning. + +**`user_ask_question`**: Ask the user questions to gather input or clarification. Disabled in child tasks (agent-spawned) to prevent blocking execution. Only available in top-level tasks (user-initiated). + +### Current Virtual MCP Tools (Always Available, Scope-Sensitive) + +These tools operate on the current scope's virtual MCP, adapting behavior based on org/project/agent context. + +**`resource_read`**: Read a resource by URI from the current scope's virtual MCP. Supports scope inheritance—searches current scope first, then parent scopes. + +**`resource_edit`**: Create, update, or delete a resource in the current scope. Scope determines which virtual MCP is modified. Supports content updates and deletion. + +**`prompt_read`**: Read a prompt by name from the current scope's virtual MCP. Prompts are templates with variables that can be invoked with parameters. + +**`prompt_edit`**: Create, update, or delete a prompt in the current scope. Enables decopilot to define reusable prompt templates as it works. + +**`tools_read`**: Read detailed information about a specific tool by name from the current scope. Returns full tool specification including input/output schemas. + +**`tools_edit`**: Edit an inline tool by name within the current scope. Can modify tool definitions, including changing which scope the tool belongs to. Cannot edit external MCP tools (read-only). + +**`tools_search`**: Search or list tools available in the target virtual MCP. Empty search term returns all tools. Returns tools from current scope, inherited parent scopes, and connected external MCPs. + +**`tool_enable`**: Enable a tool from the target virtual MCP before invoking it. Required before calling any target virtual MCP tool. Once enabled, the tool becomes available for the current task. + +## Built-in Tool Reference + +This section provides detailed specifications for each built-in tool. + +### agent_spawn + +Spawn an agent with context to work on a specific task. Creates a child task with isolated context that runs until the agent responds. + +**Signature**: `agent_spawn(agent_id: string, prompt: string) -> task_id: string` + +**Input Schema**: +```typescript +{ + agent_id: string // ID of the agent to spawn + prompt: string // Task description and context for the agent +} +``` + +**Output Schema**: +```typescript +{ + task_id: string // ID of the created child task +} +``` + +**Behavior**: +- Creates a child task with isolated context +- Agent receives fresh context (no parent conversation history) +- Agent runs until it responds with findings or completion +- Main decopilot loop continues without blocking +- Results integrate back into parent context when task completes + +**Restrictions**: +- Disabled in child tasks by default (prevents infinite spawning) +- Only available in top-level tasks unless explicitly enabled + +**Example**: +```typescript +// Spawn security review agent on specific files +const result = await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer-001", + prompt: "Review src/auth/login.ts and src/auth/session.ts for security vulnerabilities. Focus on SQL injection, XSS, and auth bypasses." +}) +// Returns: { task_id: "task-abc-123" } +``` + +### agent_search + +Search or list agents configured in the current organization. Empty search term returns all agents. + +**Signature**: `agent_search(search_term?: string) -> Agent[]` + +**Input Schema**: +```typescript +{ + search_term?: string // Optional search term (empty = list all) +} +``` + +**Output Schema**: +```typescript +{ + agents: [ + { + agent_id: string + name: string + purpose: string + capabilities: string[] + } + ] +} +``` + +**Behavior**: +- Queries organization agent registry +- Filters by search term if provided (matches name, purpose, capabilities) +- Returns all agents if search term is empty +- Results ordered by relevance (if searching) or alphabetically (if listing) + +**Example**: +```typescript +// Search for security-related agents +const result = await decopilot.invokeTool("agent_search", { + search_term: "security" +}) +// Returns: [{ agent_id: "security-reviewer-001", name: "Security Reviewer", ... }] + +// List all agents +const allAgents = await decopilot.invokeTool("agent_search", {}) +``` + +### user_ask_question + +Ask the user a question to gather input or clarification. Disabled in child tasks to prevent blocking execution. + +**Signature**: `user_ask_question(question: string, options?: { type: string, choices?: string[] }) -> string` + +**Input Schema**: +```typescript +{ + question: string // Question to ask the user + options?: { + type: "text" | "choice" | "confirmation" + choices?: string[] // For choice type + } +} +``` + +**Output Schema**: +```typescript +{ + answer: string // User's response +} +``` + +**Behavior**: +- Presents question to user in UI +- Task status changes to "Needs Input" +- Execution pauses until user responds +- Returns user's answer when provided + +**Restrictions**: +- **Disabled in child tasks** (agent-spawned tasks cannot ask user questions) +- Only available in top-level tasks (user-initiated) +- Prevents agents from blocking on user input + +**Example**: +```typescript +// Ask for confirmation before deployment +const result = await decopilot.invokeTool("user_ask_question", { + question: "Deploy to production? This will affect live users.", + options: { type: "confirmation" } +}) +// Returns: { answer: "yes" } or { answer: "no" } + +// Ask for choice +const result = await decopilot.invokeTool("user_ask_question", { + question: "Which environment should we deploy to?", + options: { + type: "choice", + choices: ["staging", "production", "development"] + } +}) +``` + +### resource_read + +Read a resource by URI from the current scope's virtual MCP. Supports scope inheritance. + +**Signature**: `resource_read(uri: string) -> { content: string, mimeType: string }` + +**Input Schema**: +```typescript +{ + uri: string // Resource URI (e.g., "project://mobile-app/architecture") +} +``` + +**Output Schema**: +```typescript +{ + content: string // Resource content + mimeType: string // MIME type (e.g., "text/markdown") + name: string // Resource name +} +``` + +**Behavior**: +- Resolves URI based on current scope +- Searches current scope's virtual MCP first +- Falls back to parent scopes if not found (inheritance) +- Returns resource content and metadata + +**Scope-sensitive**: +- Org scope: reads from org virtual MCP +- Project scope: reads from project virtual MCP (with org inheritance) +- Agent scope: reads from agent virtual MCP (with project/org inheritance) + +**Example**: +```typescript +// In project scope: read project architecture doc +const result = await decopilot.invokeTool("resource_read", { + uri: "project://mobile-app/architecture" +}) +// Returns: { content: "# Architecture\n\n...", mimeType: "text/markdown", ... } + +// Read org-level resource (inheritance) +const orgResource = await decopilot.invokeTool("resource_read", { + uri: "org://acme-corp/security-policy" +}) +``` + +### resource_edit + +Create, update, or delete a resource in the current scope's virtual MCP. + +**Signature**: `resource_edit(uri: string, content?: string, operation: "create" | "update" | "delete") -> { success: boolean }` + +**Input Schema**: +```typescript +{ + uri: string // Resource URI + content?: string // Resource content (required for create/update) + mimeType?: string // MIME type (default: "text/markdown") + name?: string // Resource name (required for create) + operation: "create" | "update" | "delete" +} +``` + +**Output Schema**: +```typescript +{ + success: boolean +} +``` + +**Behavior**: +- Creates, updates, or deletes resource in current scope's virtual MCP +- Scope determines which virtual MCP is modified +- Create fails if resource already exists +- Update fails if resource doesn't exist +- Delete removes resource from virtual MCP + +**Scope-sensitive**: +- Org scope: modifies org virtual MCP +- Project scope: modifies project virtual MCP +- Agent scope: modifies agent virtual MCP + +**Example**: +```typescript +// Create new resource in project scope +const result = await decopilot.invokeTool("resource_edit", { + uri: "project://mobile-app/deployment-checklist", + name: "Deployment Checklist", + content: "# Deployment\n\n- [ ] Run tests\n- [ ] Update changelog", + mimeType: "text/markdown", + operation: "create" +}) + +// Update existing resource +await decopilot.invokeTool("resource_edit", { + uri: "project://mobile-app/deployment-checklist", + content: "# Deployment\n\n- [ ] Run tests\n- [ ] Update changelog\n- [ ] Notify team", + operation: "update" +}) + +// Delete resource +await decopilot.invokeTool("resource_edit", { + uri: "project://mobile-app/old-doc", + operation: "delete" +}) +``` + +### prompt_read + +Read a prompt by name from the current scope's virtual MCP. + +**Signature**: `prompt_read(name: string) -> { template: string, description: string }` + +**Input Schema**: +```typescript +{ + name: string // Prompt name +} +``` + +**Output Schema**: +```typescript +{ + name: string + description: string + template: string // Template with {{variables}} +} +``` + +**Behavior**: +- Searches current scope's virtual MCP for prompt +- Falls back to parent scopes if not found (inheritance) +- Returns prompt template and metadata + +**Scope-sensitive**: +- Org scope: reads from org virtual MCP +- Project scope: reads from project virtual MCP (with org inheritance) +- Agent scope: reads from agent virtual MCP (with project/org inheritance) + +**Example**: +```typescript +// Read code review prompt +const result = await decopilot.invokeTool("prompt_read", { + name: "security-review" +}) +// Returns: { name: "security-review", template: "Review for:\n- SQL injection\n...", ... } +``` + +### prompt_edit + +Create, update, or delete a prompt in the current scope's virtual MCP. + +**Signature**: `prompt_edit(name: string, template?: string, operation: "create" | "update" | "delete") -> { success: boolean }` + +**Input Schema**: +```typescript +{ + name: string // Prompt name + description?: string // Prompt description (required for create) + template?: string // Template with {{variables}} (required for create/update) + operation: "create" | "update" | "delete" +} +``` + +**Output Schema**: +```typescript +{ + success: boolean +} +``` + +**Behavior**: +- Creates, updates, or deletes prompt in current scope's virtual MCP +- Scope determines which virtual MCP is modified +- Prompts can include variables using `{{variableName}}` syntax + +**Scope-sensitive**: +- Org scope: modifies org virtual MCP +- Project scope: modifies project virtual MCP +- Agent scope: modifies agent virtual MCP + +**Example**: +```typescript +// Create new prompt template +const result = await decopilot.invokeTool("prompt_edit", { + name: "mobile-pr-template", + description: "PR template for mobile features", + template: "## Mobile Feature PR\n\n{{description}}\n\n### Testing\n- [ ] iOS tested\n- [ ] Android tested", + operation: "create" +}) + +// Update prompt template +await decopilot.invokeTool("prompt_edit", { + name: "mobile-pr-template", + template: "## Mobile Feature PR\n\n{{description}}\n\n### Testing\n- [ ] iOS tested\n- [ ] Android tested\n- [ ] Tablet tested", + operation: "update" +}) +``` + +### tools_read + +Read detailed information about a specific tool by name from the current scope. + +**Signature**: `tools_read(tool_name: string) -> { name: string, description: string, inputSchema: object, outputSchema: object }` + +**Input Schema**: +```typescript +{ + tool_name: string // Name of the tool to read +} +``` + +**Output Schema**: +```typescript +{ + name: string + description: string + inputSchema: object // JSON Schema for input + outputSchema: object // JSON Schema for output + source: "inline" | "external" // Whether tool is inline or from external MCP +} +``` + +**Behavior**: +- Returns full tool specification including schemas +- Searches current scope's virtual MCP +- Includes inherited tools from parent scopes +- Useful for understanding tool capabilities before enabling + +**Scope-sensitive**: +- Resolves from current scope's virtual MCP and parent scopes +- Includes tools from connected external MCPs + +**Example**: +```typescript +// Read CREATE_PR tool specification +const result = await decopilot.invokeTool("tools_read", { + tool_name: "CREATE_PR" +}) +// Returns: { name: "CREATE_PR", description: "Create a pull request", inputSchema: {...}, ... } +``` + +### tools_edit + +Edit an inline tool by name within the current scope. Can modify tool definitions including scope assignment. + +**Signature**: `tools_edit(tool_name: string, definition?: object, operation: "create" | "update" | "delete") -> { success: boolean }` + +**Input Schema**: +```typescript +{ + tool_name: string // Tool name + definition?: { + description?: string + inputSchema?: object + outputSchema?: object + handler?: string // Tool implementation (inline code or composite workflow) + } + operation: "create" | "update" | "delete" +} +``` + +**Output Schema**: +```typescript +{ + success: boolean +} +``` + +**Behavior**: +- Creates, updates, or deletes inline tool in current scope's virtual MCP +- **Cannot edit external MCP tools** (read-only) +- Can change which scope a tool belongs to +- Scope determines which virtual MCP is modified + +**Scope-sensitive**: +- Org scope: modifies org virtual MCP +- Project scope: modifies project virtual MCP +- Agent scope: modifies agent virtual MCP + +**Restrictions**: +- Only works with inline tools (tools defined in virtual MCP) +- External MCP tools are read-only and cannot be modified + +**Example**: +```typescript +// Create new inline tool +const result = await decopilot.invokeTool("tools_edit", { + tool_name: "DEPLOY_STAGING", + definition: { + description: "Deploy to staging environment", + inputSchema: { + type: "object", + properties: { + branch: { type: "string" } + } + }, + handler: "composite" // Orchestrates other tools + }, + operation: "create" +}) + +// Update existing inline tool +await decopilot.invokeTool("tools_edit", { + tool_name: "DEPLOY_STAGING", + definition: { + description: "Deploy to staging environment with health checks", + inputSchema: { + type: "object", + properties: { + branch: { type: "string" }, + runHealthChecks: { type: "boolean", default: true } + } + } + }, + operation: "update" +}) +``` + +### tools_search + +Search or list tools available in the target virtual MCP. Empty search term returns all tools. + +**Signature**: `tools_search(search_term?: string) -> Tool[]` + +**Input Schema**: +```typescript +{ + search_term?: string // Optional search term (empty = list all) +} +``` + +**Output Schema**: +```typescript +{ + tools: [ + { + name: string + description: string + source: "inline" | "external" + enabled: boolean // Whether tool is currently enabled for use + } + ] +} +``` + +**Behavior**: +- Lists tools from current scope's virtual MCP +- Includes inherited tools from parent scopes +- Includes tools from connected external MCPs +- Filters by search term if provided +- Returns all tools if search term is empty + +**Scope-sensitive**: +- Org scope: lists org tools and connected external MCPs +- Project scope: lists project tools, inherited org tools, and project-connected external MCPs +- Agent scope: lists bounded agent tools and inherited capabilities + +**Example**: +```typescript +// Search for GitHub-related tools +const result = await decopilot.invokeTool("tools_search", { + search_term: "github" +}) +// Returns: [{ name: "CREATE_PR", description: "...", enabled: false }, ...] + +// List all available tools +const allTools = await decopilot.invokeTool("tools_search", {}) +// Returns all tools from current scope and parents +``` + +### tool_enable + +Enable a tool from the target virtual MCP before invoking it. Required before calling any target virtual MCP tool. + +**Signature**: `tool_enable(tool_name: string) -> { success: boolean }` + +**Input Schema**: +```typescript +{ + tool_name: string // Name of the tool to enable +} +``` + +**Output Schema**: +```typescript +{ + success: boolean + enabled: boolean // Whether tool is now enabled +} +``` + +**Behavior**: +- Enables tool for use in the current task +- Must be called before invoking any target virtual MCP tool +- Tool remains enabled for the duration of the task +- Does not persist across tasks (each task must enable tools explicitly) + +**Scope-sensitive**: +- Enables tool from current scope's virtual MCP +- Includes inherited tools from parent scopes + +**Example**: +```typescript +// Enable CREATE_PR before using it +const result = await decopilot.invokeTool("tool_enable", { + tool_name: "CREATE_PR" +}) +// Returns: { success: true, enabled: true } + +// Now CREATE_PR is available for invocation +await decopilot.invokeTool("CREATE_PR", { + title: "Add authentication feature", + body: "Implements biometric authentication" +}) +``` + +## Working with Target Virtual MCP Tools + +Target virtual MCP tools require a discovery and enablement workflow before use. This section explains the complete process. + +### Discovery Workflow + +Before using any target virtual MCP tool, you must discover what tools are available in the current scope: + +```typescript +// Step 1: Discover available tools +const result = await decopilot.invokeTool("tools_search", {}) +// Returns list of all tools in current scope + +// Step 2: Filter or search for specific capabilities +const githubTools = await decopilot.invokeTool("tools_search", { + search_term: "github" +}) +// Returns only GitHub-related tools + +// Step 3: Read tool details to understand capabilities +const toolDetails = await decopilot.invokeTool("tools_read", { + tool_name: "CREATE_PR" +}) +// Returns full specification with input/output schemas +``` + +### Enablement Workflow + +Once you've discovered a tool, enable it before invoking: + +```typescript +// Step 1: Enable the tool +await decopilot.invokeTool("tool_enable", { + tool_name: "CREATE_PR" +}) + +// Step 2: Use the enabled tool +await decopilot.invokeTool("CREATE_PR", { + title: "Add authentication", + body: "Implements biometric auth for iOS and Android", + base: "main", + head: "feature/biometric-auth" +}) +``` + +### Complete Example: GitHub PR Creation + +```typescript +// Full workflow from discovery to invocation +async function createPullRequest() { + // 1. Search for GitHub tools + const githubTools = await decopilot.invokeTool("tools_search", { + search_term: "github" + }) + console.log("Available GitHub tools:", githubTools) + + // 2. Read CREATE_PR specification + const prToolSpec = await decopilot.invokeTool("tools_read", { + tool_name: "CREATE_PR" + }) + console.log("CREATE_PR input schema:", prToolSpec.inputSchema) + + // 3. Enable CREATE_PR + await decopilot.invokeTool("tool_enable", { + tool_name: "CREATE_PR" + }) + + // 4. Create the PR + const result = await decopilot.invokeTool("CREATE_PR", { + title: "Add biometric authentication", + body: "Implements face ID and fingerprint authentication for mobile app", + base: "main", + head: "feature/biometric-auth" + }) + + console.log("PR created:", result.url) +} +``` + +### External vs Inline Tools + +Target virtual MCP tools come from two sources: + +**External MCP tools**: +- Connected from external MCP servers (GitHub, Slack, databases) +- Read-only (cannot be modified via `tools_edit`) +- Must be enabled before use +- Source shows as `"external"` in `tools_search` results + +**Inline tools**: +- Defined directly in the virtual MCP configuration +- Can be modified via `tools_edit` +- Must be enabled before use +- Source shows as `"inline"` in `tools_search` results + +```typescript +// Check tool source before attempting to edit +const toolInfo = await decopilot.invokeTool("tools_read", { + tool_name: "CREATE_PR" +}) + +if (toolInfo.source === "external") { + console.log("Cannot edit external MCP tool") +} else { + // Safe to edit inline tool + await decopilot.invokeTool("tools_edit", { + tool_name: "DEPLOY_STAGING", + definition: { /* updated definition */ }, + operation: "update" + }) +} +``` + +## Scope-Specific Tool Behavior Examples + +This section provides concrete examples of how tools behave differently across scopes. + +### Example 1: Resource Management Across Scopes + +```typescript +// In org scope (/:org/settings) +await decopilot.invokeTool("resource_edit", { + uri: "org://acme-corp/security-policy", + name: "Security Policy", + content: "# Security Policy\n\nAll code must be reviewed for security issues.", + operation: "create" +}) +// Creates resource in org virtual MCP (available to all projects) + +// In project scope (/:org/projects/mobile-app) +await decopilot.invokeTool("resource_edit", { + uri: "project://mobile-app/architecture", + name: "Mobile Architecture", + content: "# Architecture\n\nMobile app uses React Native with...", + operation: "create" +}) +// Creates resource in project virtual MCP (available only to this project) + +// Reading resources with inheritance +const securityPolicy = await decopilot.invokeTool("resource_read", { + uri: "org://acme-corp/security-policy" +}) +// Works from any scope (org, project, or agent) via inheritance +``` + +### Example 2: Tool Discovery by Scope + +```typescript +// In org scope: lists org-wide tools +const orgTools = await decopilot.invokeTool("tools_search", {}) +// Returns: ["ORG_CONNECTION_CREATE", "ORG_RESOURCE_CREATE", ...] + +// In project scope: lists project + org + connected external tools +const projectTools = await decopilot.invokeTool("tools_search", {}) +// Returns: ["CREATE_PR", "DEPLOY_STAGING", "ORG_RESOURCE_CREATE", ...] + +// In agent scope: lists bounded agent tools + inherited tools +const agentTools = await decopilot.invokeTool("tools_search", {}) +// Returns: ["SECURITY_SCAN", "CVE_LOOKUP", "ORG_RESOURCE_CREATE", ...] +``` + +### Example 3: Prompt Templates by Scope + +```typescript +// Create org-level prompt (available to all projects) +await decopilot.invokeTool("prompt_edit", { + name: "code-review-checklist", + description: "Standard code review checklist", + template: "## Code Review\n\n- [ ] Security reviewed\n- [ ] Tests added\n- [ ] Docs updated", + operation: "create" +}) + +// Create project-level prompt (overrides org for this project) +await decopilot.invokeTool("prompt_edit", { + name: "code-review-checklist", + description: "Mobile-specific code review checklist", + template: "## Mobile Code Review\n\n- [ ] iOS tested\n- [ ] Android tested\n- [ ] Security reviewed", + operation: "create" +}) + +// Reading prompts respects scope hierarchy +const prompt = await decopilot.invokeTool("prompt_read", { + name: "code-review-checklist" +}) +// In project scope: returns project-specific version +// In org scope: returns org-level version +``` + +## Tool Availability by Task Type + +Tool availability varies depending on whether the task is user-initiated (top-level) or agent-spawned (child). + +### Top-Level Tasks (User-Initiated) + +Top-level tasks have full tool access: + +- All built-in tools available (including `user_ask_question` and `agent_spawn`) +- Can discover and enable target virtual MCP tools +- Can spawn child tasks via `agent_spawn` +- Can ask user questions via `user_ask_question` + +```typescript +// Top-level task can use all tools +await decopilot.invokeTool("user_ask_question", { + question: "Deploy to production?" +}) +// Works in top-level tasks + +await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer-001", + prompt: "Review authentication code" +}) +// Works in top-level tasks +``` + +### Child Tasks (Agent-Spawned) + +Child tasks have restricted tool access: + +- Most built-in tools available +- **`user_ask_question` DISABLED** (cannot ask user questions) +- **`agent_spawn` DISABLED by default** (prevents infinite spawning) +- Can discover and enable target virtual MCP tools +- Can spawn grandchild tasks if explicitly enabled + +```typescript +// Child task (agent-spawned) +await decopilot.invokeTool("user_ask_question", { + question: "Deploy to production?" +}) +// Throws error: "user_ask_question not available in child tasks" + +await decopilot.invokeTool("agent_spawn", { + agent_id: "another-agent", + prompt: "Do more work" +}) +// Throws error: "agent_spawn disabled in child tasks" (unless explicitly enabled) + +// But can still use other built-in tools +await decopilot.invokeTool("resource_read", { + uri: "project://mobile-app/architecture" +}) +// Works in child tasks + +await decopilot.invokeTool("tools_search", { + search_term: "security" +}) +// Works in child tasks +``` + +### Task State Transitions + +Tasks transition through states based on execution and completion detection: + +**Active**: Task is currently being processed by decopilot or an agent. + +**Needs Input**: Task requires user input. Triggered by `user_ask_question` or when a cheap model determines additional input is required. + +**Successful**: Task completed successfully. Determined by cheap model checking conversation history and tool invocations. + +**Failed**: Task encountered an error that prevents completion. + +```typescript +// Task state example +const task = { + taskId: "task-001", + status: "active", // Initial state when task starts + + // After user_ask_question is called + status: "needs_input", + + // After user responds and work completes + status: "successful", + + // Or if error occurs + status: "failed" +} +``` + +## Tool Specification Format + +All tools (built-in and target virtual MCP) follow a consistent specification format: + +```typescript +interface ToolSpecification { + name: string // Tool name (UPPERCASE_SNAKE_CASE convention) + description: string // What the tool does + inputSchema: object // JSON Schema for input validation + outputSchema: object // JSON Schema for output validation + handler?: Function // Tool implementation (inline tools only) + source: "inline" | "external" // Whether tool is inline or from external MCP +} +``` + +### Input Schema + +Input schemas use JSON Schema Draft 7: + +```typescript +{ + type: "object", + properties: { + param1: { + type: "string", + description: "Parameter description" + }, + param2: { + type: "number", + description: "Another parameter" + } + }, + required: ["param1"] // Required parameters +} +``` + +### Output Schema + +Output schemas define expected return values: + +```typescript +{ + type: "object", + properties: { + result: { + type: "string", + description: "Result description" + }, + success: { + type: "boolean", + description: "Whether operation succeeded" + } + }, + required: ["success"] +} +``` + +### Example Complete Specification + +```typescript +const DEPLOY_STAGING_TOOL = { + name: "DEPLOY_STAGING", + description: "Deploy the application to staging environment", + inputSchema: { + type: "object", + properties: { + branch: { + type: "string", + description: "Git branch to deploy" + }, + runTests: { + type: "boolean", + description: "Whether to run tests before deployment", + default: true + } + }, + required: ["branch"] + }, + outputSchema: { + type: "object", + properties: { + deploymentUrl: { + type: "string", + description: "URL of the deployed application" + }, + success: { + type: "boolean", + description: "Whether deployment succeeded" + } + }, + required: ["success"] + }, + source: "inline", + handler: async (input) => { + // Tool implementation + } +} +``` + +## Key Takeaways + +**Two tool categories**: Built-in tools (always available) and target virtual MCP tools (must be discovered and enabled). + +**Scope-sensitive behavior**: Built-in tools that operate on virtual MCPs adapt automatically based on org/project/agent scope. + +**Discovery and enablement**: Target virtual MCP tools require `tools_search` to discover and `tool_enable` to activate before use. + +**Task type restrictions**: Top-level tasks have full tool access; child tasks have `user_ask_question` and `agent_spawn` disabled. + +**Scope inheritance**: Resources, prompts, and tools inherit from parent scopes, enabling reuse and consistency. + +**External vs inline**: External MCP tools are read-only; inline tools can be modified via `tools_edit`. + +Understanding these concepts is essential for working effectively with decopilot—tools are the mechanism through which decopilot interacts with virtual MCPs and accomplishes work. + +--- + +**Ready to dive deeper?** Explore [Scopes](/en/mcp-mesh/decopilot/scopes) to understand scope-based routing, [Architecture](/en/mcp-mesh/decopilot/architecture) for implementation details, or [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to understand the foundation layer. From 88ec04aade05aeeb26a2a75a10e574a8a6476095 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 17:52:42 -0300 Subject: [PATCH 12/51] docs: document decopilot agent spawning mechanism Create mcp-mesh/decopilot/spawning-agents.mdx explaining how decopilot spawns agents as tasks using agent_spawn tool. Key content: - Task spawning overview and benefits (parallel execution, context isolation) - Tasks vs threads terminology (UI uses "tasks", codebase uses "threads") - agent_spawn tool signature and behavior - Task states and lifecycle (Active, Needs Input, Successful, Failed) - Task variants: top-level vs child (tool availability differences) - Context isolation and inheritance patterns - Agent selection and discovery using agent_search - UI integration and task management - Spawning workflows: single, parallel, sequential patterns - Best practices for effective agent spawning Includes 7 code examples demonstrating: - agent_spawn usage with explicit task_id return - agent_search for discovering agents - Handling "Needs Input" state transitions - Single, parallel, and sequential spawning patterns Closes beads-main-iuu Co-Authored-By: Claude Sonnet 4.5 --- .../en/mcp-mesh/decopilot/spawning-agents.mdx | 223 ++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx new file mode 100644 index 0000000000..341bc78d76 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx @@ -0,0 +1,223 @@ +--- +title: Spawning Agents +description: How decopilot spawns agents as tasks for parallel execution and context isolation +icon: Layers +--- + +import Callout from "../../../../components/ui/Callout.astro"; + + + This page documents the **planned architecture** for agent spawning in decopilot. The implementation is in development. + + +## What is Agent Spawning? + +Agent spawning creates isolated tasks with specialized agents to accomplish specific work. Decopilot creates a new task with fresh context, delegates work, and integrates results when complete. + +Think of spawning as delegating to focused specialists. Decopilot breaks work into focused tasks, spawns agents for each piece, and orchestrates results. + +A **task** is an isolated chat session with a specific agent. The codebase uses "threads" internally, but UI and documentation use "tasks." Future versions will unify terminology. + +Learn more in [Agents](/en/mcp-mesh/agents) and [Virtual MCPs](/en/mcp-mesh/virtual-mcps). + +## Benefits of Task Spawning + +**Parallel execution**: Spawn multiple agents for independent work simultaneously. + +**Context isolation**: Each task gets fresh context focused on its objective. Parent context doesn't pollute child tasks. + +**Focused capabilities**: Agents have bounded tool access appropriate to their purpose. + +**Efficient token usage**: Fresh context means minimal overhead. Results integrate as summaries. + +**Composable workflows**: Break complex work into focused steps handled by specialized agents. + +## Understanding Tasks vs Threads + +The codebase uses "threads" for what users see as "tasks." This terminology will converge with "tasks" becoming consistent throughout. + +**For users**: Think "tasks"—the UI shows tasks. + +**For developers**: Currently "threads" in code, transitioning to "tasks." + +Spawned agents create child tasks with limited context inheritance. + +## How agent_spawn Works + +The `agent_spawn` tool creates a new task with a specified agent and prompt. + +**Signature**: `agent_spawn(agent_id: string, prompt: string): task_id: string` + +**Behavior**: Creates new task with agent's [virtual MCP](/en/mcp-mesh/virtual-mcps), passes prompt as initial message, parent continues immediately. + +```typescript +const taskId = await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer-001", + prompt: "Review src/auth/login.ts for vulnerabilities." +}) +``` + +The spawned task runs independently. Parent doesn't block—results return when task completes. + +## Task States and Lifecycle + +**Active**: Task being processed by agent. + +**Needs Input**: Requires user input to continue (via `user_ask` tool or cheap model determination). + +**Successful**: Task completed. Cheap model detects completion criteria. + +**Failed**: Encountered error preventing completion. + +```typescript +const taskId = await decopilot.invokeTool("agent_spawn", { + agent_id: "research-agent", + prompt: "Analyze architecture" +}) +// Active -> needs_input (if user_ask) -> active -> successful +``` + +Handle `needs_input` state by providing input via task UI: + +```typescript +// Task calls user_ask -> needs_input state +// Navigate to task, provide input +// Task resumes -> active state +``` + +## Task Variants: Top-level vs Child + +**Top-level tasks** are user-initiated with full tool access: +- `user_ask` available +- `agent_spawn` available +- Full access to built-in and virtual MCP tools + +**Child tasks** are agent-spawned with restrictions: +- `user_ask` disabled (prevents blocking on input) +- `agent_spawn` disabled by default (prevents deep nesting) +- Access to other tools + +Child tasks work with provided information, return partial results if clarification needed, or fail gracefully. The parent calls `user_ask` and re-spawns with additional context. + +This maintains flat hierarchy: top-level spawns children, children return results, top-level coordinates. + +## Context Isolation and Inheritance + +Spawned tasks receive isolated context with selective inheritance. + +**Spawned agents receive**: +- System instructions +- CLAUDE.md (org/project rules) +- AGENTS.md (agent-specific instructions) +- Task prompt +- Filtered tools + +**Spawned agents do NOT receive**: +- Parent conversation history +- Parent-loaded resources +- Parent context accumulation + +Results integrate as 200-500 token summaries. See [Context Management](/en/mcp-mesh/decopilot/context-management) for details. + +## Agent Selection and Discovery + +The `agent_search` tool discovers available agents. + +**Signature**: `agent_search(search_term?: string): Agent[]` + +**Output**: List with `agent_id`, `name`, `purpose`, `capabilities`. + +```typescript +const result = await decopilot.invokeTool("agent_search", { + search_term: "security" +}) +``` + +Specialized agents optimize for their purpose and produce better results. + +## UI Integration and Task Management + +**Tasks menu**: Shows all tasks for current scope with status indicators. + +**Task list view**: Displays tasks with active/needs input/successful/failed indicators. + +**Task detail view**: Full conversation history with chat interface (top-level) or read-only view (child). + +**Notifications**: Badge counts and toasts for state changes. + +Monitor multiple agents, respond when needed, review results when complete. + +## Spawning Workflows + +### Single Task Spawn + +Spawn one agent for focused work on a single objective. + +```typescript +const taskId = await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer-001", + prompt: "Review auth files for vulnerabilities. Report with severity levels." +}) +``` + +### Parallel Task Spawning + +Spawn multiple agents simultaneously for independent work that can run concurrently. + +```typescript +const archTaskId = await decopilot.invokeTool("agent_spawn", { + agent_id: "research-agent-001", + prompt: "Analyze architecture patterns." +}) + +const secTaskId = await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer-001", + prompt: "Perform security audit." +}) +``` + +### Sequential Workflow + +Spawn agents in sequence where each task depends on previous results. + +```typescript +// Research options +const researchTaskId = await decopilot.invokeTool("agent_spawn", { + agent_id: "research-agent-001", + prompt: "Research React state libraries." +}) + +// Implement chosen solution +const devTaskId = await decopilot.invokeTool("agent_spawn", { + agent_id: "development-agent-001", + prompt: "Implement Zustand store." +}) + +// Test implementation +const testTaskId = await decopilot.invokeTool("agent_spawn", { + agent_id: "testing-agent-001", + prompt: "Write tests for store." +}) +``` + +## Best Practices + +**Choose appropriate agents**: Match agent capabilities to task requirements. Specialized agents produce better results. + +**Clear prompts**: Include context, specific files, focus areas, and success criteria. + +**Parallel spawning**: Use for independent work to maximize throughput. + +**Monitor states**: Check tasks menu, respond to "Needs Input" promptly. + +**Handle failures**: Review errors, adjust approach, re-spawn with corrections. + +**Focused objectives**: One clear goal per spawned task. + +**Leverage inheritance**: Tasks inherit org/project context automatically. + +**Validate results**: Successful completion doesn't guarantee correctness. + +--- + +**Ready to start?** See [Tools](/en/mcp-mesh/decopilot/tools) for agent_spawn details, [Context Management](/en/mcp-mesh/decopilot/context-management) for isolation mechanics, or [Scopes](/en/mcp-mesh/decopilot/scopes) for scope effects. From 22eb64e86cf5d9df7cfaef980cb48f44fbe915b3 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 21:00:27 -0300 Subject: [PATCH 13/51] docs: restructure agents.mdx to match projects.mdx concise style Restructure agents documentation for consistency and scannability: - Reduce agents.mdx from 490 to 88 lines, matching projects.mdx style - Move "Agents vs. Projects" comparison to concepts.mdx as foundational context - Remove detailed composition examples, AGENTS.md config, and agent types - Keep focus on essential information: what agents are, how they work, and when to use them - Maintain all cross-references (7 page-level links remain valid) Both projects.mdx and agents.mdx now follow parallel structure with clear, scannable sections. Co-Authored-By: Claude Sonnet 4.5 --- .../client/src/content/en/mcp-mesh/agents.mdx | 480 ++---------------- .../src/content/en/mcp-mesh/concepts.mdx | 159 +++++- .../src/content/en/mcp-mesh/virtual-mcps.mdx | 288 +++++------ 3 files changed, 319 insertions(+), 608 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx index 551efe8d91..75484bdaec 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx @@ -12,479 +12,77 @@ import Callout from "../../../components/ui/Callout.astro"; ## What Are Agents? -**Agents** are single-purpose virtual MCPs optimized for specific tasks. While [Projects](/en/mcp-mesh/projects) provide general-purpose, project-level work environments, agents are narrowly focused on accomplishing one thing well. +**Agents** are single-purpose virtual MCPs optimized for specific tasks. While [Projects](/en/mcp-mesh/projects) provide general-purpose work environments, agents focus narrowly on accomplishing one thing well. -An agent is a complete virtual MCP with its own: +Agents are built on the [Virtual MCP](/en/mcp-mesh/virtual-mcps) foundation—they ARE virtual MCPs with their own tools, resources, prompts, and configuration. This makes agents first-class participants in your MCP ecosystem, exposing capabilities through standard MCP protocol endpoints at `/:org/agents/:agent_id`. -- **Tools**: Curated for the agent's specific purpose -- **Resources**: Context and documentation relevant to the task -- **Prompts**: Templates tailored to the agent's workflow -- **Configuration**: Agent-specific settings and constraints +The key distinction: projects organize capabilities for broad work contexts, while agents optimize for single-purpose execution. -Agents are built on the [Virtual MCP](/en/mcp-mesh/virtual-mcps) foundation—they ARE virtual MCPs, not just connections to them. This means agents can expose tools, resources, and prompts through the MCP protocol, making them first-class participants in your MCP ecosystem. +## How Agents Work -## Agents vs. Projects +Create an agent by defining its purpose and curating its capabilities: -Understanding the distinction between agents and projects is key: +1. **Name** - Identifies the agent (e.g., "Deployment Agent", "Research Agent") +2. **Purpose** - Clear statement of what the agent does (e.g., "Deploy applications to production") +3. **Tools** - Actions the agent can take (select from [connections](/en/mcp-mesh/connections) or define inline) +4. **Resources** - Context and guidelines specific to the agent's task +5. **Prompts** - Templates tailored to the agent's workflow -**Projects** are general-purpose organizational units for ongoing work: -- Broad scope covering multiple workflows -- Long-lived, evolving over time -- Team collaboration hub -- Example: "Mobile App Rewrite" project with design, development, and deployment tools +Since agents are [Virtual MCPs](/en/mcp-mesh/virtual-mcps), you can compose them from existing connections, define capabilities inline, or mix both approaches. The agent's configuration determines what it can do and how it operates. -**Agents** are single-purpose virtual MCPs for specific tasks: -- Narrow scope with clear, focused objective -- Designed for particular operations -- Can be spawned on-demand with fresh context -- Example: "Agent Management Agent" that only creates/edits/deletes agents +## Example: Production Deployment Agent -## Agents as Virtual MCPs - -Because agents are virtual MCPs, they have the same capabilities and configuration options as any virtual MCP. Each agent: - -- Exposes a unique MCP-compliant endpoint at `/:org/agents/:agent_id` -- Can aggregate tools from multiple connections (composition) -- Can define inline resources, prompts, and tools -- Can be configured and updated dynamically -- Operates within its defined scope and boundaries - -```typescript -// Example: Research agent configuration -{ - "agentId": "research-agent-001", - "name": "Codebase Research Agent", - "purpose": "Explore and analyze codebase structure", - "connections": [ - { - "connectionId": "github-conn-123", - "tools": ["LIST_FILES", "READ_FILE", "SEARCH_CODE"] - }, - { - "connectionId": "docs-conn-456", - "tools": ["SEARCH_DOCS", "GET_API_REFERENCE"] - } - ], - "prompts": [ - { - "name": "analyze-architecture", - "description": "Analyze codebase architecture patterns", - "template": "Analyze the architecture of:\n{{filepath}}\n\nFocus on:\n- Design patterns\n- Dependencies\n- Module organization" - } - ], - "resources": [ - { - "uri": "agent://research-agent-001/guidelines", - "name": "Research Guidelines", - "mimeType": "text/markdown", - "content": "# Research Guidelines\n\n- Read-only operations\n- Document findings clearly\n- Focus on structure and patterns" - } - ] -} -``` - -## Creating Agents - -Agents are created similarly to projects, with configuration determining their behavior. The key is defining a clear, single purpose for the agent. - -### Composition Mode - -Mix tools from multiple existing connections: - -```typescript -// Deployment agent using composition -{ - "agentId": "deployment-agent-001", - "name": "Production Deployment Agent", - "purpose": "Deploy applications to production", - "connections": [ - { - "connectionId": "github-conn-123", - "tools": ["CREATE_TAG", "MERGE_PR", "CREATE_RELEASE"] - }, - { - "connectionId": "slack-conn-456", - "tools": ["POST_MESSAGE"] - }, - { - "connectionId": "monitoring-conn-789", - "tools": ["CHECK_HEALTH", "GET_METRICS"] - } - ] -} -``` - -### Inline Mode - -Define agent capabilities directly within MCP Mesh: - -```typescript -// Testing agent with inline prompts -{ - "agentId": "testing-agent-001", - "name": "Test Analysis Agent", - "purpose": "Analyze test coverage and quality", - "prompts": [ - { - "name": "coverage-report", - "description": "Generate test coverage analysis", - "template": "Analyze test coverage for:\n{{files}}\n\nReport:\n- Coverage percentage\n- Untested paths\n- Recommendations" - }, - { - "name": "test-quality", - "description": "Assess test quality", - "template": "Review test quality:\n{{test_files}}\n\nCheck for:\n- Clear assertions\n- Edge cases\n- Maintainability" - } - ] -} -``` - -### Hybrid Mode - -Combine external tools with inline configuration: - -```typescript -// Development agent mixing both approaches -{ - "agentId": "dev-agent-001", - "name": "Development Assistant Agent", - "purpose": "Assist with feature development", - "connections": [ - { - "connectionId": "github-conn-123", - "tools": ["CREATE_BRANCH", "CREATE_PR", "LIST_ISSUES"] - } - ], - "prompts": [ - { - "name": "feature-pr-template", - "description": "Generate feature PR description", - "template": "Create PR for feature:\n{{feature_name}}\n\nInclude:\n- Summary\n- Testing checklist\n- Breaking changes" - } - ], - "resources": [ - { - "uri": "agent://dev-agent-001/workflow", - "name": "Development Workflow", - "mimeType": "text/markdown", - "content": "# Development Workflow\n\n1. Create feature branch\n2. Implement changes\n3. Write tests\n4. Create PR with checklist" - } - ] -} -``` - -## Agent Configuration - -Agents support the same configuration capabilities as virtual MCPs, plus agent-specific features. - -### AGENTS.md Support - -Each agent can have an `AGENTS.md` file that provides context and instructions specific to that agent's purpose. This file is loaded into the agent's context and guides its behavior. - -```markdown -# Research Agent Instructions - -## Purpose -Explore and analyze codebases for architectural patterns and structure. - -## Constraints -- Read-only operations only -- Document all findings -- Focus on high-level patterns, not implementation details - -## Workflow -1. Start with entry points (main files, index files) -2. Map module dependencies -3. Identify design patterns -4. Document architectural decisions -``` - -### Tool Selection - -Choose tools that align with the agent's purpose. Overly broad tool access dilutes the agent's focus. - -**Good**: Research agent with read-only tools -**Bad**: Research agent with write, deploy, and admin tools - -### Resource Configuration - -Provide resources that give the agent domain-specific context: - -- Guidelines specific to the agent's task -- Templates for common outputs -- Reference documentation -- Domain knowledge +A deployment agent might aggregate GitHub tools for tagging and releases, Slack tools for notifications, and monitoring tools for health checks. The agent handles production deployments with a focused toolset—create tags, merge PRs, post deployment notifications, verify health—all within its single-purpose scope. ## Built-in Agents -MCP Mesh includes several built-in agents for common mesh operations. These agents use the **Mesh MCP**—a self-referential MCP that exposes mesh management capabilities through the MCP protocol. - -### The Mesh MCP - -The Mesh MCP is a powerful concept: **mesh has an MCP for managing itself**. This MCP provides tools for: - -- Managing agents (create, edit, delete) -- Managing connections (add, remove, configure) -- Managing permissions (roles, access control) -- Managing users (invite, remove) -- Installing MCPs from the store - -Built-in agents leverage these mesh MCP tools, which are available in the organization's virtual MCP at the org-admin level. - -### Agent Management Agent - -**Purpose**: Create, edit, and delete agents - -**Tools**: Agent CRUD operations from mesh MCP - -**Use cases**: -- "Create a new research agent for analyzing this codebase" -- "Edit the deployment agent to add database migration tools" -- "Delete the testing agent that's no longer needed" - -**Scope**: Organization-level operations - -**How it works**: Uses mesh MCP tools (`CREATE_AGENT`, `UPDATE_AGENT`, `DELETE_AGENT`) to manage agents. The agent has access to the org's virtual MCP at admin level, allowing it to perform agent management operations. - -```typescript -// Example: Using agent management agent -{ - "agentId": "agent-manager-001", - "name": "Agent Management Agent", - "purpose": "Manage agent lifecycle", - "connections": [ - { - "connectionId": "mesh-mcp-conn", - "tools": ["CREATE_AGENT", "UPDATE_AGENT", "DELETE_AGENT", "LIST_AGENTS"] - } - ], - "prompts": [ - { - "name": "create-agent-from-description", - "description": "Create agent from natural language description", - "template": "Create an agent for: {{description}}\n\nDetermine:\n- Agent name and purpose\n- Required tools\n- Relevant prompts and resources" - } - ] -} -``` - -### Connection Management Agent - -**Purpose**: Manage MCP connections - -**Tools**: Connection management from mesh MCP - -**Use cases**: -- "Connect to the GitHub MCP server with these credentials" -- "Remove the unused Slack connection" -- "Update authentication settings for the database MCP" - -**Scope**: Organization-level operations - -**How it works**: Uses mesh MCP tools (`CREATE_CONNECTION`, `UPDATE_CONNECTION`, `DELETE_CONNECTION`) to manage connections in the organization. - -### Permission Management Agent - -**Purpose**: Manage permissions and access control - -**Tools**: Permission management from mesh MCP - -**Use cases**: -- "Grant developer role to this user" -- "Restrict access to production connections" -- "Update permissions for the deployment agent" - -**Scope**: Organization-level operations - -**How it works**: Uses mesh MCP tools for permission management (`GRANT_PERMISSION`, `REVOKE_PERMISSION`, `LIST_PERMISSIONS`) to control access within the organization. - -### MCP Store Agent - -**Purpose**: Install and manage MCPs from the store - -**Tools**: Store browsing and MCP installation from mesh MCP +MCP Mesh includes built-in agents for common mesh operations. These agents use the **Mesh MCP**—a self-referential MCP that exposes mesh management capabilities through the MCP protocol. -**Use cases**: -- "Install the GitHub MCP from the store" -- "Browse available database integration MCPs" -- "Update the Slack MCP to the latest version" +Built-in agents available out-of-the-box: -**Scope**: Organization-level operations +- **Agent Management** - Create, edit, and delete agents +- **Connection Management** - Manage MCP server connections +- **Permission Management** - Control access and authorization +- **MCP Store** - Browse and install MCPs from the store +- **User Management** - Invite and manage organization members -**How it works**: Uses mesh MCP tools (`BROWSE_STORE`, `INSTALL_MCP`, `UPDATE_MCP`) to interact with the MCP store and install servers. +These agents operate at organization level and leverage mesh MCP tools for platform configuration. -### User Management Agent +## Agent Design Principles -**Purpose**: Invite and manage organization users +**Single-purpose focus**: Each agent should do one thing well. Narrow scope improves clarity, reliability, and maintainability. -**Tools**: User management from mesh MCP - -**Use cases**: -- "Invite a new developer to the organization" -- "Remove user access for this email" -- "Update user roles and permissions" - -**Scope**: Organization-level operations - -**How it works**: Uses mesh MCP tools (`INVITE_USER`, `REMOVE_USER`, `UPDATE_USER_ROLE`) to manage organization membership. - -### Characteristics of Built-in Agents - -Built-in agents share common characteristics: - -- **Use org's virtual MCP**: Access mesh MCP tools at org-admin level -- **Pre-configured**: Tools, prompts, and resources tailored for specific mesh operations -- **Available out-of-the-box**: No setup required, ready to use immediately -- **Customizable**: Can be modified or used as templates for custom agents -- **Org-level scope**: Operate at organization level, not project or agent scope - -Built-in agents make mesh operations accessible through the same MCP interface used for application development, creating a consistent experience. - -## Agent Types and Patterns - -Common agent patterns emerge based on purpose: - -### Research Agents - -**Focus**: Exploration and analysis - -**Tools**: Read-only operations, search, documentation access - -**Example**: Codebase architecture analysis agent - -**Characteristics**: -- No write or mutating operations -- Comprehensive read access -- Documentation and analysis prompts - -### Development Agents - -**Focus**: Building and implementing features - -**Tools**: Full read/write access, branching, committing, testing - -**Example**: Feature implementation agent - -**Characteristics**: -- Code modification tools -- Git operations -- Testing and validation tools - -### Testing Agents - -**Focus**: Verification and validation - -**Tools**: Test execution, coverage analysis, quality checks - -**Example**: Test coverage agent - -**Characteristics**: -- Testing framework tools -- Coverage reporting -- Quality metrics - -### Deployment Agents - -**Focus**: Operations and releases - -**Tools**: Deployment commands, monitoring, rollback - -**Example**: Production deployment agent - -**Characteristics**: -- Production access (carefully scoped) -- Deployment and rollback tools -- Health check and monitoring - -### Custom Agents - -**Focus**: Domain-specific tasks - -**Tools**: Tailored to specific use case - -**Example**: Customer support agent with CRM and ticket tools - -**Characteristics**: -- Highly specialized toolset -- Domain-specific prompts and resources -- Often combines multiple systems - -## Single-Purpose Design Principle - -The power of agents comes from their focused design. An agent should do one thing well. - -### Why Single-Purpose? - -**Clarity**: The agent's purpose is immediately clear -**Reliability**: Narrow scope reduces unexpected behavior -**Maintainability**: Simpler to update and debug -**Reusability**: Single-purpose agents compose better - -### Good vs. Overly Broad - -**Good**: "Agent Management Agent" (creates/edits/deletes agents) -**Too broad**: "Mesh Admin Agent" (manages agents, connections, permissions, users, billing, settings...) - -**Good**: "Production Deployment Agent" (deploys to production) -**Too broad**: "DevOps Agent" (deploys, monitors, manages infrastructure, handles incidents...) - -### Defining Clear Purpose - -When creating an agent, start with a purpose statement: - -``` -Purpose: [Verb] + [Object] + [Context] - -Examples: +**Clear purpose statement**: Define agents with `[Verb] + [Object] + [Context]` pattern: - "Deploy applications to production environments" - "Analyze test coverage for code quality" -- "Research codebase architecture patterns" - "Manage agent lifecycle in the organization" -``` - -A clear purpose guides tool selection, resource configuration, and prompt design. - -## Agent Scope -When working within an agent, you operate in **agent scope**. The agent's route determines this: +**Tool selection**: Choose tools that align with the agent's purpose. A research agent needs read-only tools; a deployment agent needs release and notification tools. Overly broad tool access dilutes focus. -``` -/:org/agents/:agent_id -``` - -In agent scope: -- Tools are limited to those configured for the agent -- Resources are agent-specific plus organization-level -- Prompts are tailored to the agent's purpose -- Operations are bounded by the agent's capabilities - -For more details on how scopes work, see the decopilot documentation on [Scopes](/en/mcp-mesh/decopilot/scopes). +**Good**: "Deployment Agent" (deploys to production) +**Too broad**: "DevOps Agent" (deploys, monitors, manages infrastructure, handles incidents...) ## Using Agents Agents can be used in several ways: -**Spawned by decopilot**: When working in decopilot, agents can be spawned on-demand with fresh context. - -**Built-in agents**: Use pre-configured agents for common mesh operations without any setup. - -**Custom agents**: Create domain-specific agents for your team's unique workflows. - -**Direct connection**: Connect MCP clients directly to agent endpoints for focused work sessions. +- **Spawned by decopilot** - Agents spawned on-demand with fresh context for specific tasks +- **Built-in agents** - Pre-configured agents for mesh operations, ready immediately +- **Custom agents** - Domain-specific agents for your team's unique workflows +- **Direct connection** - Connect MCP clients to agent endpoints for focused sessions -Agents provide focused capabilities with fresh context, making them ideal for specific, well-defined tasks. +When working within an agent, you operate in **agent scope**—tools, resources, and prompts are limited to those configured for the agent. Operations are bounded by the agent's capabilities. ## Benefits Summary -Agents bring several advantages: +Agents provide focused capabilities with clear advantages: -- **Focused capabilities**: Single-purpose design ensures clarity and reliability -- **Fresh context**: Spawned agents start with clean context for their specific task -- **Reusable patterns**: Define once, use across projects and workflows -- **Built-in operations**: Pre-configured agents for common mesh tasks -- **Composable design**: Combine multiple agents for complex workflows -- **Self-referential management**: Mesh MCP enables agents to manage mesh itself +- **Focused capabilities** - Single-purpose design ensures clarity and reliability +- **Fresh context** - Spawned agents start with clean context for their task +- **Reusable patterns** - Define once, use across projects and workflows +- **Built-in operations** - Pre-configured agents for common mesh tasks +- **Self-referential management** - Mesh MCP enables agents to manage mesh itself --- -**Ready to create your first agent?** Start by understanding [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to grasp the foundation, then explore built-in agents to see common patterns. +**Next steps**: Learn about [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to understand the foundation, or explore [decopilot](/en/mcp-mesh/decopilot/overview) to see how agents are spawned dynamically. diff --git a/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx b/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx index 4f54fa7627..c20b76b0ce 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx @@ -1,6 +1,6 @@ --- title: Concepts -description: The mental model for organizations, connections, agents, API keys, and tool calls +description: The foundational concepts that power decocms icon: BookOpen --- @@ -9,23 +9,158 @@ icon: BookOpen - **Organization**: the top-level tenant boundary. Everything (connections, agents, logs) is org-scoped. - **Members**: users invited into an organization. - **Roles**: role assignments for members, used by access control checks. -- **Connection**: a configured upstream MCP endpoint (usually HTTP), optionally with stored credentials. -- **Agent**: a virtual MCP server that aggregates multiple connections into a single MCP surface. -- **Tool call**: a `tools/call` request routed through the Mesh to a downstream MCP server (or via an agent). -- **Monitoring log**: a record of a tool call (inputs, outputs, duration, error), used for debugging and ops. +- **Connection**: a configured upstream MCP endpoint (usually HTTP), optionally with stored credentials. See [Connections](/en/mcp-mesh/connections). +- **Virtual MCP**: aggregates tools/resources/prompts from connected servers into a single MCP. See [Virtual MCPs](/en/mcp-mesh/virtual-mcps). +- **Agent**: single purpose virtual MCPs optimized for specific tasks. See [Agents](/en/mcp-mesh/agents). +- **Project**: virtual MCP to organize project specifics like available tools, resources, prompts and config. See [Projects](/en/mcp-mesh/projects). +- **Monitoring**: decocms built-in monitoring lets you see and replay past tool invocations. + +## Understanding Agents vs. Projects + +Both agents and projects are Virtual MCPs, but they serve different purposes in your workflow: + +**Projects** are general-purpose organizational units for ongoing work: +- **Broad scope** - Cover multiple workflows and capabilities within a work context +- **Long-lived** - Evolve over time as work progresses +- **Team collaboration** - Shared workspace for team members +- **Example** - "Mobile App Rewrite" project with design, development, and deployment tools +- **When to use** - Organizing work by product line, client, team, or initiative + +**Agents** are single-purpose virtual MCPs for specific tasks: +- **Narrow scope** - Clear, focused objective with curated toolset +- **Task-specific** - Designed for particular operations or workflows +- **Fresh context** - Can be spawned on-demand with clean context +- **Example** - "Agent Management Agent" that only creates/edits/deletes agents +- **When to use** - Focused operations, built-in mesh management, or specialized workflows + +Both follow the same Virtual MCP architecture, but their design principles differ: projects organize capabilities for broad work contexts, while agents optimize for single-purpose execution. + +## MCP Protocol Primitives + +decocms is fully [MCP compliant](https://modelcontextprotocol.io/). The Model Context Protocol defines three core primitives: + +- **[Tools](https://modelcontextprotocol.io/docs/concepts/tools)**: Executable functions exposed by MCP servers that enable AI agents to take actions (create files, query databases, call APIs, etc.). +- **[Resources](https://modelcontextprotocol.io/docs/concepts/resources)**: Read-only data sources with URIs (like `org://`, `project://`, `agent://`) that provide context to AI agents. +- **[Prompts](https://modelcontextprotocol.io/docs/concepts/prompts)**: Reusable templates with variables for common workflows and operations. + +For the complete protocol architecture, see the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/concepts/architecture). ## Data and security boundaries - **Credential Vault**: sensitive connection credentials are encrypted at rest (vaulted) and only decrypted at request time. - **Permissions**: API keys are scoped to tool permissions; the Mesh enforces authorization before proxying. -## How requests flow +## How the Platform Works + +### The Control Plane Model + +decocms operates as a **control plane** sitting between MCP clients and MCP servers. This architectural pattern—borrowed from Kubernetes and modern infrastructure systems—separates: + +**The control plane** (decocms): Handles authentication, authorization, routing, credential management, and observability. + +**The data plane** (MCP servers): Executes actual operations (create GitHub PRs, query databases, send Slack messages). + +This separation enables centralized policy enforcement and observability without decocms needing to understand the semantics of every tool—it just routes MCP protocol messages securely. + +### Request Flow + +``` +┌─────────┐ ┌──────────┐ ┌────────────┐ +│ Client │ ──[authenticate]──▶│ decocms │ ──[with creds]──▶│ MCP Server │ +│ (Cursor)│ │ │ │ (GitHub) │ +└─────────┘ ◀──[response]──────└──────────┘ ◀─[response]─────└────────────┘ + │ + └──▶ [monitoring log] +``` + +1. **Client authenticates** to decocms (OAuth session or API key) +2. **Client makes request** to either: + - A specific **Connection** (direct proxy to one MCP server) + - An **Agent** or **Project** (Virtual MCP aggregating multiple connections) + - The **Management MCP** (decocms's own tools for platform configuration) +3. **decocms authorizes** the request against the client's permissions +4. **decocms loads credentials** from the encrypted vault for the target Connection(s) +5. **decocms proxies** the MCP protocol request to the upstream server(s) +6. **decocms logs** the invocation for monitoring and audit +7. **decocms returns** the response to the client + +This flow ensures clients never handle credentials directly, all access is authorized consistently, and every operation is observable. + +## Architectural Patterns + +### Multi-Tenancy Through Organizations + +Organizations provide the top-level isolation boundary. Everything in decocms is **organization-scoped**: + +- **Connections**: Each organization connects to MCP servers independently +- **Virtual MCPs**: Projects and Agents are organization-specific +- **Credentials**: Stored per-organization in isolated vaults +- **Members & Permissions**: Role assignments are organization-scoped +- **Monitoring logs**: Audit trails isolated per organization + +This multi-tenancy model enables: +- SaaS providers to serve multiple customers from one decocms instance +- Enterprises to separate departments or teams +- Agencies to isolate client workspaces + +### Composition Over Configuration + +decocms follows a **composition model** rather than requiring complex configuration: + +**Connect** individual MCP servers (GitHub, Slack, databases) +↓ +**Compose** them into Virtual MCPs with curated tool surfaces +↓ +**Organize** into Projects (for teams) and Agents (for specific tasks) +↓ +**Expose** through a single MCP-compliant endpoint + +This pattern enables building complex capabilities from simple, reusable components without infrastructure changes or deployments. + +### Security by Design + +**Credential isolation**: Credentials are encrypted at rest and only decrypted at request time. Clients never receive raw credentials—they authenticate to decocms, which handles credential management. + +**Least privilege**: API keys and permissions are scoped to specific tools. A key for "read GitHub issues" cannot create PRs or access Slack. + +**Audit everything**: Every tool invocation creates a monitoring log with tool name, inputs, outputs, duration, and caller identity. This audit trail is immutable and organization-scoped. + +**Zero trust**: Every request is authenticated and authorized, regardless of source. There's no "internal" vs "external" distinction—all access flows through the same authorization layer. + +## Design Decisions + +### Why Virtual MCPs Are Editable + +Traditional MCP servers expose a fixed set of tools defined in their code. decocms's Virtual MCPs are **editable at runtime** because they're configuration, not code. This enables: + +- **Dynamic tool surfaces**: Add or remove tools without deployments +- **Resource creation**: Generate documentation and context on the fly +- **Prompt evolution**: Update templates based on usage patterns +- **No-code workflows**: Non-developers can compose capabilities + +This editability is why Projects and Agents are Virtual MCPs—they need to evolve as work progresses. + +### Why Monitoring is Built-In + +In traditional MCP deployments, observability is an afterthought—each client logs independently (or not at all), and there's no unified view of tool usage. decocms makes monitoring **first-class** by logging every tool invocation that flows through the control plane. + +This built-in monitoring enables: +- **Debugging**: Trace failures across multiple MCP servers +- **Cost visibility**: See which tools are expensive or slow +- **Usage patterns**: Understand which capabilities teams actually use +- **Security audit**: Track who accessed what, when, and why + +Monitoring isn't optional—it's how the platform operates. + +### Why the MCP Protocol + +decocms could have invented its own protocol for agent-tool communication, but building on MCP provides: + +**Ecosystem compatibility**: Works with any MCP-compliant client (Claude Desktop, Cursor) and server +**Standard semantics**: Tools, Resources, and Prompts have well-defined meanings +**Open specification**: MCP is vendor-neutral and evolving through community input +**Network effects**: As the MCP ecosystem grows, decocms users benefit automatically -1. A client authenticates (OAuth session or API key). -2. The client calls either: - - the **Management MCP** (admin tools), or - - a **Proxy endpoint** (one connection), or - - an **Agent endpoint** (aggregated tools/resources/prompts). -3. The Mesh authorizes, loads credentials, proxies to the downstream Connection(s), and logs monitoring events. +By being "MCP-native," decocms becomes infrastructure for the broader ecosystem, not a proprietary silo. diff --git a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx index d535bbc306..a54f468aeb 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx @@ -1,175 +1,153 @@ --- title: Virtual MCPs -description: Create MCP servers on the spot without writing server code or managing infrastructure +description: Remix connections into reusable packages—select tools and context from multiple sources, add custom logic, and create purpose-built MCPs for your workflows icon: Waypoints --- import Callout from "../../../components/ui/Callout.astro"; -## MCP Compliance & Benefits +## What Are Virtual MCPs? -decocms is fully **MCP compliant**, following the Model Context Protocol specification. MCPs let AI agents work beyond your computer—acting on databases, APIs, SaaS tools, and production systems. MCP is a **protocol for action**, enabling agents to read, write, and orchestrate across your infrastructure. +In decocms, a **Virtual MCP** is a reusable package of capabilities—[tools, resources, and prompts](/en/mcp-mesh/concepts#mcp-protocol-primitives)—remixed from multiple [connections](/en/mcp-mesh/connections). -## The Challenge +Instead of giving your AI agent access to everything from every connection, you **compose virtual MCPs** that expose exactly what's needed for each use case. You can: -Creating traditional MCP servers requires writing server code, managing infrastructure, and maintaining updates—a barrier that prevents many teams from leveraging MCP's full potential. +- **Remix connections**: Select specific tools and context from each connection +- **Combine multiple sources**: Package GitHub + Slack + databases into one unified MCP +- **Add custom logic**: Extend with inline tools, prompts, and resources +- **Update dynamically**: Change what's included without reconfiguring your agents -## Virtual MCPs: The Solution +Virtual MCPs are the **backbone of decocms**—powering [Projects](/en/mcp-mesh/projects), [Agents](/en/mcp-mesh/agents), and organizational boundaries for how capabilities are packaged and composed. -**Virtual MCPs** are decocms's answer to this challenge. They let you **create MCP servers on the spot**, without writing server code or managing infrastructure. +## How Virtual MCPs Work -A Virtual MCP is a **virtual MCP server** that aggregates tools, resources, and prompts into a single MCP-compliant endpoint. Instead of writing and deploying server code, you configure what capabilities to expose—and decocms handles the rest. +Virtual MCPs are built by **remixing connections**—selecting capabilities from external MCPs—and optionally **extending with custom tools, prompts, and resources**. -Virtual MCPs are: +### Remix from Connections -- **Dynamically created**: spin up new MCPs through configuration, not code -- **Production-ready**: fully MCP-compliant endpoints that work with any MCP client -- **Instantly updated**: attach new tools or resources without redeploying servers -- **Foundation for advanced features**: the building block for agents and organizational tooling +**Remixing** lets you select and combine tools, resources, and prompts from multiple [connections](/en/mcp-mesh/connections). -## How Virtual MCPs Work +A **connection** is how you wire up an external MCP server to decocms (see [Connections](/en/mcp-mesh/connections) for details). Once you have connections set up, remixing works like this: + +1. **Select specific capabilities** from each connection—tools, resources, prompts +2. **Combine them** into a single virtual MCP package +3. **Your agent gets** aggregated access to all selected capabilities in one place + +**Example**: A "deployment-ops" virtual MCP might remix: +- **GitHub connection**: PR management tools + repository documentation +- **Slack connection**: Messaging and notification tools +- **Database connection**: Migration and schema tools + +Your AI agent uses this one virtual MCP to orchestrate across all three systems. + +### Extend with Inline Capabilities + +**Inline creation** lets you define tools, resources, and prompts directly within a virtual MCP—extending what connections provide. + +Inline tools can **call any MCP connection** available in your decocms instance, enabling powerful patterns like orchestration, validation, and feature gating. + +Inline tools can call other tools using `callTool(connectionId:TOOL_NAME, params)`, enabling orchestration, validation, and feature gating across your MCP infrastructure. + +This remixing approach is perfect for: + +- **Custom prompts** that guide agents through team-specific workflows +- **Context resources** like guidelines, documentation, or domain knowledge +- **Orchestration tools** that compose tools from multiple connections into higher-level operations +- **Feature gating and validation** that wrap connection tools with authorization logic (see [Authorization and Roles](/en/mcp-mesh/authorization-and-roles)) + +#### Use Case: Feature Gating + +Inline tools are ideal for **feature gating**—wrapping connection tools with validation, authorization, or custom behavior. + +**Example**: A read-only database tool that validates queries before calling the underlying connection, blocking dangerous operations like `DROP`, `DELETE`, or `UPDATE`. + +#### Use Case: Orchestration + +Inline tools can coordinate multiple connections in a single operation. + +**Example**: A deployment tool that runs tests (CI connection), merges a PR (GitHub connection), and notifies the team (Slack connection)—all in one coordinated workflow. + +These patterns enable **authorization enforcement**, **input validation**, **audit logging** (see [Monitoring](/en/mcp-mesh/monitoring)), and **workflow orchestration** across your MCP infrastructure. + +### Combine Both + +The real power comes from combining both approaches—remixing capabilities from connections and extending them with inline definitions. + +**Example**: A "development-assistant" virtual MCP that combines: +- **GitHub connection tools**: PR management, issue tracking +- **GitHub connection resources**: Repository contributing guide +- **Inline prompts**: Custom PR description templates for your team +- **Inline resources**: Team coding standards and style guides + +One virtual MCP, multiple sources (connections + inline definitions), unified agent experience. + +## Namespacing & Collision Avoidance -Virtual MCPs can be created in two fundamental ways, and you can mix both approaches as needed. - -### Approach 1: Composition (Mix Existing Connections) - -**Composition** lets you aggregate capabilities from multiple connected MCP servers into a unified virtual MCP. - -Here's how it works: - -1. **Connect MCP servers** to your decocms instance (GitHub, Slack, databases, etc.) -2. **Select tools** from one or more connections you want to expose -3. **Configure the virtual MCP** to include these selected capabilities -4. **Get a single endpoint** that exposes the aggregated toolset - -**Example**: Create a "deployment" virtual MCP that combines: -- GitHub tools (create PRs, merge, tag releases) -- Slack tools (post updates, create threads) -- Database tools (run migrations, verify schema) - -Your AI agent connects to one virtual MCP endpoint and gets access to all three systems. - -```typescript -// Configuration example: composition approach -{ - "name": "deployment-virtual-mcp", - "mode": "include", - "connections": [ - { - "connectionId": "github-conn-123", - "tools": ["CREATE_PR", "MERGE_PR", "CREATE_TAG"] - }, - { - "connectionId": "slack-conn-456", - "tools": ["POST_MESSAGE", "CREATE_THREAD"] - }, - { - "connectionId": "database-conn-789", - "tools": ["RUN_MIGRATION", "VERIFY_SCHEMA"] - } - ] -} -``` - -### Approach 2: Inline Creation - -**Inline creation** lets you create resources, prompts, and tools directly within decocms—no external MCP server needed. - -This is perfect for: - -- **Custom prompts** tailored to your team's workflows -- **Resources** like documentation, guidelines, or context -- **Tools** that orchestrate other tools or implement custom logic - -**Example**: Create a virtual MCP with inline prompts for code review: - -```typescript -// Configuration example: inline approach -{ - "name": "code-review-virtual-mcp", - "prompts": [ - { - "name": "security-review", - "description": "Review code for security vulnerabilities", - "template": "Analyze this code for security issues:\n- SQL injection\n- XSS vulnerabilities\n- Auth bypasses\n\nCode:\n{{code}}" - }, - { - "name": "performance-review", - "description": "Review code for performance issues", - "template": "Analyze this code for performance problems:\n- N+1 queries\n- Memory leaks\n- Inefficient algorithms\n\nCode:\n{{code}}" - } - ], - "resources": [ - { - "uri": "review://guidelines", - "name": "Code Review Guidelines", - "mimeType": "text/markdown", - "content": "# Review Guidelines\n\n1. Security first\n2. Performance matters\n..." - } - ] -} -``` - -### Hybrid: Mix Both Approaches - -Combine composition and inline creation in the same virtual MCP: - -```typescript -// Hybrid example: external tools + inline prompts -{ - "name": "development-assistant", - "connections": [ - { - "connectionId": "github-conn-123", - "tools": ["CREATE_PR", "LIST_ISSUES"] - } - ], - "prompts": [ - { - "name": "pr-template", - "description": "Generate PR description from commits", - "template": "Create a PR description from these commits:\n{{commits}}" - } - ] -} -``` - -This virtual MCP exposes GitHub tools from an external connection alongside custom prompts defined inline. - -## Virtual MCP Configuration - -Virtual MCPs are dynamically configurable: - -- **Tool selection**: Specify which tools to include from each connection -- **Dynamic updates**: attach new tools, resources, or prompts -- **Endpoint**: Each virtual MCP gets a unique endpoint at `/mcp/virtual/:virtualId` - -Every organization gets a **default virtual MCP** that aggregates all connections. - -## Concepts Built on Virtual MCPs - -Virtual MCPs are the **foundational feature** for specialized capabilities: - -- **Agents**: Single-purpose virtual MCPs optimized for specific tasks (see [Concepts](/en/mcp-mesh/concepts)) -- **Organization MCP**: Default virtual MCP that aggregates all your connections - -## Use Cases - -- **Unified Deployment**: Mix GitHub, Slack, and database MCPs into one endpoint for CI/CD workflows -- **Custom Code Review**: Define inline prompts tailored to your team's review process -- **Hybrid Development Assistant**: Combine external tools (GitHub, Jira) with inline prompts for contextual guidance - -## Benefits Summary - -Virtual MCPs eliminate infrastructure barriers: - -- **No server code or infrastructure**: configure capabilities, decocms handles hosting -- **Dynamic updates**: modify tools and resources without downtime -- **Composition and inline creation**: aggregate existing MCPs or define custom logic -- **Foundation for advanced workflows**: building block for agents and organizational tooling - -Virtual MCPs make MCP accessible to every team—no DevOps required. +When aggregating capabilities from multiple connections, decocms uses **connection-based namespacing** to avoid collisions. Each connection gets a unique ID, and all capabilities from that connection are prefixed with this ID. + +### Tools and Prompts + +Tools and prompts use the format: `connection_id::CAPABILITY_NAME` + +- **Namespace separator**: `::` (double colon) between connection ID and capability name +- **64-character limit**: The entire namespaced name cannot exceed 64 characters + +**Example**: Two GitHub connections can both expose a `CREATE_PR` tool: +- `github_personal_456::CREATE_PR` (personal account) +- `github_work_789::CREATE_PR` (work account) + +This ensures capabilities remain distinct even when multiple connections expose tools with the same name. + +### Resources + +Resources use URI-based namespacing, **except for well-known protocols**. + +**Custom protocols** (like `repo://`, `team://`) get namespaced with the connection ID and URL-encoded: +- Original: `repo://my-org/my-repo/README.md` +- Namespaced: `github_conn_123://repo%3A%2F%2Fmy-org%2Fmy-repo%2FREADME.md` + +**Well-known protocols** (like `http://`, `https://`, `ws://`) are **NOT namespaced** and remain unchanged. + +**Automatic content rewriting**: When resources are read through a virtual MCP, decocms automatically rewrites internal resource links to use the namespaced format. This ensures resources can reference each other correctly. + + +Tools and prompts use `connection_id::CAPABILITY_NAME` format (max 64 chars). Resources use `connection_id://encodedUri` for custom protocols, or stay unchanged for well-known protocols. + + +## Features Powered by Virtual MCPs + +Virtual MCPs provide the **foundational capability** that powers specialized features across decocms. All of these inherit full [monitoring capabilities](/en/mcp-mesh/monitoring) for audit trails and observability: + +- **[Agents](/en/mcp-mesh/agents)**: Single-purpose capability packages optimized for specific tasks +- **[Projects](/en/mcp-mesh/projects)**: Team-scoped capability packages for organizational boundaries +- **Organization MCP**: Default capability package that aggregates all your connections + +## Use Cases & Benefits + +Virtual MCPs turn fragmented MCP connections into unified, reusable capability packages: + +**Real-world applications:** +- **Unified Deployment Ops**: Package GitHub (PRs, releases) + Slack (notifications) + database (migrations) into one deployment MCP +- **Custom Code Review**: Remix GitHub tools with inline security/performance prompts and team style guides +- **Development Assistant**: Combine GitHub + Jira tools with inline workflow prompts and project context +- **Cross-system Orchestration**: Package CRM, analytics, and communication tools for end-to-end business processes + +**Key benefits:** +- **Selective remixing**: Choose exactly which tools, resources, and prompts to include from each connection +- **Inline extensions**: Add custom orchestration, validation, and feature gating logic +- **Dynamic updates**: Modify what's included without reconfiguring agents +- **Foundation for specialization**: Building block for [Projects](/en/mcp-mesh/projects) and [Agents](/en/mcp-mesh/agents) --- -**Ready to create your first virtual MCP?** Head to the [Quickstart](/en/mcp-mesh/quickstart) to get started, or learn about [Connections](/en/mcp-mesh/mcp-servers) to understand how to wire up external MCP servers. +## Next Steps + + +Start with [Connections](/en/mcp-mesh/connections) to understand how to wire up external MCP servers first. + + +**Ready to build?** Follow the [Quickstart](/en/mcp-mesh/quickstart) for step-by-step setup. + +**Building for teams?** Learn about [Projects](/en/mcp-mesh/projects) for team-scoped virtual MCPs, or [Agents](/en/mcp-mesh/agents) for single-purpose capability packages. + +**Need authorization controls?** See [Authorization and Roles](/en/mcp-mesh/authorization-and-roles) for securing virtual MCP access with feature gating and policies. From 42d9c19b10a41403a062c307f9be07345d99c35d Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 21:04:12 -0300 Subject: [PATCH 14/51] docs: make agents.mdx more user-friendly Replace technical implementation details with user-facing language: - Remove endpoint reference (/:org/agents/:agent_id) - Add "Agents provide" section with clear benefits - Mention agents are available in sidebar under "Agents" section - Remove "agent scope" jargon in favor of plain language - Remove technical "direct connection" usage pattern Focus on how users interact with agents rather than implementation details. Co-Authored-By: Claude Sonnet 4.5 --- apps/docs/client/src/content/en/mcp-mesh/agents.mdx | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx index 75484bdaec..9a297a49e0 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx @@ -14,7 +14,13 @@ import Callout from "../../../components/ui/Callout.astro"; **Agents** are single-purpose virtual MCPs optimized for specific tasks. While [Projects](/en/mcp-mesh/projects) provide general-purpose work environments, agents focus narrowly on accomplishing one thing well. -Agents are built on the [Virtual MCP](/en/mcp-mesh/virtual-mcps) foundation—they ARE virtual MCPs with their own tools, resources, prompts, and configuration. This makes agents first-class participants in your MCP ecosystem, exposing capabilities through standard MCP protocol endpoints at `/:org/agents/:agent_id`. +Agents provide: + +- **Focused capabilities** - Curated tools for specific tasks +- **Task-specific context** - Resources and guidelines tailored to the agent's purpose +- **Single-purpose design** - Clear objective with no unnecessary complexity + +Agents are available in the sidebar under the **Agents** section, where each operates as a focused workspace for its specific task. The key distinction: projects organize capabilities for broad work contexts, while agents optimize for single-purpose execution. @@ -66,12 +72,11 @@ These agents operate at organization level and leverage mesh MCP tools for platf Agents can be used in several ways: -- **Spawned by decopilot** - Agents spawned on-demand with fresh context for specific tasks +- **Spawned by decopilot** - Agents created on-demand with fresh context for specific tasks - **Built-in agents** - Pre-configured agents for mesh operations, ready immediately - **Custom agents** - Domain-specific agents for your team's unique workflows -- **Direct connection** - Connect MCP clients to agent endpoints for focused sessions -When working within an agent, you operate in **agent scope**—tools, resources, and prompts are limited to those configured for the agent. Operations are bounded by the agent's capabilities. +When working with an agent, you'll only see the tools, resources, and prompts configured for that agent's specific purpose. This focused view helps you stay on task without distraction. ## Benefits Summary From 32cdea431ee91482ffe794ef6ab450c45c488678 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 21:07:32 -0300 Subject: [PATCH 15/51] docs: align agents with SKILL.md pattern and clarify fields Key corrections: - Change "Purpose" field to "Description" and "Instructions" (actual agent fields) - Draw parallel between agents and SKILL.md files for familiarity - Clarify that decopilot uses description to learn when to spawn agents - Note that agents are organization-wide - Add cross-reference to decopilot documentation - Update "Clear purpose statement" to "Clear description" in design principles - Add "Detailed instructions" principle referencing SKILL.md pattern This makes the agent concept more intuitive by connecting it to familiar SKILL.md patterns. Co-Authored-By: Claude Sonnet 4.5 --- .../client/src/content/en/mcp-mesh/agents.mdx | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx index 9a297a49e0..c851529821 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx @@ -20,21 +20,27 @@ Agents provide: - **Task-specific context** - Resources and guidelines tailored to the agent's purpose - **Single-purpose design** - Clear objective with no unnecessary complexity -Agents are available in the sidebar under the **Agents** section, where each operates as a focused workspace for its specific task. +Agents are organization-wide and available in the sidebar under the **Agents** section, where each operates as a focused workspace for its specific task. The key distinction: projects organize capabilities for broad work contexts, while agents optimize for single-purpose execution. ## How Agents Work -Create an agent by defining its purpose and curating its capabilities: +Agents follow the same pattern as standard agent skills (`SKILL.md` files), making them familiar and easy to understand: -1. **Name** - Identifies the agent (e.g., "Deployment Agent", "Research Agent") -2. **Purpose** - Clear statement of what the agent does (e.g., "Deploy applications to production") -3. **Tools** - Actions the agent can take (select from [connections](/en/mcp-mesh/connections) or define inline) -4. **Resources** - Context and guidelines specific to the agent's task -5. **Prompts** - Templates tailored to the agent's workflow +**Like SKILL.md skills:** +- **Description** - Brief explanation of what the agent does and when to use it (like the `description:` field in `SKILL.md`) +- **Instructions** - Detailed guidelines for how the agent operates (like the body of a `SKILL.md` file) -Since agents are [Virtual MCPs](/en/mcp-mesh/virtual-mcps), you can compose them from existing connections, define capabilities inline, or mix both approaches. The agent's configuration determines what it can do and how it operates. +**Plus Virtual MCP capabilities:** +- **Name** - Identifies the agent (e.g., "Deployment Agent", "Research Agent") +- **Tools** - Actions the agent can take (select from [connections](/en/mcp-mesh/connections) or define inline) +- **Resources** - Additional context and documentation +- **Prompts** - Workflow templates + +[decopilot](/en/mcp-mesh/decopilot/overview) uses the **description** field to understand when to spawn each agent—just like it uses skill descriptions to know when to invoke skills. This makes agents discoverable and automatically available when relevant to the task at hand. + +Since agents are [Virtual MCPs](/en/mcp-mesh/virtual-mcps), you can compose them from existing connections, define capabilities inline, or mix both approaches. ## Example: Production Deployment Agent @@ -58,12 +64,14 @@ These agents operate at organization level and leverage mesh MCP tools for platf **Single-purpose focus**: Each agent should do one thing well. Narrow scope improves clarity, reliability, and maintainability. -**Clear purpose statement**: Define agents with `[Verb] + [Object] + [Context]` pattern: +**Clear description**: Write descriptions that help decopilot understand when to spawn the agent. Use `[Verb] + [Object] + [Context]` pattern: - "Deploy applications to production environments" - "Analyze test coverage for code quality" - "Manage agent lifecycle in the organization" -**Tool selection**: Choose tools that align with the agent's purpose. A research agent needs read-only tools; a deployment agent needs release and notification tools. Overly broad tool access dilutes focus. +**Detailed instructions**: Provide clear guidelines in the instructions field—just like you would in a `SKILL.md` file. Include constraints, workflow steps, and behavioral guidelines. + +**Tool selection**: Choose tools that align with the agent's description. A research agent needs read-only tools; a deployment agent needs release and notification tools. Overly broad tool access dilutes focus. **Good**: "Deployment Agent" (deploys to production) **Too broad**: "DevOps Agent" (deploys, monitors, manages infrastructure, handles incidents...) From 8fb6cf8a96a83242e3c6aef445a183d9897e5472 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 21:14:57 -0300 Subject: [PATCH 16/51] docs: replace MCP Mesh with decocms in agents.mdx Update product name references for consistency. Co-Authored-By: Claude Sonnet 4.5 --- apps/docs/client/src/content/en/mcp-mesh/agents.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx index c851529821..1ce6a40b6b 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx @@ -7,7 +7,7 @@ icon: Bot import Callout from "../../../components/ui/Callout.astro"; - This page documents the **planned architecture** for agents in MCP Mesh. The implementation is in development. + This page documents the **planned architecture** for agents in decocms. The implementation is in development. ## What Are Agents? @@ -48,7 +48,7 @@ A deployment agent might aggregate GitHub tools for tagging and releases, Slack ## Built-in Agents -MCP Mesh includes built-in agents for common mesh operations. These agents use the **Mesh MCP**—a self-referential MCP that exposes mesh management capabilities through the MCP protocol. +decocms includes built-in agents for common mesh operations. These agents use the **Mesh MCP**—a self-referential MCP that exposes mesh management capabilities through the MCP protocol. Built-in agents available out-of-the-box: From df4fdf3ed5d6b1b7890fd506a9461aa6dd0c13ff Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 21:34:04 -0300 Subject: [PATCH 17/51] docs: implement decopilot documentation improvements plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete rewrite of decopilot documentation to emphasize MCP orchestration and agentic workflows. Key changes: - Rewrite overview.mdx with agentic loop focus (gather → act → verify) - Create new quickstart.mdx with 4 practical workflow examples - Enhance scopes.mdx with workflow examples and decision guides - Enhance tools.mdx with patterns, use cases, and troubleshooting - Enhance spawning-agents.mdx with advanced patterns and agent selection - Enhance context-management.mdx with optimization strategies and budget examples - Update navigation.ts to prioritize practical content (overview → quickstart → concepts) - Update architecture.mdx to map agentic loop to implementation Documentation now positions decopilot as an MCP orchestration layer rather than a development tool, emphasizing distributed MCP coordination over HTTP (or stdio for local servers). Virtual MCPs presented as enabler for liquid MCP creation/modification, distributable across the web. All beads tasks completed: main-6pc, main-tzu, main-qpk, main-ds5, main-cxu, main-3kg, main-frw, main-dfb Co-Authored-By: Claude Sonnet 4.5 --- .../en/mcp-mesh/decopilot/architecture.mdx | 73 ++- .../mcp-mesh/decopilot/context-management.mdx | 260 +++++++- .../en/mcp-mesh/decopilot/overview.mdx | 214 ++++--- .../en/mcp-mesh/decopilot/quickstart.mdx | 596 ++++++++++++++++++ .../content/en/mcp-mesh/decopilot/scopes.mdx | 304 +++++++++ .../en/mcp-mesh/decopilot/spawning-agents.mdx | 422 +++++++++++++ .../content/en/mcp-mesh/decopilot/tools.mdx | 478 ++++++++++++++ apps/docs/client/src/utils/navigation.ts | 44 +- 8 files changed, 2290 insertions(+), 101 deletions(-) create mode 100644 apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx index 65bd33c345..13826301ea 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx @@ -14,6 +14,8 @@ import Callout from "../../../../components/ui/Callout.astro"; Decopilot is an MCP-native AI agent that operates through a scope-sensitive architecture where **everything is a virtual MCP**. Unlike traditional AI coding assistants that work with local filesystems, decopilot is built from the ground up to operate on virtual MCPs—editable, configurable MCP servers that can be dynamically modified at runtime. +Decopilot operates through an **agentic loop**—gathering context from distributed MCP servers, taking coordinated actions, and verifying results—all while dynamically adapting based on scope. This continuous cycle enables autonomous workflows spanning multiple services, with decopilot orchestrating external MCPs (GitHub, Figma, Slack) while operating on editable virtual MCPs to reshape the environment as it works. + The architecture is fundamentally defined by three core principles: **Scope-based operation**: Decopilot's behavior adapts based on the current route—operating in org scope (`/:org/settings`), project scope (`/:org/projects/:id`), or agent scope (`/:org/agents/:id`). Each scope corresponds to a different virtual MCP with distinct capabilities. @@ -24,6 +26,73 @@ The architecture is fundamentally defined by three core principles: This architecture enables decopilot to dynamically reshape the environment as it works, adding tools, creating resources, and configuring capabilities on the fly—operations that are only possible with editable virtual MCPs. +## The Agentic Loop in Practice + +Decopilot's agentic loop—**gather → act → verify**—maps directly to the architecture, showing how system components enable autonomous workflows. + +### Gather Context Phase + +Decopilot gathers context through built-in tools that query the current scope's virtual MCP and connected external MCPs: + +- **`tools_search`**: Discovers available tools from virtual MCP and external connections +- **`resource_read`**: Loads project documentation, architecture decisions, guidelines +- **`tools_read`**: Inspects tool specifications to understand capabilities +- **External MCP queries**: Invokes tools from GitHub (branch status), Figma (design specs), databases (data state) + +**Architecture insight**: The scope determines which virtual MCP is queried and which external MCPs are accessible. Project scope provides project-specific context; agent scope provides bounded, focused context. + +### Take Action Phase + +Decopilot takes action by: + +- **Enabling and invoking external MCP tools**: `tool_enable` followed by tool invocation (CREATE_PR, EXPORT_ASSETS, SEND_MESSAGE) +- **Creating resources**: `resource_edit` to document decisions, findings, or generate artifacts +- **Creating inline tools**: `tools_edit` to add project-specific capabilities dynamically +- **Spawning agents**: `agent_spawn` to delegate specialized work with isolated context + +**Architecture insight**: Virtual MCPs are editable, enabling decopilot to create tools and resources on the fly. External MCPs provide read-only tool access—decopilot invokes but doesn't modify them. + +### Verify Results Phase + +Decopilot verifies outcomes through: + +- **Tool response checking**: Confirms successful execution and validates return values +- **Agent spawning for verification**: Spawns review agents (security, performance, quality) to validate work +- **Resource creation**: Documents findings and results for future reference +- **Status reporting**: Determines next actions based on verification results + +**Architecture insight**: Agent spawning provides fresh context for verification without polluting the main loop. Results integrate as summaries (~200-500 tokens), not full conversations. + +### Complete Loop Example + +```typescript +// User request in project scope +User: "Create a PR for the auth feature" + +// GATHER: Check current state +const branch = await GIT_BRANCH_STATUS({ repo: "mobile-app" }) +const commits = await GIT_LOG({ repo: "mobile-app", limit: 5 }) + +// ACT: Create PR +await tool_enable({ tool_name: "CREATE_PR" }) +const pr = await CREATE_PR({ + title: "Add biometric authentication", + body: "Implements face ID and fingerprint auth", + base: "main", + head: "feature/biometric-auth" +}) + +// VERIFY: Spawn security agent for review +await agent_spawn({ + agent_id: "security-reviewer", + prompt: `Review PR #${pr.number} for security issues` +}) + +// Loop continues: integrate findings, update PR if needed +``` + +**Key architectural benefit**: The agentic loop operates seamlessly across distributed MCP servers (via HTTP or stdio). Each phase leverages virtual MCPs for editability and external MCPs for domain-specific capabilities. + ## Architectural Constraint: Virtual MCPs Only Decopilot has a fundamental architectural constraint: **it only works with virtual MCPs**. This constraint exists for a critical reason—decopilot needs to operate on and edit the MCP configurations dynamically. @@ -481,7 +550,7 @@ const githubMCP = { ### Virtual MCPs -Virtual MCPs are editable, configurable MCP servers managed by MCP Mesh: +Virtual MCPs are editable, configurable MCP servers managed by decocms: **Characteristics**: - Dynamic toolset that can be modified at runtime @@ -538,7 +607,7 @@ External MCPs and virtual MCPs interact through composition: ```typescript // External MCP connection to virtual MCP const externalToVirtual = { - // 1. Connect external MCP to MCP Mesh + // 1. Connect external MCP to decocms externalMCP: { id: "github-conn-123", serverUrl: "https://github-mcp.example.com", diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx index e9a2944ce3..b64874a7c0 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx @@ -112,7 +112,7 @@ Virtual MCPs enable dynamic filtering based on agent type and task requirements. **Filtering strategies**: Development agents receive write operations (CREATE_BRANCH, COMMIT_CHANGES), research agents get read-only tools (READ_FILE, SEARCH_CODE), and deployment agents access infrastructure tools (DEPLOY, ROLLBACK). This reduces average tool context from 15,000 tokens to 3,000-5,000 tokens depending on agent type. -Resources load only when explicitly requested through tool calls, preventing automatic inclusion in base context. This on-demand approach keeps initial context minimal while providing access to full project resources when needed. +Resources load only when explicitly requested through tool invocations, preventing automatic inclusion in base context. This on-demand approach keeps initial context minimal while providing access to full project resources when needed. ## Context Isolation via Agent Spawning @@ -129,6 +129,264 @@ This isolation ensures agents focus on their specific task without distraction f **Benefits**: Faster processing due to smaller context, better focus on specific objectives, parallel execution of independent tasks, and cleaner results integrated back to parent. See [Task-Based Agent Spawning](/en/mcp-mesh/decopilot/architecture#task-based-agent-spawning) for implementation details. +## Optimizing Context in Practice + +Understanding context management concepts is essential, but applying them effectively requires practical strategies. Here are proven approaches for optimizing context in real workflows. + +### Strategy 1: Strategic Agent Spawning + +**Problem**: Main context becomes bloated with exploratory work, test results, and detailed analysis. + +**Solution**: Spawn agents for any work that generates significant context but doesn't need to persist in the main conversation. + +**Example: Context Bloat (Avoid)** + +```typescript +// Main decopilot context +User: "Implement push notifications" + +// Decopilot explores options (adds ~5000 tokens) +- Researches Firebase Cloud Messaging +- Compares with OneSignal, APNs, AWS SNS +- Reads documentation for each +- Analyzes pros/cons + +// Implements feature (adds ~8000 tokens) +- Creates notification service files +- Implements iOS handler +- Implements Android handler +- Adds error handling + +// Tests implementation (adds ~6000 tokens) +- Runs unit tests (full output) +- Runs integration tests +- Reviews test results +- Fixes failing tests + +// Total context: ~19,000 tokens for one feature +// Main conversation is polluted with exploratory details +``` + +**Example: Fresh Context Isolation (Better)** + +```typescript +// Main decopilot context (~2000 tokens total) +User: "Implement push notifications" + +// Spawn research agent (isolated context) +const researchTask = await agent_spawn({ + agent_id: "research-agent", + prompt: "Research push notification solutions. Compare Firebase, OneSignal, AWS SNS. Recommend best fit." +}) +// Agent generates ~5000 tokens internally +// Returns ~300 token summary: "Recommend Firebase Cloud Messaging because..." + +// Spawn development agent (isolated context) +const devTask = await agent_spawn({ + agent_id: "development-agent", + prompt: "Implement Firebase Cloud Messaging for push notifications. Support iOS and Android." +}) +// Agent generates ~8000 tokens internally +// Returns ~400 token summary: "Implemented push service in src/notifications/..." + +// Spawn testing agent (isolated context) +const testTask = await agent_spawn({ + agent_id: "testing-agent", + prompt: "Write tests for push notification service. Test all platforms." +}) +// Agent generates ~6000 tokens internally +// Returns ~300 token summary: "Tests passing. Coverage 94%..." + +// Main context: ~2000 + 300 + 400 + 300 = ~3000 tokens total +// Fresh context for each task, summaries only in main conversation +``` + +**Key insight**: Spawning agents prevents context bloat by isolating detailed work. Main conversation stays focused on high-level decisions and results. + +### Strategy 2: Resource Management + +**Problem**: Loading all project resources upfront exhausts context before work begins. + +**Solution**: Load resources on-demand only when actually needed for specific tasks. + +**Example: Upfront Loading (Avoid)** + +```typescript +// Load everything upfront +await resource_read({ uri: "project://mobile-app/architecture" }) // 2000 tokens +await resource_read({ uri: "project://mobile-app/api-docs" }) // 3000 tokens +await resource_read({ uri: "project://mobile-app/testing-guide" }) // 1500 tokens +await resource_read({ uri: "org://coding-standards" }) // 1000 tokens +await resource_read({ uri: "org://security-policy" }) // 1500 tokens + +// Total: 9000 tokens consumed before any work starts +// Most resources never actually used +``` + +**Example: On-Demand Loading (Better)** + +```typescript +// Load only what's needed for current task +User: "Add biometric authentication" + +// Only load architecture doc (relevant to feature design) +const arch = await resource_read({ uri: "project://mobile-app/architecture" }) +// 2000 tokens - actually used + +// If security question arises later, load then +const security = await resource_read({ uri: "org://security-policy" }) +// 1500 tokens - loaded when needed + +// Total: 3500 tokens, all actually used +``` + +**Key insight**: Resources should be loaded just-in-time. Don't preemptively load "everything that might be useful." + +### Strategy 3: Tool Filtering + +**Problem**: All tools from all connected MCP servers are included in context, even if irrelevant. + +**Solution**: Enable only the tools you actually need for the current task. + +**Example: Unfiltered Tools (Wasteful)** + +```typescript +// All tools available from 3 connected MCPs: +// - GitHub MCP: 50 tools (~5000 tokens) +// - Figma MCP: 30 tools (~3000 tokens) +// - Slack MCP: 20 tools (~2000 tokens) +// Total: 100 tools, ~10,000 tokens + +// But task only needs GitHub PR creation +``` + +**Example: Selective Enabling (Efficient)** + +```typescript +// Search for specific tools needed +const tools = await tools_search({ search_term: "pull request" }) + +// Enable only what's needed +await tool_enable({ tool_name: "CREATE_PR" }) +await tool_enable({ tool_name: "LIST_FILES" }) + +// Context: ~200 tokens for 2 tools vs 10,000 for all +``` + +**Key insight**: The discover → enable → use pattern naturally filters tools. Only enabled tools consume context. + +### Strategy 4: Scope Awareness + +**Problem**: Working in wrong scope, loading unnecessary inherited context. + +**Solution**: Use the most specific scope appropriate for your task. + +**Example: Wrong Scope (Bloated)** + +```typescript +// Working in org scope when you need project-specific work +// Org scope includes: +// - All org-level tools (~3000 tokens) +// - All org resources (~5000 tokens) +// - Org CLAUDE.md (~500 tokens) +// But you're implementing a project feature + +// Total: ~8500 tokens of irrelevant org context +``` + +**Example: Right Scope (Focused)** + +```typescript +// Navigate to project scope: /:org/projects/mobile-app +// Project scope includes: +// - Project-specific tools (~2000 tokens) +// - Project resources (~2000 tokens) +// - Project CLAUDE.md + inherited org CLAUDE.md (~800 tokens) +// All relevant to the project feature + +// Total: ~4800 tokens, all relevant +``` + +**Key insight**: Navigate to the most specific scope for your work. Don't work in org scope when you need project context. + +## Context Budget Examples + +Understanding typical token budgets helps plan workflows and predict when to spawn agents. + +### Scenario 1: Simple PR Creation + +**Task**: Create a pull request for a completed feature. + +**Context breakdown**: +``` +System instructions: ~800 tokens +CLAUDE.md (project): ~500 tokens +Conversation history: ~1000 tokens (user request + planning) +Tool definitions: ~100 tokens (CREATE_PR only) +Total: ~2400 tokens +``` + +**Remaining budget**: ~197,600 tokens available for PR creation, tool responses, and conversation. + +**Assessment**: Plenty of room. No need for agent spawning. Single-task workflow works well. + +### Scenario 2: Complex Multi-Agent Workflow + +**Task**: Implement feature with research, development, testing, and review. + +**Context breakdown (without agent spawning)**: +``` +System instructions: ~800 tokens +CLAUDE.md (project): ~500 tokens +Research work: ~5000 tokens (exploration, docs) +Development work: ~8000 tokens (implementation, iteration) +Testing work: ~6000 tokens (test runs, results) +Review work: ~4000 tokens (security scan, findings) +Tool definitions: ~5000 tokens (many tools enabled) +Conversation history: ~10,000 tokens (accumulated) +Total: ~39,300 tokens +``` + +**Remaining budget**: ~160,700 tokens + +**Assessment**: Works but polluted context. Better approach: spawn agents. + +**With agent spawning**: +``` +System instructions: ~800 tokens +CLAUDE.md (project): ~500 tokens +Research summary: ~300 tokens (from spawned agent) +Development summary: ~400 tokens (from spawned agent) +Testing summary: ~300 tokens (from spawned agent) +Review summary: ~300 tokens (from spawned agent) +Tool definitions: ~100 tokens (minimal in main) +Conversation history: ~2000 tokens (high-level only) +Total: ~4700 tokens +``` + +**Remaining budget**: ~195,300 tokens + +**Assessment**: Much more efficient. Main context stays focused. Each agent worked with fresh context. + +### Scenario 3: Research Agent Spawn + +**Task**: Spawned agent exploring codebase architecture. + +**Context breakdown (spawned agent)**: +``` +System instructions: ~800 tokens +CLAUDE.md (project): ~500 tokens +AGENTS.md (research): ~300 tokens +Task prompt: ~200 tokens +Tool definitions: ~500 tokens (read-only tools) +Agent conversation: ~10,000 tokens (detailed exploration) +Total: ~12,300 tokens +``` + +**Parent receives**: ~400 token summary of findings + +**Key insight**: Agent uses ~12,300 tokens internally, but parent only receives ~400. Fresh context enables deep work without polluting parent. + ## Summary Decopilot balances completeness with efficiency through priority-based inclusion, tool filtering, on-demand resources, and agent spawning. Virtual MCPs enable dynamic, scope-aware context management for efficient operation within token limits. diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx index 899f388cd8..7b737ac6f5 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx @@ -1,6 +1,6 @@ --- -title: Decopilot Overview -description: MCP-native AI agent for web-based development that operates on virtual MCPs +title: Overview +description: The agentic AI assistant that runs on decocms, operating through distributed MCP architecture icon: Sparkles --- @@ -12,142 +12,178 @@ import Callout from "../../../../components/ui/Callout.astro"; ## What is Decopilot? -**Decopilot** is an MCP-native AI agent designed for web-based development within MCP Mesh. Unlike traditional AI coding assistants that operate on local filesystems, decopilot is built from the ground up to work with the Model Context Protocol—operating through MCP servers, virtual MCPs, and distributed capabilities. +**Decopilot** is an agentic AI assistant that operates through the Model Context Protocol within decocms. Unlike traditional AI coding assistants that work with local filesystems, decopilot orchestrates distributed MCP servers over HTTP (or stdio when running locally) to deliver state-of-the-art agentic workflows. -The defining characteristic of decopilot is that **it only works with virtual MCPs**. This is a fundamental architectural constraint: decopilot needs to operate and edit the MCP configurations dynamically, which is only possible with virtual MCPs. External MCP servers (like traditional GitHub or Slack servers) are read-only connections that decopilot cannot modify. This is why projects, agents, and organization scopes are all virtual MCPs—they provide the editable, configurable foundation that decopilot requires. +Decopilot brings the proven agentic loop pattern—**gather context → take action → verify results**—to MCP orchestration. It coordinates work across multiple MCP servers, dynamically adapting based on scope, and delegating to specialized agents when needed. This distributed MCP architecture makes decopilot fundamentally different from filesystem-based assistants: it's an MCP orchestration layer, not a development tool. -Decopilot is part of the MCP Mesh infrastructure, operating within the scope-based routing system to provide context-aware assistance across organization, project, and agent levels. +Decopilot uses **virtual MCPs** to make creating and modifying MCPs as easy and liquid as creating files on a filesystem—but with the added benefit of being distributable across the web. While decopilot invokes tools from external MCP servers (GitHub, Figma, Slack), it operates on virtual MCPs to dynamically reshape the environment as it works. Projects, agents, and organization scopes are all virtual MCPs, providing the editable, programmable foundation that enables decopilot's agentic capabilities. -## Why Virtual MCPs? + +Start with the [Quick Start](/en/mcp-mesh/decopilot/quickstart) guide to see the agentic loop in action with practical workflows. + -Decopilot's foundation is built on [Virtual MCPs](/en/mcp-mesh/virtual-mcps), and understanding why is crucial: +## The Agentic Loop -**Virtual MCPs are editable and configurable**. When decopilot operates in a project, it can dynamically add tools, create resources, update prompts, and modify the virtual MCP configuration. This enables decopilot to: +Decopilot operates through a continuous cycle that adapts to your work: -- Add new tools to the current context on the fly -- Create documentation resources as it works -- Update project prompts based on workflow patterns -- Configure agent capabilities dynamically +**1. Gather Context**: Query connected MCP servers to understand current state +- Read GitHub repositories to check branch status and recent commits +- Fetch Figma designs to understand UI specifications +- Query databases or APIs to verify data state +- Load project resources (architecture docs, checklists, guidelines) -**Regular MCP servers are read-only**. External MCP servers like GitHub or Slack provide fixed capabilities through the MCP protocol. Decopilot can use these tools, but it cannot modify the server configuration. These external connections are composed into virtual MCPs to make them part of the editable context. +**2. Take Action**: Execute tools across distributed MCP servers +- Create branches, commit code, open pull requests via GitHub MCP +- Export assets, check design specs via Figma MCP +- Send notifications, update channels via Slack MCP +- Create inline tools in virtual MCPs for project-specific operations -**Projects, agents, and org scopes are all virtual MCPs**. This ensures decopilot always has an editable foundation. When you work in a project (`/:org/projects/:id`), that project IS a virtual MCP that decopilot can operate on and modify. The same is true for agents and organization scope. +**3. Verify Results**: Check outcomes and determine next steps +- Confirm actions completed successfully across all services +- Spawn specialized agents to verify code quality, security, or performance +- Update project resources with findings +- Report results and recommend follow-up actions -This architecture makes decopilot fundamentally different from traditional AI assistants—it doesn't just use tools, it can reshape the environment it operates in. +This loop runs continuously as you work, with decopilot adapting based on scope. The distributed nature means decopilot can orchestrate complex workflows spanning multiple services—all coordinated through the MCP protocol. - - If you're familiar with Claude Code, here's how decopilot concepts map to what you know: +```mermaid +graph LR + A[Gather Context] --> B[Take Action] + B --> C[Verify Results] + C --> A -| Claude Code | Decopilot | -|-------------|-----------| -| Skills | Virtual MCPs (agents) | -| `project/.claude/` | Project scope (`/:org/projects/:id`) | -| `~/.claude/` | Org scope (org routes) | -| Subagents | Task-based agent spawning | -| CLAUDE.md | CLAUDE.md + AGENTS.md | -| Skill references/assets | MCP resources | -| `/command` invocation | MCP commands | + A -.-> D[GitHub MCP] + A -.-> E[Figma MCP] + A -.-> F[Project Virtual MCP] -The key difference: decopilot operates through the MCP protocol on virtual MCPs, making it web-native and composable across your infrastructure. - + B -.-> D + B -.-> E + B -.-> F + + C -.-> G[Spawn Agent] + G -.-> C +``` + +## Distributed MCP Architecture + +Decopilot's core differentiator is its **distributed MCP architecture**—the ability to coordinate work across multiple MCP servers while operating on editable virtual MCPs. + +**External MCP Servers (Read-Only)**: Decopilot invokes tools from external MCP servers like GitHub, Figma, Slack, and databases. These servers expose their capabilities through the MCP protocol (over HTTP or stdio). Decopilot uses these tools but cannot modify the server configurations—they're external, read-only connections. + +**Virtual MCPs (Editable)**: Decopilot operates on virtual MCPs—editable MCP endpoints that can be modified dynamically. When working in a project, decopilot can add tools, create resources, update prompts, and reshape the virtual MCP configuration. This is the programmable layer that makes decopilot's dynamic behavior possible. + +**Composition**: External MCP servers are composed into virtual MCPs through connections. A project's virtual MCP might include GitHub tools, Figma tools, and custom inline tools—all available through one unified MCP endpoint. Decopilot operates on this composed virtual MCP while invoking tools from the external servers. + +**Protocol-Based Orchestration**: MCP coordination happens over HTTP for remote servers or stdio for local servers. Decopilot doesn't need filesystem access—it coordinates distributed MCP servers through the MCP protocol. This makes decopilot portable, scalable, and composable across your infrastructure. + +This architecture enables workflows that span multiple services in a single agentic loop. Need to create a branch, export Figma assets, and notify the team? Decopilot orchestrates all three through distributed MCP calls, verifies success, and reports back—pure MCP orchestration. ## Key Capabilities -**Virtual MCP Foundation**: Decopilot operates exclusively on virtual MCPs, enabling it to edit and configure the environment as it works. This is not just a feature—it's the architectural foundation that makes decopilot's dynamic behavior possible. +**Agentic Workflow Orchestration**: The continuous gather → act → verify loop enables decopilot to handle complex, multi-step workflows autonomously. Decopilot breaks down ambiguous requests into concrete actions, executes them across distributed services, and adapts based on results. + +**Distributed Tool Coordination**: Invoke tools from multiple MCP servers in a single workflow. Decopilot seamlessly coordinates GitHub, Figma, Slack, databases, and custom tools—all through standardized MCP protocol. -**Scope-Sensitive Operations**: Decopilot automatically adapts based on where you are in the application. Operating in org scope (`/:org/settings`) gives you organization-wide capabilities. Working in project scope (`/:org/projects/:id`) provides project-specific tools and context. Agent scope (`/:org/agents/:id`) bounds operations to the agent's focused purpose. +**Dynamic Environment Configuration**: Operating on virtual MCPs means decopilot can reshape the environment as it works. Add tools on the fly, create resources for documentation, update prompts based on patterns—all without manual configuration. -**Task-Based Agent Spawning**: Decopilot can spawn agents on specific tasks with fresh context. Agents run until they respond, then the main decopilot loop continues. This enables parallel work and focused execution without context pollution. +**Scope-Sensitive Operations**: Decopilot automatically adapts based on where you are in the application. Organization scope provides org-wide capabilities. Project scope gives project-specific tools and context. Agent scope bounds operations to focused purposes. -**Agent Selection**: When spawning agents, decopilot can pick any agent configured in your organization to accomplish the task. This allows delegation to specialized agents optimized for particular operations. +**Agent Spawning**: Delegate to specialized agents with fresh context for parallel work. Spawn a security agent to review code while continuing with implementation. Spawn a research agent to explore architecture while keeping the main context clean. -**Built-in Tools**: Comprehensive toolset for MCP management, including tools for reading and editing resources, prompts, and tools within the current virtual MCP scope. +**Context Management**: Intelligent token management through strategic agent spawning and tool filtering. Decopilot balances completeness with efficiency, ensuring relevant context without bloat. -## How It Works +## Scope-Based Operation Decopilot operates in **three distinct scopes**, each corresponding to a different virtual MCP: -**Org Scope** (`/:org/settings`, `/:org/connections`): Operates like an org-admin with organization-wide resources, prompts, and tools. Comparable to `~/.claude/` in Claude Code—this is the foundation level where shared context lives. +**Org Scope** (`/:org/settings`): Organization-wide context with shared resources, prompts, and connected MCPs. Think of this as the foundation level—comparable to `~/.claude/` in Claude Code. -**Project Scope** (`/:org/projects/:id`): Projects ARE virtual MCPs, not just containers. Each project has project-specific tools, resources, and connected MCPs. Comparable to `.claude/` in Claude Code—isolated work context for the project. +**Project Scope** (`/:org/projects/:id`): Project-specific virtual MCP with project tools, resources, and connected external MCPs. Isolated work context for the project—comparable to `.claude/` in Claude Code. -**Agent Scope** (`/:org/agents/:id`): Agents ARE virtual MCPs optimized for single-purpose tasks. Most narrowly focused scope for repeatable, well-defined operations. +**Agent Scope** (`/:org/agents/:id`): Single-purpose virtual MCP optimized for repeatable tasks. Most narrowly focused scope with bounded tool access. -The route determines the scope automatically. As you navigate through the application, decopilot seamlessly adapts to the new context. Each scope is a virtual MCP that decopilot can operate on and edit, providing the foundation for its dynamic capabilities. +The route determines the scope automatically. As you navigate the application, decopilot seamlessly adapts to the new context, adjusting available tools, resources, and capabilities accordingly. -### Task-Based Agent Spawning +For detailed information on how scopes work and when to use each, see [Scopes](/en/mcp-mesh/decopilot/scopes). -Decopilot can spawn agents to handle specific tasks: +## Quick Examples + +### Multi-Server Workflow + +Working in a project, you ask decopilot to prepare a feature branch: ```typescript -// Conceptual example: spawning an agent -decopilot.spawnAgent({ - agentId: "research-agent-001", - task: "Analyze the authentication architecture in this codebase", - context: { projectId: "mobile-app-rewrite" } -}) -// Agent runs until it responds, then main loop continues -``` +// Decopilot orchestrates across 3 MCP servers: -This enables parallel execution and focused work without polluting the main decopilot context. +// 1. GitHub MCP - Create feature branch +CREATE_BRANCH({ name: "feature/biometric-auth", base: "main" }) -### Editing Virtual MCPs +// 2. Figma MCP - Export latest auth flow designs +EXPORT_ASSETS({ fileId: "auth-flows", format: "svg" }) -Because decopilot operates on virtual MCPs, it can modify them dynamically: +// 3. Slack MCP - Notify team +SEND_MESSAGE({ channel: "engineering", text: "Started biometric auth feature" }) -```typescript -// Conceptual example: editing the current virtual MCP -decopilot.addTool({ - name: "DEPLOY_STAGING", - description: "Deploy to staging environment", - // ... tool configuration -}) - -decopilot.createResource({ - uri: "project://mobile-app/deployment-checklist", - name: "Deployment Checklist", - content: "# Deployment Checklist\n\n- [ ] Run tests\n- [ ] Update changelog\n..." -}) +// All coordinated through decopilot's agentic loop ``` -This is only possible because projects, agents, and org scopes are all virtual MCPs—editable and configurable in real-time. +### Agent Spawning Pattern -## Quick Examples +Need security review while continuing development: -**Working in Project Scope**: +```typescript +// Main loop: Implementing feature +User: "Add biometric authentication" + +Decopilot: +- Plans implementation approach +- Spawns security agent on parallel task + +// Spawned agent (isolated context) +Agent: security-reviewer-001 +- Scans authentication files +- Checks for common vulnerabilities +- Generates findings report +- Returns to main loop + +// Main loop continues +Decopilot: +- Completes implementation +- Integrates security findings +- Updates code based on recommendations +``` -When editing a project's virtual MCP, decopilot can: -- Add GitHub tools for creating pull requests -- Create project-specific resources like architecture documentation -- Update prompts for code review templates -- Configure connections to external MCP servers +The agent runs with fresh context, preventing token bloat while enabling focused security analysis in parallel. -**Spawning an Agent on a Task**: + + If you're familiar with Claude Code, here's how decopilot concepts map to what you know: -When analyzing a large codebase, spawn a research agent: -- Agent gets fresh context for the specific task -- Agent has read-only tools to explore code -- Agent reports findings back to main decopilot loop -- Main context remains clean and focused +| Claude Code | Decopilot | +|-------------|-----------| +| Agentic loop (local) | Agentic loop (distributed MCP) | +| Skills | Virtual MCPs (agents) | +| `project/.claude/` | Project scope (`/:org/projects/:id`) | +| `~/.claude/` | Org scope (org routes) | +| Subagents | Agent spawning with `agent_spawn` | +| CLAUDE.md | CLAUDE.md + AGENTS.md | +| Skill references/assets | MCP resources | +| `/command` invocation | MCP commands | -For detailed information on how scopes work, see [Scopes](/en/mcp-mesh/decopilot/scopes). +**Key difference**: Decopilot brings Claude Code's agentic patterns to MCP orchestration through distributed architecture. Instead of local filesystem operations, decopilot coordinates work across multiple MCP servers—GitHub, Figma, Slack, databases, and more—all through standardized MCP protocol. + ## Next Steps -**Virtual MCPs** (foundational): Understand why decopilot uses virtual MCPs and how they enable dynamic configuration. Start here: [Virtual MCPs](/en/mcp-mesh/virtual-mcps) - -**Scopes**: Learn how org/project/agent scopes work and how routing determines context. See: [Scopes](/en/mcp-mesh/decopilot/scopes) - -**Projects**: Understand projects as virtual MCPs and how they organize work. Read: [Projects](/en/mcp-mesh/projects) +**[Quick Start](/en/mcp-mesh/decopilot/quickstart)**: See the agentic loop in action with practical workflows. Start here for hands-on examples. -**Agents**: Explore single-purpose virtual MCPs and how they provide focused capabilities. Check: [Agents](/en/mcp-mesh/agents) +**[Scopes](/en/mcp-mesh/decopilot/scopes)**: Learn how org/project/agent scopes determine available tools and context. Essential for understanding decopilot's behavior. -**Architecture**: Deep-dive into decopilot's technical architecture and implementation (coming soon) +**[Architecture](/en/mcp-mesh/decopilot/architecture)**: Deep-dive into decopilot's technical implementation, virtual MCP constraint, and distributed coordination. -**Context Management**: Learn how decopilot maintains context across scopes and agent spawning (coming soon) +**[Tools](/en/mcp-mesh/decopilot/tools)**: Explore the comprehensive toolset for MCP management and tool discovery patterns. -**Built-in Tools**: Explore the comprehensive toolset for MCP management (coming soon) +**[Virtual MCPs](/en/mcp-mesh/virtual-mcps)**: Understand why virtual MCPs enable dynamic configuration and how they differ from external MCP servers. --- -Decopilot represents a new approach to AI-assisted development—web-native, MCP-first, and built on the foundation of virtual MCPs. By operating exclusively on virtual MCPs, it can dynamically reshape the environment as it works, providing capabilities that traditional filesystem-based assistants cannot match. +Decopilot represents a new approach to MCP orchestration—**HTTP-based, MCP-first, and built on distributed architecture**. By operating through virtual MCPs and coordinating across external MCP servers, decopilot delivers the proven agentic loop pattern as an MCP orchestration layer. This is the agentic assistant that runs on decocms. diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx new file mode 100644 index 0000000000..ee764885b7 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx @@ -0,0 +1,596 @@ +--- +title: Quick Start +description: Practical workflows showing decopilot's agentic loop in action +icon: Rocket +--- + +import Callout from "../../../../components/ui/Callout.astro"; + +This guide shows practical decopilot workflows with the **agentic loop** in action. Each workflow demonstrates how decopilot gathers context from distributed MCP servers, takes coordinated actions, and verifies results—all while adapting based on scope. + + +These workflows adapt based on scope (org/project/agent). Learn more in [Scopes](/en/mcp-mesh/decopilot/scopes). + + +## Prerequisites + +Before starting, you'll need: + +- **Access to a decocms organization**: With permission to create and modify projects +- **At least one project with connected MCP servers**: GitHub is recommended for these examples +- **Basic MCP familiarity**: Understanding of tools, resources, and the MCP protocol helps but isn't required + +If you haven't set up MCP servers yet, see [Connections](/en/mcp-mesh/connections). + +## Workflow 1: Creating a Pull Request + +This workflow shows the complete agentic loop with an external MCP server (GitHub). + +### The Request + +You're working in a project and ready to create a pull request for your feature: + +``` +User: "Create a PR for the authentication feature" +``` + +### Step 1: Gather Context + +Decopilot begins by gathering context from the GitHub MCP: + +```typescript +// Decopilot internally: +// 1. Check current branch state +const branch = await GIT_BRANCH_STATUS({ repo: "mobile-app" }) +// => { name: "feature/biometric-auth", ahead: 5, behind: 0 } + +// 2. Review recent commits +const commits = await GIT_LOG({ repo: "mobile-app", limit: 5 }) +// => [ +// { sha: "abc123", message: "Add biometric scanner component" }, +// { sha: "def456", message: "Implement face recognition flow" }, +// ... +// ] + +// 3. Check for uncommitted changes +const status = await GIT_STATUS({ repo: "mobile-app" }) +// => { modified: [], staged: [], untracked: [] } +``` + +**Learning point**: Decopilot queries the GitHub MCP to understand the current state before taking action. This ensures the PR creation is context-aware. + +### Step 2: Take Action + +With context gathered, decopilot searches for and enables the appropriate tool: + +```typescript +// 1. Search for GitHub tools related to PRs +const tools = await tools_search({ + search_term: "pull request github", + scope: "project" +}) +// => [ +// { name: "CREATE_PR", description: "Create a pull request on GitHub" }, +// { name: "UPDATE_PR", description: "Update existing pull request" }, +// ... +// ] + +// 2. Enable the CREATE_PR tool +await tool_enable({ tool_name: "CREATE_PR" }) + +// 3. Create PR with context-aware description +await CREATE_PR({ + repo: "mobile-app", + title: "Add biometric authentication", + body: `## Summary +- Implemented biometric scanner component +- Added face recognition flow +- Integrated with iOS/Android APIs + +## Testing +- Tested on iPhone 14 Pro with Face ID +- Tested on Pixel 7 with fingerprint scanner`, + base: "main", + head: "feature/biometric-auth" +}) +``` + +**Learning point**: The discover → enable → use pattern is fundamental to decopilot's tool workflow. Tools from external MCPs must be enabled before use. + +### Step 3: Verify Results + +Decopilot confirms the PR was created successfully: + +```typescript +// Check PR creation result +// => { +// success: true, +// pr_number: 142, +// url: "https://github.com/org/mobile-app/pull/142" +// } + +// Report to user +"✓ Created PR #142: Add biometric authentication + View: https://github.com/org/mobile-app/pull/142" +``` + +**Learning point**: The agentic loop doesn't stop at execution—decopilot verifies success and reports meaningful results. + +### The Complete Loop + +```mermaid +sequenceDiagram + participant User + participant Decopilot + participant GitHub_MCP + + User->>Decopilot: "Create a PR for the auth feature" + + Note over Decopilot: GATHER CONTEXT + Decopilot->>GitHub_MCP: GIT_BRANCH_STATUS + GitHub_MCP-->>Decopilot: feature/biometric-auth (5 commits ahead) + Decopilot->>GitHub_MCP: GIT_LOG + GitHub_MCP-->>Decopilot: Recent commits + Decopilot->>GitHub_MCP: GIT_STATUS + GitHub_MCP-->>Decopilot: No uncommitted changes + + Note over Decopilot: TAKE ACTION + Decopilot->>Decopilot: tools_search("pull request") + Decopilot->>Decopilot: tool_enable("CREATE_PR") + Decopilot->>GitHub_MCP: CREATE_PR(...) + GitHub_MCP-->>Decopilot: PR #142 created + + Note over Decopilot: VERIFY RESULTS + Decopilot-->>User: ✓ Created PR #142 (link) +``` + +## Workflow 2: Spawning a Security Review Agent + +This workflow demonstrates agent spawning for parallel work with isolated context. + +### The Request + +You're implementing a feature and want security review to happen in parallel: + +``` +User: "Add biometric authentication and run security review" +``` + +### Main Loop: Implementation + +Decopilot begins implementation in the main context: + +```typescript +// Main decopilot loop +// 1. Plan implementation approach +const plan = await resource_read({ + uri: "project://mobile-app/architecture-decisions" +}) + +// 2. Check existing auth infrastructure +const authFiles = await tools_search({ + search_term: "authentication", + scope: "project" +}) + +// 3. Spawn security agent on parallel task +const agentTask = await agent_spawn({ + agent_id: "security-reviewer", + task: "Review biometric authentication implementation for security vulnerabilities", + context: { + files: ["src/auth/biometric.ts", "src/auth/face-recognition.ts"], + focus: "authentication security" + } +}) +// => { task_id: "task-abc123", status: "in_progress" } +``` + +**Learning point**: Agent spawning happens early in the workflow, allowing parallel execution while the main loop continues. + +### Spawned Agent: Security Review + +The spawned agent runs with **fresh context**, isolated from the main loop: + +```typescript +// Inside security-reviewer agent (isolated context) +// Agent has bounded tool access: security scanning, CVE lookup, file reading + +// 1. Gather context - read security checklist +const checklist = await resource_read({ + uri: "agent://security-reviewer/checklist" +}) + +// 2. Take action - scan authentication files +const scanResults = await SECURITY_SCAN({ + files: ["src/auth/biometric.ts", "src/auth/face-recognition.ts"], + rules: ["auth", "crypto", "input-validation"] +}) + +// 3. Check known vulnerabilities +const cveResults = await CVE_LOOKUP({ + dependencies: ["face-api.js", "biometric-sdk"] +}) + +// 4. Generate findings report +const findings = { + critical: [], + high: [ + "Biometric templates stored without encryption", + "Face recognition threshold too permissive (0.5)" + ], + medium: [ + "Missing rate limiting on auth attempts" + ], + info: [ + "Consider implementing liveness detection" + ] +} + +// Agent completes and returns findings +return { status: "completed", findings } +``` + +**Learning point**: The agent operates in an isolated context with only the tools it needs. This prevents token bloat and enables focused analysis. + +### Main Loop: Integration + +Back in the main loop, decopilot integrates the findings: + +```typescript +// Main loop continues +// 1. Complete implementation +await tool_enable({ tool_name: "CREATE_FILE" }) +await CREATE_FILE({ + path: "src/auth/biometric.ts", + content: "// Implementation..." +}) + +// 2. Check agent task status +const agentResult = await agent_task_status({ task_id: "task-abc123" }) +// => { status: "completed", findings: { ... } } + +// 3. Update implementation based on findings +await tool_enable({ tool_name: "UPDATE_FILE" }) +await UPDATE_FILE({ + path: "src/auth/biometric.ts", + changes: [ + "Encrypt biometric templates with AES-256", + "Increase face recognition threshold to 0.7", + "Add rate limiting middleware" + ] +}) + +// 4. Create resource documenting findings +await resource_create({ + uri: "project://mobile-app/security-findings-2024-02", + name: "Security Review: Biometric Auth", + content: JSON.stringify(agentResult.findings, null, 2) +}) +``` + +**Learning point**: The main loop continues working while the agent runs, then integrates results when ready. This is efficient parallel execution. + +### The Complete Flow + +```mermaid +graph TB + A[User Request] --> B[Main Loop: Plan Implementation] + B --> C[Spawn Security Agent] + B --> D[Continue Implementation] + + C --> E[Agent: Fresh Context] + E --> F[Agent: Scan Files] + F --> G[Agent: Check CVEs] + G --> H[Agent: Generate Findings] + + D --> I[Main: Complete Implementation] + H --> J[Main: Integrate Findings] + I --> J + J --> K[Main: Update Code] + K --> L[Main: Document Results] +``` + +## Workflow 3: Multi-Server Orchestration + +This workflow shows coordination across multiple MCP servers in a single operation. + +### The Request + +You need to set up a feature branch across multiple services: + +``` +User: "Create feature branch, export Figma assets, and notify the team" +``` + +### The Agentic Loop + +Decopilot orchestrates across three MCP servers: + +```typescript +// GATHER CONTEXT + +// 1. Check GitHub repository state +const repo = await GIT_BRANCH_STATUS({ repo: "mobile-app" }) +// => { name: "main", clean: true } + +// 2. Check Figma for latest designs +const figmaFile = await FIGMA_GET_FILE({ file_id: "mobile-app-designs" }) +// => { last_modified: "2024-02-08", version: "1.42" } + +// 3. Check Slack channel for previous notifications +const history = await SLACK_GET_HISTORY({ + channel: "engineering", + limit: 10 +}) +// => [...recent messages] + +// TAKE ACTION + +// 1. GitHub MCP - Create feature branch +await tool_enable({ tool_name: "CREATE_BRANCH" }) +const branch = await CREATE_BRANCH({ + repo: "mobile-app", + name: "feature/new-onboarding", + base: "main" +}) +// => { success: true, branch: "feature/new-onboarding" } + +// 2. Figma MCP - Export design assets +await tool_enable({ tool_name: "EXPORT_ASSETS" }) +const assets = await EXPORT_ASSETS({ + file_id: "mobile-app-designs", + node_ids: ["onboarding-flow", "welcome-screen"], + format: "svg", + scale: 2 +}) +// => { +// success: true, +// files: [ +// { name: "onboarding-flow.svg", url: "..." }, +// { name: "welcome-screen.svg", url: "..." } +// ] +// } + +// 3. Slack MCP - Notify team +await tool_enable({ tool_name: "SEND_MESSAGE" }) +const notification = await SEND_MESSAGE({ + channel: "engineering", + text: `🚀 Started new onboarding feature +Branch: feature/new-onboarding +Figma assets: ${assets.files.length} files exported +Design version: 1.42` +}) +// => { success: true, timestamp: "1707398400" } + +// VERIFY RESULTS + +// Confirm all operations succeeded +const results = { + github: branch.success, // ✓ + figma: assets.success, // ✓ + slack: notification.success // ✓ +} + +// Report to user +"✓ Feature setup complete: + • Branch created: feature/new-onboarding + • Exported 2 Figma assets + • Team notified in #engineering" +``` + +**Learning point**: Decopilot coordinates multiple MCP servers in a single workflow. Each server is called through the MCP protocol (HTTP for remote, stdio for local), with decopilot orchestrating the sequence. + +### Distributed Architecture in Action + +```mermaid +graph LR + Decopilot --> GitHub[GitHub MCP
HTTP] + Decopilot --> Figma[Figma MCP
HTTP] + Decopilot --> Slack[Slack MCP
HTTP] + + GitHub --> Branch[Create Branch] + Figma --> Assets[Export Assets] + Slack --> Notify[Send Message] +``` + +**Learning point**: This is the distributed MCP architecture in action—web-native coordination across multiple services through standardized protocol. + +## Workflow 4: Dynamic Tool Creation + +This workflow demonstrates decopilot's ability to edit virtual MCPs by creating tools on the fly. + +### The Request + +You need a custom tool for a project-specific operation: + +``` +User: "We need a tool to run the mobile test suite on all platforms" +``` + +### The Agentic Loop + +Decopilot operates on the project's virtual MCP to create an inline tool: + +```typescript +// GATHER CONTEXT + +// 1. Check existing test infrastructure +const testTools = await tools_search({ + search_term: "test", + scope: "project" +}) +// => [ +// { name: "RUN_TESTS", description: "Run test suite for a platform" }, +// { name: "TEST_RESULTS", description: "Get test results" } +// ] + +// 2. Read project testing documentation +const testDocs = await resource_read({ + uri: "project://mobile-app/testing-guide" +}) + +// TAKE ACTION + +// 1. Create inline tool in project virtual MCP +await tool_create({ + name: "RUN_MOBILE_TESTS_ALL_PLATFORMS", + description: "Run complete mobile test suite on iOS and Android", + inputSchema: { + type: "object", + properties: { + suite: { + type: "string", + enum: ["unit", "integration", "e2e", "all"], + description: "Test suite to run" + } + } + }, + implementation: { + type: "workflow", + steps: [ + { + tool: "RUN_TESTS", + input: { platform: "ios", suite: "{{input.suite}}" } + }, + { + tool: "RUN_TESTS", + input: { platform: "android", suite: "{{input.suite}}" } + } + ] + } +}) + +// 2. Enable the newly created tool +await tool_enable({ tool_name: "RUN_MOBILE_TESTS_ALL_PLATFORMS" }) + +// 3. Use it immediately +const results = await RUN_MOBILE_TESTS_ALL_PLATFORMS({ + suite: "integration" +}) +// => { +// ios: { passed: 142, failed: 0, skipped: 3 }, +// android: { passed: 138, failed: 2, skipped: 7 } +// } + +// VERIFY RESULTS + +// Check test outcomes +const summary = { + ios: results.ios.failed === 0 ? "✓ Pass" : "✗ Fail", + android: results.android.failed === 0 ? "✓ Pass" : "✗ Fail" +} + +// Report to user +"✓ Created RUN_MOBILE_TESTS_ALL_PLATFORMS tool + Results: + • iOS: ✓ Pass (142/145 tests) + • Android: ✗ Fail (138/147 tests, 2 failures)" +``` + +**Learning point**: Decopilot can create tools in virtual MCPs and use them immediately. This is only possible because projects are virtual MCPs—editable and configurable. + +### Virtual MCP Editability + +```mermaid +graph TB + A[User Request] --> B[Gather: Check Existing Tools] + B --> C[Take Action: Create Inline Tool] + C --> D[Virtual MCP: Add Tool Definition] + D --> E[Enable Tool] + E --> F[Use Tool Immediately] + F --> G[Verify: Check Results] + + style D fill:#e1f5ff +``` + +**Learning point**: The virtual MCP is the editable layer. Decopilot operates on it to add tools, resources, and configuration—something impossible with external MCP servers. + +## Tips for Effective Use + +### 1. Leverage Scopes Appropriately + +**Org scope** for organization-wide setup: +- Connect external MCP servers (GitHub org, Slack workspace) +- Create shared resources (security policies, coding standards) +- Define org-level prompt templates + +**Project scope** for feature development: +- Use project-specific tools and resources +- Create inline tools for project operations +- Coordinate work across connected MCPs + +**Agent scope** for focused tasks: +- Delegate to specialized agents (security, testing, research) +- Benefit from fresh context and bounded tool access + +### 2. Spawn Agents Strategically + +**Good candidates for agent spawning**: +- Security reviews (parallel to implementation) +- Research tasks (exploring architecture, investigating bugs) +- Testing workflows (comprehensive test runs) +- Code quality checks (linting, formatting, documentation) + +**Keep in main loop**: +- Feature implementation (needs full context) +- User interactions (requires responsiveness) +- Sequential workflows (where order matters) + +### 3. Work with Virtual MCPs + +**Create resources** for documentation: +```typescript +await resource_create({ + uri: "project://mobile-app/architecture-decisions", + name: "Architecture Decisions", + content: "# ADRs\n\n..." +}) +``` + +**Create inline tools** for project operations: +```typescript +await tool_create({ + name: "DEPLOY_STAGING", + description: "Deploy to staging environment", + // ... +}) +``` + +**Update prompts** based on workflow patterns: +```typescript +await prompt_update({ + name: "code-review", + template: "Review this code for:\n- Security\n- Performance\n..." +}) +``` + +### 4. Monitor Task Status + +When spawning agents, check status: +```typescript +const status = await agent_task_status({ task_id: "task-abc123" }) +// => { status: "in_progress" | "completed" | "failed" } +``` + +Integrate results when ready: +```typescript +if (status.status === "completed") { + // Use agent findings +} +``` + +## Next Steps + +**[Scopes](/en/mcp-mesh/decopilot/scopes)**: Understand how org/project/agent scopes determine behavior and tool availability. Essential for effective decopilot use. + +**[Spawning Agents](/en/mcp-mesh/decopilot/spawning-agents)**: Learn advanced patterns for agent spawning, including fan-out/fan-in, conditional spawning, and agent selection. + +**[Tools](/en/mcp-mesh/decopilot/tools)**: Explore the comprehensive toolset, discover patterns, and troubleshoot common issues. + +**[Context Management](/en/mcp-mesh/decopilot/context-management)**: Optimize token usage through strategic agent spawning and context filtering. + +**[Architecture](/en/mcp-mesh/decopilot/architecture)**: Deep-dive into decopilot's technical implementation and distributed MCP coordination. + +--- + +You've seen the agentic loop in action across four practical workflows. Decopilot brings proven agentic patterns to web-based development through distributed MCP architecture—gather context, take coordinated actions, and verify results, all while adapting to scope. This is the foundation for state-of-the-art agentic workflows in decocms. diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx index 296893e997..c07f35225c 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx @@ -97,6 +97,310 @@ decopilot.listTools() // Agent: ["REVIEW_CODE", "ANALYZE_SECURITY", ...] ``` +## Practical Scope Workflows + +Understanding scope concepts is essential, but seeing them in action clarifies how they enable real work. Here are practical workflows demonstrating each scope type. + +### Workflow 1: Org-Level Setup + +**Context**: You're setting up organization-wide resources and connections. + +**Route**: `/:org/settings` + +**Operations**: + +```typescript +// 1. Create org-level CLAUDE.md with coding standards +await resource_create({ + uri: "org://coding-standards", + name: "CLAUDE.md", + content: `# Coding Standards + +## Style +- Use TypeScript strict mode +- Prefer functional patterns +- Document public APIs + +## Security +- Never commit credentials +- Validate all user input +- Use parameterized queries` +}) + +// 2. Connect external MCP servers at org level +await connection_create({ + name: "GitHub Organization", + type: "github", + scope: "org", + config: { + org: "my-company", + auth: "oauth" + } +}) + +await connection_create({ + name: "Slack Workspace", + type: "slack", + scope: "org", + config: { + workspace: "my-company", + channel_defaults: ["#engineering", "#deploys"] + } +}) + +// 3. Create shared security policy resource +await resource_create({ + uri: "org://security-policy", + name: "Security Policy", + content: `# Security Policy + +## Authentication +- Use OAuth 2.1 with PKCE +- Require MFA for production access + +## Data Handling +- Encrypt PII at rest and in transit +- Implement data retention policies` +}) + +// 4. Define org-wide prompt templates +await prompt_create({ + name: "code-review-template", + scope: "org", + template: `Review this code for: +1. Security vulnerabilities +2. Performance issues +3. Code style adherence +4. Test coverage` +}) +``` + +**Result**: Organization foundation established. All projects inherit these resources, connections, and prompts. + +### Workflow 2: Project Development + +**Context**: You're working on a mobile app project, coordinating across multiple services. + +**Route**: `/:org/projects/mobile-app` + +**Operations**: + +```typescript +// 1. Read project CLAUDE.md (inherits org + project-specific) +const guidelines = await resource_read({ + uri: "project://mobile-app/guidelines" +}) +// Returns: Org coding standards + project-specific patterns + +// 2. Use GitHub tools to create branch (via org GitHub connection) +await tool_enable({ tool_name: "CREATE_BRANCH" }) +await CREATE_BRANCH({ + repo: "mobile-app", + name: "feature/push-notifications", + base: "main" +}) + +// 3. Use Figma tools to export assets (via project Figma connection) +await tool_enable({ tool_name: "EXPORT_ASSETS" }) +await EXPORT_ASSETS({ + file_id: "mobile-app-designs", + node_ids: ["notification-icons"], + format: "svg" +}) + +// 4. Create project resource for architecture decisions +await resource_create({ + uri: "project://mobile-app/architecture-decisions", + name: "Architecture Decision: Push Notifications", + content: `# ADR: Push Notifications + +## Decision +Use Firebase Cloud Messaging (FCM) for cross-platform push. + +## Rationale +- Native iOS/Android support +- Reliable delivery +- Cost effective at scale + +## Alternatives Considered +- OneSignal (3rd party dependency) +- Native APNS/GCM (platform-specific complexity)` +}) + +// 5. Spawn security agent for review +await agent_spawn({ + agent_id: "security-reviewer", + task: "Review push notification implementation for security", + context: { + files: ["src/notifications/push.ts"], + focus: "credential storage, message encryption" + } +}) +``` + +**Result**: Feature developed with project-specific context, coordinating GitHub, Figma, and security review—all scoped to the project. + +### Workflow 3: Agent Execution + +**Context**: A spawned security agent is reviewing code with bounded capabilities. + +**Route**: `/:org/agents/security-reviewer` + +**Operations**: + +```typescript +// 1. Read agent-specific checklist resource +const checklist = await resource_read({ + uri: "agent://security-reviewer/checklist" +}) +// Returns: Security-specific checklist, not full project context + +// 2. Use bounded tools for security scanning +await tool_enable({ tool_name: "SECURITY_SCAN" }) +const scanResults = await SECURITY_SCAN({ + files: ["src/notifications/push.ts"], + rules: ["credential-exposure", "insecure-storage", "xss"] +}) +// => { +// findings: [ +// { +// severity: "high", +// rule: "credential-exposure", +// message: "FCM server key hardcoded on line 42" +// } +// ] +// } + +// 3. Check known vulnerabilities +await tool_enable({ tool_name: "CVE_LOOKUP" }) +const cveResults = await CVE_LOOKUP({ + dependencies: ["firebase-admin", "node-notifier"] +}) + +// 4. Generate findings report (can't modify project resources) +return { + status: "completed", + findings: { + critical: ["FCM server key hardcoded"], + high: [], + medium: ["Consider rate limiting push notifications"], + info: ["Update firebase-admin to latest version"] + } +} +``` + +**Result**: Security analysis completed with fresh context and bounded tools. Agent cannot modify project resources—only reads and returns findings. + +## Scope Transitions + +When you navigate between routes, decopilot automatically transitions between scopes. Understanding these transitions helps you predict behavior. + +### Org → Project Transition + +```typescript +// Before: /:org/settings (Org scope) +await tools_list() +// => ["ORG_CONNECTION_CREATE", "ORG_RESOURCE_CREATE", ...] + +// Navigate to: /:org/projects/mobile-app + +// After: /:org/projects/mobile-app (Project scope) +await tools_list() +// => [ +// // Inherited org tools +// "ORG_CONNECTION_CREATE", +// // Project-specific tools +// "CREATE_PR", "EXPORT_ASSETS", "RUN_TESTS", +// // Inline project tools +// "RUN_MOBILE_TESTS_ALL_PLATFORMS" +// ] +``` + +**What changes**: +- Context switches from org to project virtual MCP +- Tool availability updates (adds project + external MCP tools) +- Resource inheritance recalculates (org resources + project resources) +- Connected MCPs refresh (org connections + project connections) + +### Project → Agent Transition + +```typescript +// Before: /:org/projects/mobile-app (Project scope) +await tools_list() +// => ["CREATE_PR", "EXPORT_ASSETS", "RUN_TESTS", ...] + +// Spawn agent: agent_spawn({ agent_id: "security-reviewer", ... }) + +// Inside agent: /:org/agents/security-reviewer (Agent scope) +await tools_list() +// => [ +// // Only bounded agent tools +// "SECURITY_SCAN", "CVE_LOOKUP", "CODE_ANALYSIS" +// ] +``` + +**What changes**: +- Context switches to isolated agent virtual MCP +- Tool availability dramatically narrows (bounded to agent purpose) +- Resources limited to agent-specific only (no automatic project inheritance) +- Fresh token context (no pollution from parent scope) + +**Key insight**: Agent scope is intentionally restricted. This prevents agents from accidentally modifying project state and keeps their context focused. + +## When to Use Each Scope + +Knowing which scope to operate in for different tasks improves efficiency and organization. + +### Use Org Scope When: + +**Setting up infrastructure**: +- Connecting external MCP servers (GitHub org, Slack workspace, Figma teams) +- Creating organization-wide resources (coding standards, security policies) +- Defining shared prompt templates +- Managing organization members and permissions + +**Example tasks**: +- "Connect our GitHub organization" +- "Create org-wide coding standards" +- "Set up Slack integration for all projects" + +### Use Project Scope When: + +**Developing features**: +- Creating branches, pull requests, commits +- Coordinating work across multiple services (GitHub + Figma + Slack) +- Creating project-specific resources (architecture decisions, test plans) +- Using connected MCP tools for project work + +**Example tasks**: +- "Create a PR for the authentication feature" +- "Export Figma assets for the onboarding flow" +- "Run the mobile test suite on all platforms" +- "Document the architecture decision for push notifications" + +### Use Agent Scope When: + +**Running focused, repeatable tasks**: +- Security reviews with specialized scanning +- Code quality analysis with bounded tools +- Research tasks exploring specific architecture +- Testing workflows with dedicated test runners + +**Example tasks**: +- "Review this authentication code for security vulnerabilities" +- "Analyze performance of the notification service" +- "Research state management patterns in the codebase" +- "Run comprehensive integration tests" + +**Decision rule**: If the task needs full project context and multiple services, use project scope. If the task is focused, repeatable, and benefits from isolation, spawn an agent. + + +Start in project scope for most work. Spawn agents when you need: +- **Parallel execution** (security review while implementing) +- **Fresh context** (researching architecture without bloat) +- **Bounded capabilities** (testing, analysis, review tasks) + + ## Virtual MCPs at Every Level **Everything in decocms is a virtual MCP**. Orgs, projects, and agents are all virtual MCPs with tools, resources, prompts, and configuration. The scope hierarchy creates an inheritance model where projects and agents access org-level capabilities while maintaining their own scope-specific additions. diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx index 341bc78d76..557186c9d7 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx @@ -59,6 +59,62 @@ const taskId = await decopilot.invokeTool("agent_spawn", { The spawned task runs independently. Parent doesn't block—results return when task completes. +### Complete Spawn Lifecycle Example + +Understanding the full lifecycle from spawn to completion helps predict behavior and handle edge cases. + +```typescript +// T0: Parent task spawns security agent +const taskId = await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer", + prompt: "Review src/auth/biometric.ts for security vulnerabilities" +}) +// Returns immediately: { task_id: "task-abc-123" } +// Task status: "active" + +// T1: Spawned agent starts executing +// - Loads agent virtual MCP configuration +// - Reads CLAUDE.md (org + project context) +// - Reads AGENTS.md (agent-specific instructions) +// - Receives prompt as initial message +// - Begins agentic loop (gather → act → verify) + +// T2: Agent discovers and enables tools +await tools_search({ search_term: "security" }) +await tool_enable({ tool_name: "SECURITY_SCAN" }) + +// T3: Agent invokes tools +const scanResults = await SECURITY_SCAN({ + files: ["src/auth/biometric.ts"], + rules: ["credential-exposure", "insecure-storage"] +}) + +// T4: Agent generates response +// Response includes findings, recommendations, severity levels +// Task status transitions: "active" -> "successful" + +// T5: Parent task receives result notification +// Result integrated as ~200-500 token summary: +// "Security review complete. Found 2 high-severity issues: +// 1. Biometric templates stored without encryption (line 42) +// 2. Auth threshold too permissive (line 68) +// See full report in task-abc-123" + +// T6: Parent continues with integrated findings +await resource_create({ + uri: "project://mobile-app/security-findings", + name: "Security Review: Biometric Auth", + content: scanResults.report +}) +``` + +**Key lifecycle points**: +- Spawn returns immediately (non-blocking) +- Agent loads isolated context +- Agent executes autonomously +- Results integrate as summaries +- Parent task continues throughout + ## Task States and Lifecycle **Active**: Task being processed by agent. @@ -135,6 +191,153 @@ const result = await decopilot.invokeTool("agent_search", { Specialized agents optimize for their purpose and produce better results. +## Choosing the Right Agent + +Selecting the appropriate agent for your task improves results and reduces iteration. Different agent types excel at different work. + +### Research Agents + +**Best for**: +- Exploring codebases and understanding architecture +- Investigating bugs and tracing execution paths +- Analyzing options before making decisions +- Understanding third-party libraries and APIs + +**Characteristics**: +- Read-heavy tool access (file reading, code search, documentation lookup) +- No write permissions (safe for exploratory work) +- Fresh context ideal for deep dives + +**Example usage**: +```typescript +await decopilot.invokeTool("agent_spawn", { + agent_id: "research-agent", + prompt: "Analyze the authentication flow in src/auth/. Map the complete user login journey from form submission to session creation." +}) +``` + +### Development Agents + +**Best for**: +- Implementing features based on specifications +- Writing code with clear requirements +- Refactoring existing code +- Adding tests for new functionality + +**Characteristics**: +- Read and write tool access (file editing, code generation) +- Focused on implementation, not exploration +- Benefits from clear specs and acceptance criteria + +**Example usage**: +```typescript +await decopilot.invokeTool("agent_spawn", { + agent_id: "development-agent", + prompt: "Implement push notification service using Firebase Cloud Messaging. Requirements: support iOS and Android, handle background notifications, respect user preferences." +}) +``` + +### Review Agents + +**Best for**: +- Code quality analysis +- Security vulnerability scanning +- Performance profiling +- Accessibility auditing + +**Characteristics**: +- Specialized analysis tools (linters, security scanners, profilers) +- Domain expertise in specific review type +- Generate structured findings reports + +**Example usage**: +```typescript +await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer", + prompt: "Review src/auth/biometric.ts for security issues. Focus on credential storage, authentication bypass risks, and biometric data handling. Report findings with severity levels." +}) +``` + +### Testing Agents + +**Best for**: +- Writing unit tests for new code +- Creating integration tests +- Running test suites and analyzing failures +- Generating test data + +**Characteristics**: +- Test framework tools (Jest, Pytest, etc.) +- Coverage analysis capabilities +- Can execute tests and interpret results + +**Example usage**: +```typescript +await decopilot.invokeTool("agent_spawn", { + agent_id: "testing-agent", + prompt: "Write comprehensive unit tests for src/notifications/push.ts. Cover success cases, error handling, edge cases. Aim for 90%+ coverage." +}) +``` + +### Deployment Agents + +**Best for**: +- Releasing features to staging/production +- Infrastructure configuration +- Deployment verification +- Rollback procedures + +**Characteristics**: +- Deployment pipeline tools (kubectl, terraform, CI/CD) +- Environment-specific configurations +- Health check and monitoring capabilities + +**Example usage**: +```typescript +await decopilot.invokeTool("agent_spawn", { + agent_id: "deployment-agent", + prompt: "Deploy feature/push-notifications to staging. Run health checks. Monitor for 5 minutes. Report deployment status and any errors." +}) +``` + +### Decision Guide + +Use this flowchart to choose the right agent: + +``` +Need to understand code? → Research Agent + ├─ Exploring architecture + ├─ Investigating bugs + └─ Analyzing options + +Need to write code? → Development Agent + ├─ Implementing features + ├─ Refactoring + └─ Adding tests + +Need to check quality? → Review Agent + ├─ Security scan → Security Reviewer + ├─ Performance → Performance Analyzer + └─ Accessibility → Accessibility Checker + +Need to test? → Testing Agent + ├─ Unit tests + ├─ Integration tests + └─ Test execution + +Need to deploy? → Deployment Agent + ├─ Staging release + ├─ Production deploy + └─ Rollback +``` + +**Pro tip**: When unsure, use `agent_search` with descriptive terms to find specialized agents: +```typescript +await decopilot.invokeTool("agent_search", { + search_term: "security vulnerability scanning" +}) +``` + ## UI Integration and Task Management **Tasks menu**: Shows all tasks for current scope with status indicators. @@ -200,6 +403,225 @@ const testTaskId = await decopilot.invokeTool("agent_spawn", { }) ``` +## Advanced Spawning Patterns + +Beyond basic single or parallel spawning, these advanced patterns enable sophisticated workflows. + +### Pattern 1: Fan-out/Fan-in + +Spawn multiple agents for parallel work, then collect and synthesize results. + +```typescript +// Fan-out: Spawn multiple review agents +const securityTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer", + prompt: "Security audit of src/auth/" +}) + +const performanceTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "performance-analyzer", + prompt: "Performance analysis of src/auth/" +}) + +const accessibilityTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "accessibility-checker", + prompt: "Accessibility audit of auth UI" +}) + +// All three tasks run in parallel, each with isolated context + +// Fan-in: Collect results (after tasks complete) +// Results integrate as summaries +// Parent synthesizes findings: + +await resource_create({ + uri: "project://mobile-app/auth-review-summary", + name: "Authentication Review Summary", + content: `# Authentication Review + +## Security +${securityTaskResults} + +## Performance +${performanceTaskResults} + +## Accessibility +${accessibilityTaskResults} + +## Action Items +[Synthesized priorities based on all findings]` +}) +``` + +**When to use**: Comprehensive analysis requiring multiple specialized perspectives. Each agent brings domain expertise. + +**Benefits**: +- Parallel execution (faster than sequential) +- Isolated contexts (no cross-contamination) +- Specialized focus (each agent optimized) + +### Pattern 2: Conditional Spawning + +Spawn agents based on runtime conditions or previous task results. + +```typescript +// Step 1: Research implementation options +const researchTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "research-agent", + prompt: "Research React state management options. Compare Redux, Zustand, Jotai. Recommend best fit for our architecture." +}) + +// Step 2: Wait for research completion +// (In practice, decopilot integrates results automatically) + +// Step 3: Conditional spawn based on recommendation +if (researchResults.recommendation === "Zustand") { + // Spawn Zustand implementation agent + await decopilot.invokeTool("agent_spawn", { + agent_id: "development-agent", + prompt: "Implement Zustand store following the research recommendations. Focus on user state management." + }) +} else if (researchResults.recommendation === "Redux") { + // Spawn Redux implementation agent + await decopilot.invokeTool("agent_spawn", { + agent_id: "development-agent", + prompt: "Implement Redux store with Redux Toolkit following best practices." + }) +} + +// Step 4: Always spawn testing agent after implementation +await decopilot.invokeTool("agent_spawn", { + agent_id: "testing-agent", + prompt: "Write comprehensive tests for the state management implementation." +}) +``` + +**When to use**: Multi-stage workflows where later steps depend on earlier results. + +**Benefits**: +- Adaptive workflows (adjust based on findings) +- Efficient resource use (only spawn what's needed) +- Clear decision points + +### Pattern 3: Iterative Refinement + +Spawn agents in a loop to refine results based on quality checks. + +```typescript +// Iteration 1: Initial implementation +let implementationTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "development-agent", + prompt: "Implement biometric authentication with Face ID support" +}) + +// Quality check +const qualityTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer", + prompt: "Review biometric implementation. Check for security issues." +}) + +// Iteration 2: If issues found, refine +if (qualityResults.criticalIssues.length > 0) { + implementationTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "development-agent", + prompt: `Refine biometric implementation addressing: +${qualityResults.criticalIssues.map(issue => `- ${issue}`).join('\n')} + +Focus on security and correctness.` + }) + + // Re-check quality + await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer", + prompt: "Re-review refined implementation. Verify issues addressed." + }) +} +``` + +**When to use**: Quality-critical work requiring validation and refinement cycles. + +**Benefits**: +- Ensures quality standards met +- Fresh context for each iteration +- Clear validation checkpoints + +### Pattern 4: Pipeline Architecture + +Chain agents in a processing pipeline where each stage adds value. + +```typescript +// Stage 1: Research +const researchTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "research-agent", + prompt: "Research push notification best practices. Document patterns." +}) + +// Stage 2: Implement (uses research findings) +const implementTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "development-agent", + prompt: "Implement push notifications using research findings. Follow documented patterns." +}) + +// Stage 3: Test (validates implementation) +const testTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "testing-agent", + prompt: "Write integration tests for push notification system. Test all platforms." +}) + +// Stage 4: Review (ensures quality) +const reviewTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer", + prompt: "Security review of push notification implementation. Check credential handling." +}) + +// Stage 5: Document (captures knowledge) +const docTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "documentation-agent", + prompt: "Document push notification system: setup, usage, troubleshooting." +}) + +// Each stage builds on previous work, creating comprehensive delivery +``` + +**When to use**: Complex features requiring multiple specialized stages (research → implement → test → review → document). + +**Benefits**: +- Clear separation of concerns +- Each agent focuses on one aspect +- Comprehensive feature delivery +- Knowledge capture throughout + +### Pattern 5: Hierarchical Delegation + +Spawn a coordinator agent that spawns its own sub-agents (requires enabling `agent_spawn` in child tasks). + +```typescript +// Top-level: Spawn feature coordinator +const coordinatorTask = await decopilot.invokeTool("agent_spawn", { + agent_id: "feature-coordinator", + prompt: "Coordinate implementation of complete authentication system: backend API, frontend UI, testing, documentation.", + allowChildSpawn: true // Enable agent_spawn in child task +}) + +// Coordinator spawns sub-agents: +// - backend-agent for API implementation +// - frontend-agent for UI components +// - testing-agent for test suites +// - documentation-agent for docs + +// Coordinator manages dependencies and integration +// Top-level task receives final coordinated result +``` + +**When to use**: Very complex features requiring orchestration of multiple work streams. + +**Caution**: Increases complexity. Use sparingly and only when clear coordination benefits exist. + +**Benefits**: +- Distributes coordination responsibility +- Enables complex multi-agent workflows +- Maintains context isolation + ## Best Practices **Choose appropriate agents**: Match agent capabilities to task requirements. Specialized agents produce better results. diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx index 2740b0af30..4042b15ef9 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx @@ -775,6 +775,105 @@ await decopilot.invokeTool("CREATE_PR", { }) ``` +### Common Patterns + +Understanding common tool usage patterns improves efficiency and reduces errors. + +#### Pattern 1: Discover-Enable-Use + +The most common pattern for working with target virtual MCP tools: + +```typescript +// 1. Discover what's available +const tools = await decopilot.invokeTool("tools_search", { + search_term: "github" +}) +// => [{ name: "CREATE_PR", enabled: false }, { name: "CREATE_BRANCH", enabled: false }] + +// 2. Enable the specific tool needed +await decopilot.invokeTool("tool_enable", { + tool_name: "CREATE_PR" +}) + +// 3. Use the enabled tool +await decopilot.invokeTool("CREATE_PR", { + title: "Add feature", + body: "Feature description", + base: "main", + head: "feature/new-feature" +}) +``` + +**When to use**: Default pattern for any target virtual MCP tool. Always follow this sequence. + +#### Pattern 2: Explore-Then-Enable + +When you're not sure what capabilities exist, explore first: + +```typescript +// 1. List all available tools +const allTools = await decopilot.invokeTool("tools_search", {}) + +// 2. Read details for promising tools +const prDetails = await decopilot.invokeTool("tools_read", { + tool_name: "CREATE_PR" +}) +console.log("Input schema:", prDetails.inputSchema) + +const issueDetails = await decopilot.invokeTool("tools_read", { + tool_name: "CREATE_ISSUE" +}) +console.log("Input schema:", issueDetails.inputSchema) + +// 3. Enable the right tool for your task +await decopilot.invokeTool("tool_enable", { + tool_name: "CREATE_ISSUE" +}) + +// 4. Use it +await decopilot.invokeTool("CREATE_ISSUE", { + title: "Bug: Login fails on iOS", + body: "Steps to reproduce..." +}) +``` + +**When to use**: When you're exploring a new project or unfamiliar MCP server. Take time to understand available tools before committing. + +#### Pattern 3: Multi-Tool Workflow + +Enable multiple tools for complex workflows: + +```typescript +// Enable all tools you'll need upfront +await decopilot.invokeTool("tool_enable", { tool_name: "CREATE_BRANCH" }) +await decopilot.invokeTool("tool_enable", { tool_name: "COMMIT_CHANGES" }) +await decopilot.invokeTool("tool_enable", { tool_name: "CREATE_PR" }) +await decopilot.invokeTool("tool_enable", { tool_name: "SEND_MESSAGE" }) + +// Then orchestrate the workflow +await decopilot.invokeTool("CREATE_BRANCH", { + name: "feature/notification-system", + base: "main" +}) + +await decopilot.invokeTool("COMMIT_CHANGES", { + message: "Add push notification service", + files: ["src/notifications/push.ts"] +}) + +await decopilot.invokeTool("CREATE_PR", { + title: "Add push notification system", + body: "Implements FCM-based push notifications" +}) + +await decopilot.invokeTool("SEND_MESSAGE", { + channel: "engineering", + text: "PR ready for review: push notification system" +}) +``` + +**When to use**: Complex workflows spanning multiple services. Enable all tools first, then execute the workflow smoothly. + ### Complete Example: GitHub PR Creation ```typescript @@ -843,6 +942,207 @@ if (toolInfo.source === "external") { } ``` +## Tool Workflows by Use Case + +Practical examples showing tool usage patterns for common development tasks. + + +Check the [Quick Start](/en/mcp-mesh/decopilot/quickstart) for complete workflow examples with detailed context. + + +### Use Case 1: Code Review Workflow + +**Goal**: Create a PR and spawn a security review agent. + +**Tools needed**: `tools_search`, `tool_enable`, GitHub MCP tools, `agent_spawn` + +```typescript +// 1. Discover GitHub tools +const githubTools = await decopilot.invokeTool("tools_search", { + search_term: "github pull request" +}) + +// 2. Enable PR creation +await decopilot.invokeTool("tool_enable", { + tool_name: "CREATE_PR" +}) + +// 3. Create the PR +const pr = await decopilot.invokeTool("CREATE_PR", { + title: "Add biometric authentication", + body: "Implements face ID and fingerprint auth", + base: "main", + head: "feature/biometric-auth" +}) + +// 4. Spawn security agent for parallel review +await decopilot.invokeTool("agent_spawn", { + agent_id: "security-reviewer", + prompt: `Review PR #${pr.number} for security vulnerabilities. +Focus on: +- Credential storage +- Biometric data handling +- Authentication bypass risks` +}) + +// Main loop continues while agent reviews in parallel +``` + +**Key pattern**: Coordinate external MCP tools (GitHub) with built-in tools (agent spawning) for parallel workflows. + +### Use Case 2: Resource Management + +**Goal**: Create and organize project resources as you work. + +**Tools needed**: `resource_read`, `resource_edit` + +```typescript +// 1. Read existing architecture doc (if exists) +const existingArch = await decopilot.invokeTool("resource_read", { + uri: "project://mobile-app/architecture" +}).catch(() => null) // May not exist yet + +// 2. Create new architecture decision document +await decopilot.invokeTool("resource_edit", { + uri: "project://mobile-app/adr-001-push-notifications", + name: "ADR 001: Push Notifications", + content: `# ADR 001: Push Notification Strategy + +## Decision +Use Firebase Cloud Messaging for cross-platform push. + +## Rationale +- Native iOS/Android support +- Reliable delivery at scale +- Cost effective + +## Consequences +- Adds Firebase SDK dependency +- Requires Firebase project setup +- Lock-in to Google infrastructure`, + mimeType: "text/markdown", + operation: "create" +}) + +// 3. Update main architecture doc with reference +const updatedContent = existingArch + ? `${existingArch.content}\n\n## ADRs\n- [ADR 001: Push Notifications](project://mobile-app/adr-001-push-notifications)` + : `# Architecture\n\n## ADRs\n- [ADR 001: Push Notifications](project://mobile-app/adr-001-push-notifications)` + +await decopilot.invokeTool("resource_edit", { + uri: "project://mobile-app/architecture", + name: "Mobile App Architecture", + content: updatedContent, + operation: existingArch ? "update" : "create" +}) +``` + +**Key pattern**: Use resources to document decisions and maintain project knowledge. Resources persist across tasks and are inherited by spawned agents. + +### Use Case 3: Multi-Server Coordination + +**Goal**: Coordinate work across GitHub, Figma, and Slack in a single workflow. + +**Tools needed**: `tools_search`, `tool_enable`, tools from multiple external MCPs + +```typescript +// 1. Discover and enable tools from multiple sources +await decopilot.invokeTool("tool_enable", { tool_name: "CREATE_BRANCH" }) // GitHub +await decopilot.invokeTool("tool_enable", { tool_name: "EXPORT_ASSETS" }) // Figma +await decopilot.invokeTool("tool_enable", { tool_name: "SEND_MESSAGE" }) // Slack + +// 2. Create feature branch +await decopilot.invokeTool("CREATE_BRANCH", { + repo: "mobile-app", + name: "feature/new-onboarding", + base: "main" +}) + +// 3. Export Figma assets for the feature +const assets = await decopilot.invokeTool("EXPORT_ASSETS", { + file_id: "mobile-app-designs", + node_ids: ["onboarding-flow", "welcome-screen"], + format: "svg", + scale: 2 +}) + +// 4. Notify team with context +await decopilot.invokeTool("SEND_MESSAGE", { + channel: "engineering", + text: `🚀 Started new onboarding feature +Branch: feature/new-onboarding +Figma assets: ${assets.files.length} files exported +Ready for development` +}) +``` + +**Key pattern**: Decopilot orchestrates distributed MCP servers through a single workflow. Each tool invocation reaches the appropriate external MCP via the MCP protocol (HTTP for remote servers, stdio for local servers). + +### Use Case 4: Dynamic Tool Creation + +**Goal**: Create a project-specific tool for a recurring operation. + +**Tools needed**: `tools_edit`, `tool_enable`, composite workflow capability + +```typescript +// 1. Check existing tools for mobile testing +const testTools = await decopilot.invokeTool("tools_search", { + search_term: "test mobile" +}) + +// 2. Create composite tool that orchestrates existing tools +await decopilot.invokeTool("tools_edit", { + tool_name: "RUN_MOBILE_TESTS_ALL_PLATFORMS", + definition: { + description: "Run complete mobile test suite on iOS and Android", + inputSchema: { + type: "object", + properties: { + suite: { + type: "string", + enum: ["unit", "integration", "e2e", "all"], + description: "Test suite to run" + } + }, + required: ["suite"] + }, + outputSchema: { + type: "object", + properties: { + ios: { type: "object" }, + android: { type: "object" } + } + }, + handler: "composite", // Orchestrates other tools + workflow: [ + { tool: "RUN_TESTS", input: { platform: "ios", suite: "{{input.suite}}" } }, + { tool: "RUN_TESTS", input: { platform: "android", suite: "{{input.suite}}" } } + ] + }, + operation: "create" +}) + +// 3. Enable and use immediately +await decopilot.invokeTool("tool_enable", { + tool_name: "RUN_MOBILE_TESTS_ALL_PLATFORMS" +}) + +const results = await decopilot.invokeTool("RUN_MOBILE_TESTS_ALL_PLATFORMS", { + suite: "integration" +}) + +// 4. Save results as project resource +await decopilot.invokeTool("resource_edit", { + uri: "project://mobile-app/test-results-latest", + name: "Latest Test Results", + content: JSON.stringify(results, null, 2), + mimeType: "application/json", + operation: "create" +}) +``` + +**Key pattern**: Create inline tools to encapsulate project-specific operations. These tools become part of the project's virtual MCP and are available to all future tasks. + ## Scope-Specific Tool Behavior Examples This section provides concrete examples of how tools behave differently across scopes. @@ -1108,6 +1408,184 @@ const DEPLOY_STAGING_TOOL = { } ``` +## Troubleshooting Common Issues + +Common problems when working with decopilot tools and how to resolve them. + +### Issue: Tool Not Found + +**Symptoms**: `tools_search` doesn't return the expected tool, or `tool_enable` fails with "Tool not found". + +**Causes**: +1. Tool doesn't exist in current scope +2. Connected MCP server not properly configured +3. Wrong scope context (e.g., looking for project tool in org scope) + +**Solutions**: + +```typescript +// 1. List ALL available tools to verify existence +const allTools = await decopilot.invokeTool("tools_search", {}) +console.log("All available tools:", allTools) + +// 2. Check if you're in the right scope +// Navigate to /:org/projects/:id for project tools +// Navigate to /:org/settings for org tools + +// 3. Verify connection status for external MCP tools +// Check that GitHub, Slack, etc. are properly connected in settings + +// 4. Check tool source and scope +const toolInfo = await decopilot.invokeTool("tools_read", { + tool_name: "CREATE_PR" +}) +console.log("Tool source:", toolInfo.source) +``` + +**Prevention**: Always use `tools_search` to discover tools before attempting to enable them. Don't assume tools exist. + +### Issue: Tool Enable Fails + +**Symptoms**: `tool_enable` returns `{ success: false }` or throws an error. + +**Causes**: +1. Tool doesn't exist (see "Tool Not Found" above) +2. Insufficient permissions in current scope +3. External MCP server connection error + +**Solutions**: + +```typescript +// 1. Verify tool exists first +const tools = await decopilot.invokeTool("tools_search", { + search_term: "CREATE_PR" +}) + +if (tools.tools.length === 0) { + console.error("CREATE_PR tool not available in current scope") +} else { + // 2. Check tool details + const toolInfo = await decopilot.invokeTool("tools_read", { + tool_name: "CREATE_PR" + }) + console.log("Tool info:", toolInfo) + + // 3. Try enabling + const result = await decopilot.invokeTool("tool_enable", { + tool_name: "CREATE_PR" + }) + + if (!result.success) { + console.error("Enable failed. Check permissions and connection status") + } +} +``` + +**Prevention**: Check tool existence with `tools_search` before enabling. Verify external MCP connections are active. + +### Issue: Agent Spawn Blocked + +**Symptoms**: `agent_spawn` fails with "agent_spawn not available" or permission error. + +**Causes**: +1. Attempting to spawn from child task (agent-spawned task) +2. Agent doesn't exist in organization +3. Insufficient permissions to spawn agents + +**Solutions**: + +```typescript +// 1. Check if you're in a top-level task +// agent_spawn is disabled in child tasks by default + +// 2. Search for available agents +const agents = await decopilot.invokeTool("agent_search", { + search_term: "security" +}) +console.log("Available security agents:", agents) + +// 3. Use exact agent_id from search results +if (agents.agents.length > 0) { + await decopilot.invokeTool("agent_spawn", { + agent_id: agents.agents[0].agent_id, + prompt: "Review code for security issues" + }) +} else { + console.error("No security agents available") +} +``` + +**Prevention**: Always use `agent_search` to discover available agents. Only spawn from top-level tasks unless explicitly enabled. + +### Issue: Resource Not Found + +**Symptoms**: `resource_read` fails with "Resource not found" error. + +**Causes**: +1. Resource doesn't exist +2. Wrong URI format +3. Resource exists in different scope + +**Solutions**: + +```typescript +// 1. Check URI format +// Correct formats: +// - "org://org-slug/resource-name" +// - "project://project-slug/resource-name" +// - "agent://agent-id/resource-name" + +// 2. Try reading with proper URI +try { + const resource = await decopilot.invokeTool("resource_read", { + uri: "project://mobile-app/architecture" + }) + console.log("Resource found:", resource) +} catch (error) { + console.error("Resource doesn't exist. Creating...") + + // 3. Create the resource if it doesn't exist + await decopilot.invokeTool("resource_edit", { + uri: "project://mobile-app/architecture", + name: "Architecture", + content: "# Architecture\n\nInitial content...", + operation: "create" + }) +} +``` + +**Prevention**: Use consistent URI formats. Create resources explicitly rather than assuming they exist. + +### Issue: Scope Confusion + +**Symptoms**: Tools behave unexpectedly, or expected tools aren't available. + +**Causes**: +1. Misunderstanding current scope +2. Expecting project tools in org scope (or vice versa) +3. Scope inheritance not working as expected + +**Solutions**: + +```typescript +// 1. Always check what scope you're in based on route +// /:org/settings = Org scope +// /:org/projects/:id = Project scope +// /:org/agents/:id = Agent scope + +// 2. List available tools to understand current context +const tools = await decopilot.invokeTool("tools_search", {}) +console.log(`Available tools in current scope: ${tools.tools.length}`) + +// 3. Remember inheritance: project scope inherits from org, agent inherits from project+org +// Resources, prompts, and tools inherit automatically + +// 4. For scope-specific tools, navigate to the right route first +// Don't try to use project tools while in org scope +``` + +**Prevention**: Pay attention to which route you're on. Understand that scope determines tool availability and behavior. + ## Key Takeaways **Two tool categories**: Built-in tools (always available) and target virtual MCP tools (must be discovered and enabled). diff --git a/apps/docs/client/src/utils/navigation.ts b/apps/docs/client/src/utils/navigation.ts index c0da3e0f70..413098f493 100644 --- a/apps/docs/client/src/utils/navigation.ts +++ b/apps/docs/client/src/utils/navigation.ts @@ -15,23 +15,49 @@ export async function getNavigationLinks( // Define the correct order for navigation const order = [ + // 1. Introduction "introduction", - // decocms (product docs) - "mcp-mesh/overview", + + // 2. Getting Started + "getting-started/ai-builders", + "getting-started/developers", "mcp-mesh/quickstart", + + // 3. Core Concepts + "mcp-mesh/overview", "mcp-mesh/concepts", - "mcp-mesh/connect-clients", + + // 4. Working with MCP + "mcp-mesh/connections", + "mcp-mesh/virtual-mcps", + "mcp-mesh/projects", + "mcp-mesh/agents", + + // 5. Monitoring & Observability + "mcp-mesh/monitoring", + + // 6. Decopilot + "mcp-mesh/decopilot/overview", + "mcp-mesh/decopilot/quickstart", + "mcp-mesh/decopilot/scopes", + "mcp-mesh/decopilot/spawning-agents", + "mcp-mesh/decopilot/tools", + "mcp-mesh/decopilot/context-management", + "mcp-mesh/decopilot/architecture", + + // 7. Security & Access Control "mcp-mesh/authentication", "mcp-mesh/authorization-and-roles", - "mcp-mesh/mcp-servers", - "mcp-mesh/virtual-mcps", "mcp-mesh/api-keys", - "mcp-mesh/monitoring", - "mcp-mesh/api-reference", + + // 8. Deployment "mcp-mesh/deploy/local-docker-compose", "mcp-mesh/deploy/kubernetes-helm-chart", - "getting-started/ai-builders", - "getting-started/developers", + + // 9. Reference + "mcp-mesh/api-reference", + + // 10. Legacy Admin Guides (no-code and full-code guides) "no-code-guides/creating-tools", "no-code-guides/creating-agents", "full-code-guides/project-structure", From 4afc18b331807d6c69cce545633d8e4a60a22cc8 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 22:39:20 -0300 Subject: [PATCH 18/51] docs(decopilot): improve overview scopes section for clarity Refactored the Scopes section in decopilot overview to be more concise and user-friendly: - Condensed Organization/Project/Agent scope descriptions from 3 subsections with bullet points into 3 brief paragraphs - Simplified "How Scopes Layer" section to remove incorrect "Org + Project + Agent" combination that isn't supported - Replaced detailed "Loading Context" section with brief transitional paragraph pointing to dedicated context-management page - Added cross-references between Scopes and Context Management pages - Maintained technical accuracy while focusing on user capabilities rather than implementation details This change keeps the overview concise while detailed technical information is available in the dedicated context-management page. Co-Authored-By: Claude Sonnet 4.5 --- .../en/mcp-mesh/decopilot/overview.mdx | 193 ++++++------------ 1 file changed, 65 insertions(+), 128 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx index 7b737ac6f5..3d40e1564c 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx @@ -10,180 +10,117 @@ import Callout from "../../../../components/ui/Callout.astro"; This page documents the **planned architecture** for decopilot. The implementation is in development. -## What is Decopilot? +## What is decopilot? -**Decopilot** is an agentic AI assistant that operates through the Model Context Protocol within decocms. Unlike traditional AI coding assistants that work with local filesystems, decopilot orchestrates distributed MCP servers over HTTP (or stdio when running locally) to deliver state-of-the-art agentic workflows. +**decopilot** is an agentic AI assistant that orchestrates work across your entire stack—from GitHub and Figma to Google Sheets, email, Slack, and custom services. Unlike traditional AI assistants confined to code editors, decopilot operates through the Model Context Protocol, giving it reach into the productive applications where real work happens. -Decopilot brings the proven agentic loop pattern—**gather context → take action → verify results**—to MCP orchestration. It coordinates work across multiple MCP servers, dynamically adapting based on scope, and delegating to specialized agents when needed. This distributed MCP architecture makes decopilot fundamentally different from filesystem-based assistants: it's an MCP orchestration layer, not a development tool. +You interact through a **chat interface**. Start a conversation, and decopilot works autonomously in the background. Continue with other tasks—when decopilot needs your input, you'll receive a notification. This human-in-the-loop design keeps you in control while letting AI handle coordination across multiple services. -Decopilot uses **virtual MCPs** to make creating and modifying MCPs as easy and liquid as creating files on a filesystem—but with the added benefit of being distributable across the web. While decopilot invokes tools from external MCP servers (GitHub, Figma, Slack), it operates on virtual MCPs to dynamically reshape the environment as it works. Projects, agents, and organization scopes are all virtual MCPs, providing the editable, programmable foundation that enables decopilot's agentic capabilities. +The power comes from **[virtual MCPs](/en/mcp-mesh/virtual-mcps)**—decopilot can create and modify its own capabilities dynamically as it works, adapting to your needs in real-time. This programmable foundation makes decopilot not just a tool user, but a tool builder. - -Start with the [Quick Start](/en/mcp-mesh/decopilot/quickstart) guide to see the agentic loop in action with practical workflows. + +Start with the [Quick Start](/en/mcp-mesh/decopilot/quickstart) guide to see decopilot in action with practical workflows. ## The Agentic Loop -Decopilot operates through a continuous cycle that adapts to your work: +Decopilot follows the same proven agentic loop pattern as [Claude Code](https://code.claude.com/docs/en/how-claude-code-works#the-agentic-loop): **gather context → take action → verify results**. This cycle runs continuously as you work, with decopilot adapting based on what it learns. -**1. Gather Context**: Query connected MCP servers to understand current state -- Read GitHub repositories to check branch status and recent commits -- Fetch Figma designs to understand UI specifications -- Query databases or APIs to verify data state -- Load project resources (architecture docs, checklists, guidelines) +The key difference is where this loop operates. While Claude Code works with local filesystems and terminal commands, decopilot orchestrates **distributed MCP servers** over HTTP. Instead of reading local files, decopilot queries GitHub, Figma, Slack, databases, and your custom MCP servers—all through standardized MCP protocol. -**2. Take Action**: Execute tools across distributed MCP servers -- Create branches, commit code, open pull requests via GitHub MCP -- Export assets, check design specs via Figma MCP -- Send notifications, update channels via Slack MCP -- Create inline tools in virtual MCPs for project-specific operations +Each phase uses MCP tools: +- **Gather context**: Read from connected MCP servers to understand current state +- **Take action**: Execute tools across multiple services in a coordinated workflow +- **Verify results**: Check outcomes, spawn specialized agents for review, adapt approach -**3. Verify Results**: Check outcomes and determine next steps -- Confirm actions completed successfully across all services -- Spawn specialized agents to verify code quality, security, or performance -- Update project resources with findings -- Report results and recommend follow-up actions +The distributed nature means decopilot can orchestrate complex workflows spanning multiple services in a single loop—creating branches in GitHub, exporting assets from Figma, and notifying teams in Slack, all while operating on editable virtual MCPs. -This loop runs continuously as you work, with decopilot adapting based on scope. The distributed nature means decopilot can orchestrate complex workflows spanning multiple services—all coordinated through the MCP protocol. +## Models -```mermaid -graph LR - A[Gather Context] --> B[Take Action] - B --> C[Verify Results] - C --> A +Unlike solutions like [Claude Code](https://code.claude.com/docs/en/how-claude-code-works#models) that are tied to a single provider, decopilot is **multi-model**—it works with various AI model providers to understand your architecture, reason about MCP orchestration, and coordinate distributed workflows. - A -.-> D[GitHub MCP] - A -.-> E[Figma MCP] - A -.-> F[Project Virtual MCP] +You can use: +- **Anthropic models**: Claude Sonnet handles most orchestration tasks well, while Opus provides stronger reasoning for complex multi-service workflows +- **Other providers**: OpenAI, Google, and other commercial model providers +- **Free and open source models**: Self-hosted models via compatible APIs - B -.-> D - B -.-> E - B -.-> F +Model choice affects reasoning quality, speed, and cost. Configure which model decopilot uses based on your needs—stronger models for complex coordination, faster models for simple operations, or open source models for full control and privacy. - C -.-> G[Spawn Agent] - G -.-> C -``` +When this documentation says "decopilot chooses" or "decopilot decides," it's the model doing the reasoning—selecting which MCP servers to query, which tools to enable, and how to coordinate work across distributed systems. -## Distributed MCP Architecture +## Context Management -Decopilot's core differentiator is its **distributed MCP architecture**—the ability to coordinate work across multiple MCP servers while operating on editable virtual MCPs. +Context management is critical in decopilot. Your conversation history, tool definitions, resources, and MCP server configurations all compete for space in the model's limited token window. The more MCP servers you connect and tools you enable, the more context you consume. -**External MCP Servers (Read-Only)**: Decopilot invokes tools from external MCP servers like GitHub, Figma, Slack, and databases. These servers expose their capabilities through the MCP protocol (over HTTP or stdio). Decopilot uses these tools but cannot modify the server configurations—they're external, read-only connections. +Decopilot manages context through: +- **Strategic tool filtering**: Only enabled tools consume context. Use the discover → enable → use pattern to keep overhead low. +- **Agent spawning for isolation**: Spawn agents with fresh context for focused work. They return summaries instead of full conversation history. +- **Reserved token slots**: Decopilot reserves slots for certain operations, ensuring room for critical work even when context is full. -**Virtual MCPs (Editable)**: Decopilot operates on virtual MCPs—editable MCP endpoints that can be modified dynamically. When working in a project, decopilot can add tools, create resources, update prompts, and reshape the virtual MCP configuration. This is the programmable layer that makes decopilot's dynamic behavior possible. +You can always check your current context usage in the decopilot UI to understand what's consuming space and when to spawn an agent for complex work. See [Context Management](/en/mcp-mesh/decopilot/context-management) for token budgets, optimization strategies, and practical examples. -**Composition**: External MCP servers are composed into virtual MCPs through connections. A project's virtual MCP might include GitHub tools, Figma tools, and custom inline tools—all available through one unified MCP endpoint. Decopilot operates on this composed virtual MCP while invoking tools from the external servers. +## Tasks and Agent Spawning -**Protocol-Based Orchestration**: MCP coordination happens over HTTP for remote servers or stdio for local servers. Decopilot doesn't need filesystem access—it coordinates distributed MCP servers through the MCP protocol. This makes decopilot portable, scalable, and composable across your infrastructure. +As you work, decopilot can delegate specialized work to **[agents](/en/mcp-mesh/agents)**—focused assistants optimized for specific tasks like customer support, research, or data analysis. When you spawn an agent, it gets its own fresh context to work independently, then reports back with a summary. -This architecture enables workflows that span multiple services in a single agentic loop. Need to create a branch, export Figma assets, and notify the team? Decopilot orchestrates all three through distributed MCP calls, verifies success, and reports back—pure MCP orchestration. +This lets you handle complex work in parallel. For example, spawn a support agent to answer a customer question about product compatibility while you continue building the checkout flow. The agent works separately with clean context, preventing your main conversation from getting bloated with support details. -## Key Capabilities +Learn more about when to spawn agents and spawning patterns in [Tasks and Agent Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning). -**Agentic Workflow Orchestration**: The continuous gather → act → verify loop enables decopilot to handle complex, multi-step workflows autonomously. Decopilot breaks down ambiguous requests into concrete actions, executes them across distributed services, and adapts based on results. +## Scopes -**Distributed Tool Coordination**: Invoke tools from multiple MCP servers in a single workflow. Decopilot seamlessly coordinates GitHub, Figma, Slack, databases, and custom tools—all through standardized MCP protocol. +Decopilot always operates within a **scope**—the virtual MCP context that determines which tools, resources, and instructions are available. Scopes let you work at different levels of focus, from organization-wide operations to project-specific tasks to individual agent work. -**Dynamic Environment Configuration**: Operating on virtual MCPs means decopilot can reshape the environment as it works. Add tools on the fly, create resources for documentation, update prompts based on patterns—all without manual configuration. +Your current scope is determined by where you are in the decocms UI, and decopilot automatically loads the appropriate capabilities for that context. The three scope levels are: -**Scope-Sensitive Operations**: Decopilot automatically adapts based on where you are in the application. Organization scope provides org-wide capabilities. Project scope gives project-specific tools and context. Agent scope bounds operations to focused purposes. +- **Org scope**: The default level with organization-wide [connections](/en/mcp-mesh/connections), resources, and [agents](/en/mcp-mesh/agents). Always available as the foundation. +- **Project scope**: Adds project-specific tools, resources, and prompts from the [project's virtual MCP](/en/mcp-mesh/virtual-mcps). Inherits org scope. +- **Agent scope**: Adds specialized instructions and bounded tools when working with a specific [agent](/en/mcp-mesh/agents). Inherits org or project scope. -**Agent Spawning**: Delegate to specialized agents with fresh context for parallel work. Spawn a security agent to review code while continuing with implementation. Spawn a research agent to explore architecture while keeping the main context clean. +### How Scopes Layer -**Context Management**: Intelligent token management through strategic agent spawning and tool filtering. Decopilot balances completeness with efficiency, ensuring relevant context without bloat. +Scopes layer naturally as you navigate: -## Scope-Based Operation +- **Org scope alone**: Access org-wide capabilities +- **Org + Project scope**: Access org capabilities plus project-specific context +- **Org + Agent scope**: Access org capabilities plus agent-specific instructions -Decopilot operates in **three distinct scopes**, each corresponding to a different virtual MCP: +This layered approach means you're never locked into a narrow view—org-level tools remain available even when working in focused project or agent contexts. See [Context Management](/en/mcp-mesh/decopilot/context-management#scope-specific-context-loading) for technical details on what context loads at each scope level, and [Tasks and Agent Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning) to understand how spawned agents create isolated task scopes with fresh context. -**Org Scope** (`/:org/settings`): Organization-wide context with shared resources, prompts, and connected MCPs. Think of this as the foundation level—comparable to `~/.claude/` in Claude Code. +## Built-in Tools -**Project Scope** (`/:org/projects/:id`): Project-specific virtual MCP with project tools, resources, and connected external MCPs. Isolated work context for the project—comparable to `.claude/` in Claude Code. +Decopilot comes with built-in tools that enable meta-level operations: +- **`agent_spawn`**: Create child tasks with specialized agents +- **`agent_search`**: Discover available agents in your organization +- **`tools_search`**: Find tools in the current scope's virtual MCP +- **`tool_enable`**: Activate tools in the current scope before use +- **`resource_read` / `resource_edit`**: Manage project documentation and resources +- **`prompt_read` / `prompt_edit`**: Create reusable prompt templates -**Agent Scope** (`/:org/agents/:id`): Single-purpose virtual MCP optimized for repeatable tasks. Most narrowly focused scope with bounded tool access. +These built-in tools are always available and provide the foundation for working with virtual MCPs. Beyond these, you discover and enable tools from your connected MCP servers (GitHub, Figma, Slack, etc.) as needed. -The route determines the scope automatically. As you navigate the application, decopilot seamlessly adapts to the new context, adjusting available tools, resources, and capabilities accordingly. +See [Tools](/en/mcp-mesh/decopilot/tools) for complete specifications, usage patterns, and examples of coordinating tools across multiple services. -For detailed information on how scopes work and when to use each, see [Scopes](/en/mcp-mesh/decopilot/scopes). +## Loading Context -## Quick Examples +When decopilot starts a task, it loads context based on your current scope—org-level instructions, project-specific guidelines, and agent instructions are all layered according to the layers described above. Resources and tools are loaded strategically to keep context usage under control. For complete details on context loading priorities, token budgets, and optimization strategies, see [Context Management](/en/mcp-mesh/decopilot/context-management). -### Multi-Server Workflow - -Working in a project, you ask decopilot to prepare a feature branch: - -```typescript -// Decopilot orchestrates across 3 MCP servers: - -// 1. GitHub MCP - Create feature branch -CREATE_BRANCH({ name: "feature/biometric-auth", base: "main" }) - -// 2. Figma MCP - Export latest auth flow designs -EXPORT_ASSETS({ fileId: "auth-flows", format: "svg" }) - -// 3. Slack MCP - Notify team -SEND_MESSAGE({ channel: "engineering", text: "Started biometric auth feature" }) - -// All coordinated through decopilot's agentic loop -``` - -### Agent Spawning Pattern - -Need security review while continuing development: - -```typescript -// Main loop: Implementing feature -User: "Add biometric authentication" - -Decopilot: -- Plans implementation approach -- Spawns security agent on parallel task - -// Spawned agent (isolated context) -Agent: security-reviewer-001 -- Scans authentication files -- Checks for common vulnerabilities -- Generates findings report -- Returns to main loop - -// Main loop continues -Decopilot: -- Completes implementation -- Integrates security findings -- Updates code based on recommendations -``` - -The agent runs with fresh context, preventing token bloat while enabling focused security analysis in parallel. - - - If you're familiar with Claude Code, here's how decopilot concepts map to what you know: - -| Claude Code | Decopilot | -|-------------|-----------| -| Agentic loop (local) | Agentic loop (distributed MCP) | -| Skills | Virtual MCPs (agents) | -| `project/.claude/` | Project scope (`/:org/projects/:id`) | -| `~/.claude/` | Org scope (org routes) | -| Subagents | Agent spawning with `agent_spawn` | -| CLAUDE.md | CLAUDE.md + AGENTS.md | -| Skill references/assets | MCP resources | -| `/command` invocation | MCP commands | +## Next Steps -**Key difference**: Decopilot brings Claude Code's agentic patterns to MCP orchestration through distributed architecture. Instead of local filesystem operations, decopilot coordinates work across multiple MCP servers—GitHub, Figma, Slack, databases, and more—all through standardized MCP protocol. - +Ready to learn more? Explore these guides to understand how decopilot works: -## Next Steps +**[Quick Start](/en/mcp-mesh/decopilot/quickstart)**: See decopilot in action with step-by-step workflows. Start here for hands-on examples. -**[Quick Start](/en/mcp-mesh/decopilot/quickstart)**: See the agentic loop in action with practical workflows. Start here for hands-on examples. +**[Context Management](/en/mcp-mesh/decopilot/context-management)**: Learn strategies for managing token usage, when to spawn agents, and how to optimize context. -**[Scopes](/en/mcp-mesh/decopilot/scopes)**: Learn how org/project/agent scopes determine available tools and context. Essential for understanding decopilot's behavior. +**[Tasks and Agent Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning)**: Understand task lifecycles, agent selection, and patterns for parallel execution. -**[Architecture](/en/mcp-mesh/decopilot/architecture)**: Deep-dive into decopilot's technical implementation, virtual MCP constraint, and distributed coordination. +**[Tools](/en/mcp-mesh/decopilot/tools)**: Complete reference for built-in tools and working with target virtual MCP tools. -**[Tools](/en/mcp-mesh/decopilot/tools)**: Explore the comprehensive toolset for MCP management and tool discovery patterns. +**[Scopes](/en/mcp-mesh/decopilot/scopes)**: Deep-dive into scope-based routing and how org/project/agent contexts work. -**[Virtual MCPs](/en/mcp-mesh/virtual-mcps)**: Understand why virtual MCPs enable dynamic configuration and how they differ from external MCP servers. +**[Architecture](/en/mcp-mesh/decopilot/architecture)**: Technical implementation details and distributed coordination patterns. --- -Decopilot represents a new approach to MCP orchestration—**HTTP-based, MCP-first, and built on distributed architecture**. By operating through virtual MCPs and coordinating across external MCP servers, decopilot delivers the proven agentic loop pattern as an MCP orchestration layer. This is the agentic assistant that runs on decocms. +Decopilot brings proven agentic patterns to MCP orchestration. By coordinating work across distributed MCP servers while operating on editable virtual MCPs, decopilot enables complex workflows that span multiple services—all through standardized MCP protocol. This is the agentic assistant that runs on decocms. From 6b85c2b288905910273bbd8ba4b8894aee19603d Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 22:39:30 -0300 Subject: [PATCH 19/51] docs(decopilot): add scope-specific context loading section Enhanced context-management.mdx with detailed scope-based loading information: - Replaced "What Gets Included in Context" with enhanced "How Context Loading Works" section with priority explanations - Added new "Scope-Specific Context Loading" section with detailed breakdowns of Organization, Project, and Agent scopes - Added context inheritance table showing what loads at each scope level - Updated CLAUDE.md section to clarify org vs project scope behavior - Updated AGENTS.md section to emphasize agent-scope-only loading - Added cross-references between overview Scopes section and context-management technical details - Updated Strategy 4 in optimization section with scope-specific links This provides the technical depth on context loading that was removed from the overview, creating better separation between user-facing concepts (overview) and implementation details (context-management). Co-Authored-By: Claude Sonnet 4.5 --- .../mcp-mesh/decopilot/context-management.mdx | 77 ++++++++++++++++--- 1 file changed, 66 insertions(+), 11 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx index b64874a7c0..41f94fd656 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx @@ -12,20 +12,75 @@ import Callout from "../../../../components/ui/Callout.astro"; Decopilot manages context through a priority-based system that balances completeness with efficiency. Context includes conversation history, tool definitions, resources, and project-specific instructions—all within the model's limited token window. -## What Gets Included in Context +## How Context Loading Works -Decopilot builds context in priority order: +When decopilot starts a task, it loads context in priority order. This ensures essential context is always present while managing token usage efficiently: -1. **System Instructions** - Core behavior definition (always present) -2. **CLAUDE.md** - Project and org-admin persistent rules -3. **AGENTS.md** - Agent-specific instructions via MCP server instructions property -4. **Conversation History** - Recent messages (automatically truncated) -5. **MCP Tool Definitions** - Filtered by agent type to reduce overhead -6. **Resources** - Loaded on-demand when explicitly requested +1. **System instructions**: Core behavior definition (always present, ~800 tokens) +2. **CLAUDE.md**: Organization and project persistent rules (scope-dependent, see below) +3. **AGENTS.md**: Agent-specific instructions via MCP server's instructions property (only for spawned agents) +4. **Conversation history**: Recent messages automatically managed and truncated as needed +5. **MCP tool definitions**: Only enabled tools consume context (filtered by agent type to reduce overhead) +6. **Resources**: Loaded on-demand when explicitly requested through tool invocations + +The priority system ensures essential instructions and rules are loaded first, with heavier elements (conversation history, tools, resources) added strategically based on need and scope. + +## Scope-Specific Context Loading + +Different scopes load different context automatically. Understanding scope-based loading helps you work efficiently and avoid unnecessary context bloat. + +### Organization Scope + +When working at org scope (the default level): +- **System instructions**: Always present +- **Org CLAUDE.md**: Organization-wide rules and standards +- **Org-level tools**: Tools enabled at organization level +- **Conversation history**: Current session +- **NO project-specific context**: No project CLAUDE.md, no project tools + +Use org scope for cross-project work, administrative tasks, or when you don't need project-specific context. + +### Project Scope + +When working at project scope: +- **System instructions**: Always present +- **Org CLAUDE.md**: Inherited from organization +- **Project CLAUDE.md**: Project-specific rules (takes precedence on conflicts) +- **Project tools**: Tools enabled at project level +- **Conversation history**: Current session +- **Resources**: Available on-demand through `resource_read` + +Project scope inherits org context and adds project-specific layers. This is the most common scope for development work. + +### Agent Scope + +When you spawn an agent: +- **System instructions**: Always present +- **CLAUDE.md**: Inherited based on spawn location (org or project) +- **AGENTS.md**: Agent-specific instructions from MCP server's instructions property +- **Task prompt**: The specific task you assigned +- **Filtered tools**: Only tools relevant to agent type +- **NO parent conversation history**: Fresh context, no accumulated history from parent +- **NO parent resources**: Clean slate, loads own resources if needed + +Agent scope provides fresh, focused context for specific tasks. See [Context Isolation via Agent Spawning](#context-isolation-via-agent-spawning) for details. + +### Context Inheritance + +| Context Element | Org Scope | Project Scope | Agent Scope (from project) | +|----------------|-----------|---------------|---------------------------| +| System instructions | ✓ | ✓ | ✓ | +| Org CLAUDE.md | ✓ | ✓ (inherited) | ✓ (inherited) | +| Project CLAUDE.md | ✗ | ✓ | ✓ (inherited) | +| AGENTS.md | ✗ | ✗ | ✓ | +| Parent conversation | ✓ (own) | ✓ (own) | ✗ (fresh start) | +| Parent resources | N/A | N/A | ✗ (clean slate) | + +See [Scopes](/en/mcp-mesh/decopilot/overview#scopes) in the overview for more on how scope layering works in practice. ## CLAUDE.md Support -CLAUDE.md provides persistent context at two levels: org-admin (`/:org` scope) for organization-wide rules, and project (`/:org/projects/:id` scope) for project-specific guidelines. +CLAUDE.md provides persistent context at two levels: **org scope** for organization-wide rules, and **project scope** for project-specific guidelines. When working in project scope, both org and project CLAUDE.md files are loaded—project context inherits from org context. **Precedence handling**: When both levels define conflicting rules, project-level CLAUDE.md takes precedence. This allows project-specific overrides while maintaining organization-wide defaults. For example, an org-admin might enforce Conventional Commits across all projects, but a specific project could override commit message format for integration with external systems. @@ -67,7 +122,7 @@ CLAUDE.md provides persistent context at two levels: org-admin (`/:org` scope) f ## AGENTS.md Support -AGENTS.md provides agent-specific instructions via the MCP server's `instructions` property. Both project and org-admin virtual MCPs return this content—spawned agents automatically receive targeted guidance for their specific purpose. +AGENTS.md provides agent-specific instructions via the MCP server's `instructions` property. **This content only appears in agent scope**—when decopilot spawns an agent. When spawned from project scope, agents receive both org CLAUDE.md and project CLAUDE.md plus AGENTS.md. When spawned from org scope, agents receive only org CLAUDE.md plus AGENTS.md. ### Example: AGENTS.md Structure @@ -279,7 +334,7 @@ await tool_enable({ tool_name: "LIST_FILES" }) **Problem**: Working in wrong scope, loading unnecessary inherited context. -**Solution**: Use the most specific scope appropriate for your task. +**Solution**: Use the most specific scope appropriate for your task. See [Scopes](/en/mcp-mesh/decopilot/overview#scopes) for details on scope-based capabilities and [Scope-Specific Context Loading](#scope-specific-context-loading) for what context is available at each level. **Example: Wrong Scope (Bloated)** From cd7a62a1c4097abfde3ada23392f451253a08516 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 22:39:39 -0300 Subject: [PATCH 20/51] docs(nav): reorder decopilot menu to match overview structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated sidebar navigation and page navigation order for decopilot section to follow the logical flow from overview's "Next Steps": New order: 1. Overview 2. Quick Start (was missing from sidebar order) 3. Context Management (moved up) 4. Tasks and Agent Spawning 5. Tools 6. Scopes (moved down) 7. Architecture Also improved sidebar comments to document the information architecture structure (Getting Started → Core Concepts → Working with MCP → Monitoring → Security → Reference). Co-Authored-By: Claude Sonnet 4.5 --- .../client/src/components/ui/Sidebar.astro | 50 +++++++++++++++---- apps/docs/client/src/utils/navigation.ts | 6 +-- 2 files changed, 43 insertions(+), 13 deletions(-) diff --git a/apps/docs/client/src/components/ui/Sidebar.astro b/apps/docs/client/src/components/ui/Sidebar.astro index 524fc98904..340bb905df 100644 --- a/apps/docs/client/src/components/ui/Sidebar.astro +++ b/apps/docs/client/src/components/ui/Sidebar.astro @@ -68,17 +68,25 @@ function buildTree(docs: any[]): TreeNode[] { // Custom order for decocms top-level pages if (parentPath === "mcp-mesh") { // NOTE: doc IDs do not include ".mdx" (e.g. "overview", not "overview.mdx") + // Order follows: Getting Started → Core Concepts → Working with MCP → Monitoring → Decopilot → Security → Operations → Reference const mcpMeshOrder = [ - "overview", + // Getting Started "quickstart", + // Core Concepts + "overview", "concepts", - "connect-clients", + // Working with MCP + "connections", + "virtual-mcps", + "projects", + "agents", + // Monitoring & Observability + "monitoring", + // Security & Access Control "authentication", "authorization-and-roles", - "mcp-servers", - "virtual-mcps", "api-keys", - "monitoring", + // Reference "api-reference", ]; const aIndex = mcpMeshOrder.indexOf(a.name); @@ -90,6 +98,26 @@ function buildTree(docs: any[]): TreeNode[] { if (bIndex !== -1) return 1; } + // Custom order for decopilot subfolder + if (parentPath === "decopilot") { + const decopilotOrder = [ + "overview", + "quickstart", + "context-management", + "tasks-and-spawning", + "tools", + "scopes", + "architecture", + ]; + const aIndex = decopilotOrder.indexOf(a.name); + const bIndex = decopilotOrder.indexOf(b.name); + if (aIndex !== -1 && bIndex !== -1) { + return aIndex - bIndex; + } + if (aIndex !== -1) return -1; + if (bIndex !== -1) return 1; + } + // Custom order for no-code-guides files if (parentPath === "no-code-guides") { const noCodeOrder = ["creating-tools", "creating-agents"]; @@ -137,11 +165,13 @@ function buildTree(docs: any[]): TreeNode[] { // For folders - custom ordering if (a.type === "folder" && b.type === "folder") { const folderOrder: Record = { - // Put decocms docs first - "mcp-mesh": 0, - "getting-started": 1, - "no-code-guides": 2, - "full-code-guides": 3, + // Order follows improved information architecture + "mcp-mesh": 0, // decocms docs (main product) + "getting-started": 1, // Getting Started (after intro) + decopilot: 2, // Decopilot (elevated section within mcp-mesh) + deploy: 3, // Deploy section + "no-code-guides": 4, // Legacy admin guides + "full-code-guides": 5, // Legacy admin guides }; const aOrder = folderOrder[a.name] ?? Number.POSITIVE_INFINITY; diff --git a/apps/docs/client/src/utils/navigation.ts b/apps/docs/client/src/utils/navigation.ts index 413098f493..7cc8bfbd18 100644 --- a/apps/docs/client/src/utils/navigation.ts +++ b/apps/docs/client/src/utils/navigation.ts @@ -39,10 +39,10 @@ export async function getNavigationLinks( // 6. Decopilot "mcp-mesh/decopilot/overview", "mcp-mesh/decopilot/quickstart", - "mcp-mesh/decopilot/scopes", - "mcp-mesh/decopilot/spawning-agents", - "mcp-mesh/decopilot/tools", "mcp-mesh/decopilot/context-management", + "mcp-mesh/decopilot/tasks-and-spawning", + "mcp-mesh/decopilot/tools", + "mcp-mesh/decopilot/scopes", "mcp-mesh/decopilot/architecture", // 7. Security & Access Control From aa16d7e63b1d78d0f09026137df843292b248e62 Mon Sep 17 00:00:00 2001 From: gimenes Date: Mon, 9 Feb 2026 22:41:40 -0300 Subject: [PATCH 21/51] docs: implement comprehensive documentation restructuring Major documentation improvements across multiple areas: **New pages:** - Added connections.mdx to document MCP connection management - Added tasks-and-spawning.mdx for decopilot task lifecycle **Removed/consolidated pages:** - Removed connect-clients.mdx (consolidated into connections.mdx) - Removed spawning-agents.mdx (consolidated into tasks-and-spawning.mdx) - Removed mcp-servers.mdx (content moved to connections.mdx) **Updated documentation:** - AGENTS.md: Updated agent documentation structure - Sidebar.tsx: Component updates for navigation - introduction.mdx: Improved introduction content (en + pt-br) - quickstart.mdx: Enhanced quick start guides (mcp-mesh + decopilot) - overview.mdx: Updated overview content - projects.mdx: Improved project documentation - virtual-mcps.mdx: Enhanced virtual MCP explanations - authorization-and-roles.mdx: Updated auth documentation - monitoring.mdx: Improved monitoring docs - deployment.mdx: Updated deployment guide - creating-agents.mdx: Enhanced agent creation guide - ui.ts: Updated i18n translations This restructuring improves information architecture by consolidating related content, removing redundancy, and creating clearer navigation paths through the documentation. Co-Authored-By: Claude Sonnet 4.5 --- AGENTS.md | 4 + .../docs/client/src/components/ui/Sidebar.tsx | 4 +- .../en/full-code-guides/deployment.mdx | 2 +- .../client/src/content/en/introduction.mdx | 2 +- .../en/mcp-mesh/authorization-and-roles.mdx | 2 +- .../content/en/mcp-mesh/connect-clients.mdx | 31 --- .../src/content/en/mcp-mesh/connections.mdx | 143 ++++++++++++ .../en/mcp-mesh/decopilot/quickstart.mdx | 2 +- ...ning-agents.mdx => tasks-and-spawning.mdx} | 4 +- .../src/content/en/mcp-mesh/mcp-servers.mdx | 39 ---- .../src/content/en/mcp-mesh/monitoring.mdx | 145 +++++++++++-- .../src/content/en/mcp-mesh/overview.mdx | 127 +++++++++-- .../src/content/en/mcp-mesh/projects.mdx | 205 ++++-------------- .../src/content/en/mcp-mesh/quickstart.mdx | 2 +- .../src/content/en/mcp-mesh/virtual-mcps.mdx | 8 +- .../en/no-code-guides/creating-agents.mdx | 4 +- .../client/src/content/pt-br/introduction.mdx | 2 +- apps/docs/client/src/i18n/ui.ts | 12 + 18 files changed, 456 insertions(+), 282 deletions(-) delete mode 100644 apps/docs/client/src/content/en/mcp-mesh/connect-clients.mdx create mode 100644 apps/docs/client/src/content/en/mcp-mesh/connections.mdx rename apps/docs/client/src/content/en/mcp-mesh/decopilot/{spawning-agents.mdx => tasks-and-spawning.mdx} (99%) delete mode 100644 apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx diff --git a/AGENTS.md b/AGENTS.md index aa6202ca13..363eb031e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,10 @@ This file provides guidance when working with code in this repository, including for Claude Code (claude.ai/code) and other AI coding assistants. +## Documentation Philosophy + +**IMPORTANT**: The documentation in `apps/docs/` describes the **intended system design and behavior**, not necessarily the current implementation state. Documentation represents the target architecture and how the system should work, serving as both specification and aspiration. When implementation and documentation differ, the documentation defines the goal, not a bug to be "fixed" in the docs. + ## Overview MCP Mesh is an open-source control plane for Model Context Protocol (MCP) traffic. It provides a unified layer for authentication, routing, and observability between MCP clients (Cursor, Claude, VS Code) and MCP servers. The system is built as a monorepo using Bun workspaces with TypeScript, Hono (API), and React 19 (UI). diff --git a/apps/docs/client/src/components/ui/Sidebar.tsx b/apps/docs/client/src/components/ui/Sidebar.tsx index 3d8e4a1b87..399865e408 100644 --- a/apps/docs/client/src/components/ui/Sidebar.tsx +++ b/apps/docs/client/src/components/ui/Sidebar.tsx @@ -142,7 +142,9 @@ function TreeItem({ ? "Network" : node.id === "mcp-mesh/deploy" ? "Rocket" - : "Folder" + : node.id === "mcp-mesh/decopilot" + ? "Bot" + : "Folder" } size={16} className={`shrink-0 ${active ? "text-primary" : ""}`} diff --git a/apps/docs/client/src/content/en/full-code-guides/deployment.mdx b/apps/docs/client/src/content/en/full-code-guides/deployment.mdx index 785c1785d8..ef626a4d49 100644 --- a/apps/docs/client/src/content/en/full-code-guides/deployment.mdx +++ b/apps/docs/client/src/content/en/full-code-guides/deployment.mdx @@ -103,7 +103,7 @@ Test production immediately after deploy: 1. Open `https://.deco.page` 2. Verify frontend loads correctly -3. Test tool calls through UI +3. Test tool invocations through UI 4. Check integrations work (production may use different credentials than dev) 5. Test as an end user would interact with the app 6. Review Cloudflare Worker logs if issues occur diff --git a/apps/docs/client/src/content/en/introduction.mdx b/apps/docs/client/src/content/en/introduction.mdx index 31f11baf9f..1518d88fa6 100644 --- a/apps/docs/client/src/content/en/introduction.mdx +++ b/apps/docs/client/src/content/en/introduction.mdx @@ -91,7 +91,7 @@ The application will be available at `http://localhost:8080`. - **[decocms Overview](/en/mcp-mesh/overview)** - **[Quickstart](/en/mcp-mesh/quickstart)** - **[Concepts](/en/mcp-mesh/concepts)** -- **[MCP Servers (Connections)](/en/mcp-mesh/mcp-servers)** +- **[Connections](/en/mcp-mesh/connections)** - **[Virtual MCPs](/en/mcp-mesh/virtual-mcps)** - **[API Keys](/en/mcp-mesh/api-keys)** - **[Monitoring](/en/mcp-mesh/monitoring)** diff --git a/apps/docs/client/src/content/en/mcp-mesh/authorization-and-roles.mdx b/apps/docs/client/src/content/en/mcp-mesh/authorization-and-roles.mdx index 0371406972..32ed2d4ab2 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/authorization-and-roles.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/authorization-and-roles.mdx @@ -1,6 +1,6 @@ --- title: Authorization & Roles -description: How permissions are enforced across management tools and proxied tool calls +description: How permissions are enforced across management tools and proxied tool invocations icon: Users --- diff --git a/apps/docs/client/src/content/en/mcp-mesh/connect-clients.mdx b/apps/docs/client/src/content/en/mcp-mesh/connect-clients.mdx deleted file mode 100644 index 4daf540ce4..0000000000 --- a/apps/docs/client/src/content/en/mcp-mesh/connect-clients.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Connect MCP Clients -description: How Cursor/Claude/custom clients authenticate to the Mesh and consume tools via MCP -icon: PlugZap ---- - -import Callout from "../../../components/ui/Callout.astro"; - -## Client options - -There are two common ways to connect clients to the Mesh: - -- **OAuth (recommended for interactive clients)**: supports standard OAuth flows, consent, and organization-aware access. -- **API Keys (recommended for servers/agents)**: scoped keys with explicit tool permissions. - -## Endpoints you’ll use - -- **Management MCP**: `POST /mcp` -- **Connection proxy**: `POST /mcp/:connectionId` -- **Agent (virtual server)**: `POST /mcp/gateway/:gatewayId` (or omit `:gatewayId` to use the org default Agent with headers) - - - If your goal is a "single MCP URL" for a curated tool surface, use **Agents**. If you want a direct pipe to one upstream MCP, use **Connection proxy**. - - -## Authentication quick notes - -- **OAuth** is ideal when you want per-user identity and browser-based sign-in. -- **API keys** are ideal for automation and server-to-server access (least friction to bootstrap). - - diff --git a/apps/docs/client/src/content/en/mcp-mesh/connections.mdx b/apps/docs/client/src/content/en/mcp-mesh/connections.mdx new file mode 100644 index 0000000000..81be231112 --- /dev/null +++ b/apps/docs/client/src/content/en/mcp-mesh/connections.mdx @@ -0,0 +1,143 @@ +--- +title: Connections +description: How decocms connects to upstream MCP servers and how clients connect to the mesh +icon: Network +--- + +import Callout from "../../../components/ui/Callout.astro"; + +## What are Connections? + +**Connections** represent the bridge between decocms and external MCP servers. A Connection is decocms's registered relationship with an upstream MCP server—whether that's GitHub, Slack, a database, or your custom MCP implementation. + +## Connecting to Upstream MCP Servers + +### Why Connections Exist + +The Connection abstraction solves a critical problem: **separating connection configuration from usage**. Instead of every client (Cursor, Claude Desktop, custom agents) managing their own credentials and endpoints for each MCP server, decocms centralizes this once. + +#### The Problem Without Connections + +Without a centralized connection layer: +- Every client must store and manage credentials for every MCP server they use +- Credential rotation means updating every client +- No unified audit trail of which tools were accessed and by whom +- Authorization policies drift across different clients +- No way to temporarily revoke access to an MCP server without updating all clients + +#### How Connections Solve This + +Connections provide: + +**Centralized credential management**: Store credentials once in decocms's encrypted vault. Clients authenticate to decocms, not to individual MCP servers. + +**Unified authorization**: Define who can access which tools through decocms's permission system, rather than managing access per MCP server. + +**Credential rotation without client updates**: Update credentials in decocms; all clients automatically use the new credentials without reconfiguration. + +**Complete observability**: Every tool invocation flows through decocms, creating a unified audit trail across all MCP servers. + +**Secure credential handling**: Credentials are encrypted at rest and only decrypted at request time, never exposed to clients. + +### Design Principles + +#### 1. Connections are Read-Only From Client Perspective + +Clients interact with tools exposed by Connections, but they cannot modify the Connection configuration itself. This separation ensures: +- Credentials remain protected +- Configuration changes require appropriate authorization +- Audit trails remain trustworthy + +#### 2. Connections Compose Into Virtual MCPs + +Connections are the building blocks for [Virtual MCPs](/en/mcp-mesh/virtual-mcps). You connect individual MCP servers (GitHub, Slack, databases), then compose them into Virtual MCPs that expose curated tool surfaces. + +``` +GitHub Connection ──┐ +Slack Connection ──┼──▶ Virtual MCP (Project) ──▶ Clients +Database Connection──┘ +``` + +This composition model keeps external MCP servers isolated and secure while enabling flexible, dynamic tool surfaces through Virtual MCPs. + +#### 3. Connections are Organization-Scoped + +All Connections belong to an organization. This scoping ensures: +- Clear tenant isolation +- Organization-wide credential management +- Consistent access policies across projects and agents + +### How Connections Work + +When a client invokes a tool through decocms: + +1. **Client authenticates** to decocms (OAuth or API key) +2. **Authorization check**: decocms verifies the client has permission to invoke the requested tool +3. **Credential loading**: decocms decrypts stored credentials for the target Connection +4. **Request proxying**: decocms forwards the MCP request to the upstream server with credentials +5. **Monitoring**: decocms logs the invocation (tool, duration, status, errors) +6. **Response return**: decocms returns the MCP server's response to the client + +This flow ensures credentials never leave decocms's secure boundary while enabling seamless tool invocation. + +### Connection Types + +Connections typically fall into three categories: + +**SaaS Integration MCPs**: Services like GitHub, Slack, Notion, Google Drive—external systems with their own authentication (often OAuth). + +**Infrastructure MCPs**: Database connections, Kubernetes clusters, cloud provider APIs—systems requiring sensitive credentials. + +**Custom MCPs**: Your own MCP servers exposing domain-specific tools and operations. + +All connection types follow the same pattern: register once in decocms, use everywhere through Virtual MCPs and agents. + +### Connections vs. Direct Access + +**Direct Access** (client → MCP server): +- ✅ Simple for single-client, single-server scenarios +- ❌ Credentials managed per client +- ❌ No unified observability +- ❌ Authorization logic duplicated + +**Through Connections** (client → decocms → MCP server): +- ✅ Centralized credential management +- ✅ Unified authorization and observability +- ✅ Credential rotation without client updates +- ✅ Foundation for Virtual MCPs and composition + +For production usage, Connections provide the control plane capabilities needed to operate MCP traffic at scale. + +--- + +## Connecting MCP Clients to the Mesh + +Once you've configured upstream connections, you need to connect your MCP clients (Cursor, Claude Desktop, custom agents) to decocms to consume the tools. + +### Client Authentication Options + +There are two common ways to connect clients to the Mesh: + +- **OAuth (recommended for interactive clients)**: supports standard OAuth flows, consent, and organization-aware access. +- **API Keys (recommended for servers/agents)**: scoped keys with explicit tool permissions. + +### Endpoints + +Depending on your use case, you'll connect to one of these endpoints: + +- **Management MCP**: `POST /mcp` - Access decocms management tools (creating connections, projects, agents) +- **Connection proxy**: `POST /mcp/:connectionId` - Direct access to a specific upstream connection +- **Agent (virtual server)**: `POST /mcp/gateway/:gatewayId` - Access a curated tool surface through an agent + + + If your goal is a "single MCP URL" for a curated tool surface, use **Agents**. If you want a direct pipe to one upstream MCP, use **Connection proxy**. + + +### Authentication Quick Notes + +- **OAuth** is ideal when you want per-user identity and browser-based sign-in. +- **API keys** are ideal for automation and server-to-server access (least friction to bootstrap). + + + Connections are the foundation for [Virtual MCPs](/en/mcp-mesh/virtual-mcps), [Projects](/en/mcp-mesh/projects), and [Agents](/en/mcp-mesh/agents)—you'll connect individual MCP servers first, then compose them into higher-level abstractions. + diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx index ee764885b7..bf1ada8054 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx @@ -583,7 +583,7 @@ if (status.status === "completed") { **[Scopes](/en/mcp-mesh/decopilot/scopes)**: Understand how org/project/agent scopes determine behavior and tool availability. Essential for effective decopilot use. -**[Spawning Agents](/en/mcp-mesh/decopilot/spawning-agents)**: Learn advanced patterns for agent spawning, including fan-out/fan-in, conditional spawning, and agent selection. +**[Tasks and Agent Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning)**: Learn advanced patterns for agent spawning, including fan-out/fan-in, conditional spawning, and agent selection. **[Tools](/en/mcp-mesh/decopilot/tools)**: Explore the comprehensive toolset, discover patterns, and troubleshoot common issues. diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx similarity index 99% rename from apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx rename to apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx index 557186c9d7..8922cc0cdd 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/spawning-agents.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx @@ -1,6 +1,6 @@ --- -title: Spawning Agents -description: How decopilot spawns agents as tasks for parallel execution and context isolation +title: Tasks and Agent Spawning +description: How decopilot uses tasks with isolated contexts and spawns agents for parallel execution icon: Layers --- diff --git a/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx b/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx deleted file mode 100644 index d88cbdc714..0000000000 --- a/apps/docs/client/src/content/en/mcp-mesh/mcp-servers.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Connections -description: Register upstream MCP servers, store credentials, and proxy requests securely -icon: Server ---- - -import Callout from "../../../components/ui/Callout.astro"; - -## What is a connection? - -A **Connection** in the Mesh is a configured upstream MCP endpoint (typically HTTP). The Mesh stores its configuration and (optionally) credentials, and can then proxy MCP requests to it. - -## In the UI - -Go to **Connections** to: - -- browse connected connections -- create a new connection (**Create Connection**) -- search and manage existing connections - -## Proxying to a single connection - -Once you have a connection ID, clients can call tools via: - -- `POST /mcp/:connectionId` - -The Mesh will: - -1. authenticate the caller -2. authorize the tool call -3. decrypt credentials (if needed) -4. forward the MCP request to the upstream server -5. log a monitoring event - - - If you need a single aggregated endpoint for multiple connections, use [Agents](/en/mcp-mesh/virtual-mcps) instead. - - - diff --git a/apps/docs/client/src/content/en/mcp-mesh/monitoring.mdx b/apps/docs/client/src/content/en/mcp-mesh/monitoring.mdx index 842f6961f6..3acecfb511 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/monitoring.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/monitoring.mdx @@ -1,34 +1,141 @@ --- title: Monitoring -description: Inspect tool calls, errors, and latency across connections and agents +description: Why observability is built into the control plane and how it enables production MCP operations icon: Activity --- -## What gets recorded +import Callout from "../../../components/ui/Callout.astro"; -The Mesh records monitoring logs for proxied tool calls, including: +## Observability as Infrastructure -- tool name -- connection / agent attribution -- user identity (user ID or API key user) -- duration and error status -- inputs and output (normalized) +decocms treats monitoring as **infrastructure, not an afterthought**. Every tool invocation that flows through the control plane creates a monitoring log—there's no way to disable this, and that's by design. -## In the UI + +**Every tool call is monitored by decocms.** Whether it's a simple GitHub query or a complex database operation, every MCP tool invocation creates a structured log entry with full request/response details, timing, attribution, and error information. This happens automatically—no configuration required. + -Go to **Monitoring** to: +Traditional MCP deployments have fragmented observability: each client logs independently (or doesn't log at all), each MCP server has its own logging strategy, and there's no unified view of what happened across the system. decocms solves this by logging **at the control plane level**, creating a single source of truth for all MCP traffic. -- view tool call volume, errors, and latency -- filter by tool/connection/agent/status -- tail logs via **Streaming** -- drill into individual calls +## Why Monitoring is First-Class -## Why this matters +### The Distributed System Problem -Monitoring is the backbone for: +MCP deployments are inherently distributed systems: +- **Multiple clients**: Cursor, Claude Desktop, custom agents +- **Multiple MCP servers**: GitHub, Slack, databases, custom tools +- **Multiple operations**: A single user workflow might invoke 10+ tools across 5 MCP servers -- debugging broken tool calls -- verifying permissions and agent selection -- tracking latency regressions and error spikes +When something breaks, you need to reconstruct what happened across this distributed system. Without centralized monitoring, you're correlating logs from different sources with different formats, timestamps, and levels of detail—if those logs even exist. + +### Control Plane Logging Solves This + +By logging at the control plane (decocms), monitoring becomes: + +**Centralized**: One place to see all tool invocations across all clients and MCP servers. + +**Consistent**: Every log entry follows the same schema with the same level of detail. + +**Complete**: No invocation can bypass monitoring—if it went through decocms, it's logged. + +**Correlated**: Request context connects related operations, enabling distributed tracing across multiple tool invocations. + +## What Gets Recorded + +Every tool invocation creates a monitoring log with: + +### Identity & Attribution +- **Caller**: Which user or API key made the request +- **Organization**: Which tenant the request belongs to +- **Connection**: Which upstream MCP server was invoked +- **Agent/Project**: If accessed through a Virtual MCP, which one + +### Operation Details +- **Tool name**: The specific tool that was invoked +- **Input arguments**: What parameters were sent (normalized and sanitized) +- **Output results**: What the tool returned +- **Timestamp**: When the invocation occurred + +### Performance & Status +- **Duration**: How long the operation took (milliseconds) +- **Status**: Success or failure +- **Error details**: If failed, what went wrong +- **HTTP status**: The underlying HTTP response code (if applicable) + +This comprehensive logging enables multiple use cases beyond debugging. + +## Use Cases Enabled by Monitoring + +### Debugging Production Failures + +When a tool invocation fails, monitoring logs provide: +- **Exact inputs**: What arguments were passed (to verify correctness) +- **Error messages**: What the MCP server returned +- **Timing context**: When the failure occurred and how long it took +- **Attribution**: Which user/agent made the request + +This information is available immediately in the decocms UI, without SSH-ing into servers or grepping log files. + +### Security & Compliance + +Monitoring creates an **immutable audit trail** of all MCP activity: +- Who accessed which tools, when +- What data was read or modified +- Which credentials were used +- Failed authorization attempts + +For regulated industries (finance, healthcare), this audit trail is essential for compliance. For any production system, it's essential for security incident response. + +### Cost & Performance Analysis + +Monitoring data reveals: +- **Expensive operations**: Which tools are slowest or most resource-intensive +- **Usage patterns**: Which tools are actually used (vs. which are just configured) +- **Bottlenecks**: Where latency spikes occur +- **Optimization opportunities**: Which Virtual MCPs could benefit from filtering or caching + +This visibility enables data-driven decisions about MCP infrastructure optimization. + +### Behavior Analysis + +Understanding how teams actually use MCP capabilities: +- **Tool adoption**: Which connections are most valuable +- **Workflow patterns**: Common sequences of tool invocations +- **Agent effectiveness**: How agents' tool selection evolves over time +- **User friction**: Where errors or retries happen most frequently + +This informs product decisions about which capabilities to prioritize or improve. + +## Monitoring as a Feedback Loop + +decocms monitoring isn't just passive logging—it creates a feedback loop that improves the platform: + +**Error patterns** → Better authorization policies or connection health checks + +**Performance data** → Virtual MCP filtering strategies or caching policies + +**Usage analytics** → Recommendations for which tools to add or deprecate + +**Security events** → Automated responses or enhanced access controls + +This feedback loop is only possible with centralized, structured monitoring. + +## Privacy & Data Handling + + +Monitoring logs include tool inputs and outputs by default. For sensitive operations (e.g., querying customer data), consider: +- Using API keys with appropriate scope restrictions +- Implementing connection-level logging policies +- Leveraging organization-level data retention controls + +decocms provides the observability infrastructure; your organization defines the privacy policies. + + +## Monitoring Philosophy + +Traditional systems treat monitoring as "nice to have"—something you add after building the core functionality. decocms inverts this: + +**Monitoring is not optional**. It's how the control plane operates. Without monitoring logs, you cannot debug, audit, optimize, or secure MCP traffic at scale. + +By making observability first-class infrastructure, decocms enables teams to run MCP in production with the same confidence they have in other critical systems. diff --git a/apps/docs/client/src/content/en/mcp-mesh/overview.mdx b/apps/docs/client/src/content/en/mcp-mesh/overview.mdx index 7af1240a4a..b8e0d86905 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/overview.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/overview.mdx @@ -8,18 +8,71 @@ import Callout from "../../../components/ui/Callout.astro"; ## What is decocms? -**decocms** is a **control plane for MCP traffic**. It sits between MCP clients (Cursor, Claude Desktop, custom agents) and MCP servers, providing a centralized layer for **authentication, authorization, credential management, and observability**. +**decocms** is a **control plane for MCP traffic**. It sits between MCP clients (like Claude Desktop, Cursor, or custom AI agents) and MCP servers (like GitHub, Slack, databases, or your custom tools), providing a centralized layer for **authentication, authorization, credential management, and observability**. -## The problem +Think of decocms as the "Kubernetes for MCP"—it manages the infrastructure layer so you can focus on building capabilities, not managing connections. -When MCP moves from a few PoCs to production usage, teams start paying an “integration tax”: +## The Problem: MCP at Scale -- **Connection sprawl**: every client wires and maintains its own MCP connections and auth -- **Inconsistent policy enforcement**: SSO/RBAC and approvals drift across apps and teams -- **Operational blind spots**: no unified logs/traces to debug failures end-to-end -- **Tool surface explosion**: too many tools increases context size, latency, and tool-selection errors +The Model Context Protocol enables AI agents to take action beyond chat—querying databases, creating pull requests, sending messages, deploying code. But when you move from a few proof-of-concepts to production usage across teams, a new set of challenges emerges: -decocms centralizes these concerns once, so you can operate MCP traffic like any other production surface. +### Connection Sprawl + +Without a control plane, every client (Cursor on your laptop, Claude Desktop, your custom agent) must independently configure and maintain connections to every MCP server it uses. Each connection requires: +- Storing credentials (API keys, OAuth tokens) +- Managing connection URLs and configuration +- Handling credential rotation +- Updating when MCP servers change + +For a team of 20 developers using 10 MCP servers, that's 200 individual connection configurations to manage. + +### Inconsistent Security & Policy + +When each client manages its own MCP connections, security policies fragment: +- Developer A can access production databases, Developer B cannot (but should) +- Credential rotation happens on different schedules across clients +- No unified answer to "who has access to what?" +- Authorization logic lives in client applications, not infrastructure + +This fragmentation makes compliance difficult and security incidents hard to investigate. + +### Operational Blind Spots + +Without centralized observability, debugging failures is painful: +- No unified logs showing which tools were invoked +- Client-side logging (if it exists) is inconsistent +- Cannot trace a request across multiple MCP servers +- No visibility into performance bottlenecks or expensive operations + +When something breaks, you're piecing together logs from different clients and servers, hoping to reconstruct what happened. + +### Tool Surface Explosion + +As you connect more MCP servers, the total number of available tools grows rapidly. A typical setup might expose: +- GitHub: 25 tools (create PR, list issues, merge, tag releases...) +- Slack: 15 tools (post message, create channel, invite user...) +- Database: 30 tools (query, insert, update, migrations...) +- Custom APIs: 40+ tools + +This creates two problems: +- **Context bloat**: Sending 100+ tool definitions to the AI consumes precious context window +- **Selection errors**: More tools means higher chance the AI picks the wrong one + +## How decocms Solves This + +decocms centralizes MCP infrastructure so these problems disappear: + +**One connection per MCP server** (configured once in decocms), not one per client. + +**Unified credential vault** with encryption at rest and rotation without client updates. + +**Single authorization layer** enforcing consistent permissions across all clients and MCP servers. + +**Built-in observability** logging every tool invocation for debugging, audit, and cost visibility. + +**Virtual MCPs** composing and filtering tool surfaces so clients see only relevant capabilities. + +By handling these concerns in infrastructure rather than application code, decocms lets teams operate MCP traffic like any other production system—with security, observability, and control. ## High-level architecture @@ -33,22 +86,54 @@ decocms centralizes these concerns once, so you can operate MCP traffic like any └──────────────────┘ ``` -## What decocms centralizes +## Platform Capabilities + +### Connection Management + +**Connect MCP servers once**, store credentials securely, and use everywhere. Whether it's GitHub, Slack, your database, or custom MCP servers—register them in decocms and they become available across all your projects and agents. + +Credentials are encrypted at rest in decocms's vault and never exposed to clients. When credentials need rotation, update once in decocms rather than updating every client. + +### Virtual MCPs: Composition Without Code + +**Dynamically compose** tool surfaces from multiple MCP servers without writing or deploying server code. Virtual MCPs aggregate tools, resources, and prompts into a single MCP-compliant endpoint that can be modified at runtime. + +This enables: +- Building curated tool surfaces for specific workflows +- Filtering large tool surfaces to reduce context size +- Adding inline resources and prompts +- Creating organizational patterns (Projects for teams, Agents for specific tasks) + +### Authorization & Access Control + +**Centralized permission management** ensures consistent security policies across all MCP traffic. Define who can access which tools, and decocms enforces authorization before proxying requests. + +API keys can be scoped to specific tools (e.g., "can create GitHub PRs but not merge them"), providing fine-grained least-privilege access for automation and integrations. + +### Complete Observability + +**Every tool invocation** flowing through decocms creates a monitoring log with: +- Tool name and connection +- Caller identity (user or API key) +- Input arguments and output results +- Duration and error status +- Request context and timestamps + +This unified audit trail enables debugging, cost analysis, security investigation, and usage analytics across your entire MCP infrastructure. + +### Multi-Tenancy & Isolation + +**Organization-scoped** isolation ensures clear boundaries between tenants. Each organization has its own: +- Connection configurations and credentials +- Virtual MCPs (projects and agents) +- Permission policies and member roles +- Monitoring logs and audit trails -- **Routing + execution**: which MCP to call and how to authenticate it -- **Policy enforcement**: who can access which tools (and through which virtual MCPs) -- **Observability**: logs, latency, errors, and request context across tool calls -- **Runtime strategies (virtual MCPs)**: different exposure strategies as tool surfaces grow +This multi-tenancy enables SaaS providers, enterprises with multiple divisions, and agencies managing client workspaces. -## Product surfaces (what you can do today) +### Self-Hosted or Cloud -- **Store**: browse a catalog of Connections you can connect to (default: the official MCP Registry). -- **Connections**: connect and manage MCP servers (HTTP MCP endpoints). -- **Hubs**: publish a curated "virtual MCP server" that aggregates tools/resources/prompts from multiple connections. -- **API Keys**: create scoped keys with explicit tool permissions. -- **Members & Roles**: invite teammates and manage roles + permissions. -- **Monitoring**: tool-call logs, errors, latency, filtering, and streaming. -- **Deploy**: self-host locally (npx / Docker Compose) or on Kubernetes (Helm). +**Deploy anywhere**: run decocms locally for development, self-host in your infrastructure (Docker Compose, Kubernetes), or use the managed cloud service. The architecture is the same regardless of deployment model—you maintain full control over your data and credentials. We're releasing decocms to the open-source community in **December 2025**. diff --git a/apps/docs/client/src/content/en/mcp-mesh/projects.mdx b/apps/docs/client/src/content/en/mcp-mesh/projects.mdx index 8a7764a083..3afcc40dba 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/projects.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/projects.mdx @@ -1,6 +1,6 @@ --- title: Projects -description: Organizational units that are virtual MCPs with their own tools, resources, and configuration +description: Organizational units for managing tools, resources, and prompts scoped to specific work contexts icon: FolderTree --- @@ -12,171 +12,58 @@ import Callout from "../../../components/ui/Callout.astro"; ## What are Projects? -**Projects** are organizational units that **are virtual MCPs themselves**. Unlike traditional project management systems where projects are mere containers, in MCP Mesh a project is a fully-functional virtual MCP server with its own tools, resources, and configuration. - -Projects enable teams to: - -- **Organize work** by product, client, or initiative -- **Scope capabilities** to specific contexts -- **Configure connections** at both project and organization levels -- **Operate within boundaries** that match your organizational structure - -Each project is accessible at `/:org/projects/:project_id` and operates as a self-contained virtual MCP. - -## Projects as Virtual MCPs - -Projects are virtual MCPs at the organization level—they are the primary organizational container for work. Each project has: - -- **Tools**: Project-specific tools or aggregated from connected MCPs -- **Resources**: Documentation, guidelines, context files -- **Prompts**: Custom templates for common workflows - -Projects can connect to other virtual MCPs (including agents), compose capabilities from multiple sources, and define inline tools—just like any [Virtual MCP](/en/mcp-mesh/virtual-mcps). The key distinction: projects ARE virtual MCPs themselves, and they can aggregate capabilities from other virtual MCPs within their scope. - -```typescript -// Example: Project as virtual MCP -{ - "projectId": "mobile-app-rewrite", - "name": "Mobile App Rewrite", - "connections": [ - { - "connectionId": "github-conn-123", - "tools": ["CREATE_PR", "LIST_ISSUES", "CREATE_BRANCH"] - }, - { - "connectionId": "figma-conn-456", - "tools": ["GET_DESIGN", "EXPORT_ASSETS"] - } - ], - "prompts": [ - { - "name": "mobile-pr-template", - "description": "PR template for mobile features", - "template": "## Mobile Feature PR\n\n### Changes\n{{changes}}\n\n### Testing\n- [ ] iOS tested\n- [ ] Android tested" - } - ], - "resources": [ - { - "uri": "project://mobile-app-rewrite/guidelines", - "name": "Mobile Development Guidelines", - "mimeType": "text/markdown", - "content": "# Mobile Guidelines\n\n- Always test on both platforms..." - } - ] -} -``` - -## Configuration Hierarchy - -MCP Mesh supports **two levels of configuration**: - -**Project-level** (`/:org/projects/:project_id`): -- Project-specific tools and resources -- Project's `CLAUDE.md` and `AGENTS.md` -- Connections configured for this project - -**Organization-level** (`/:org`): -- Organization-wide tools available across all projects -- Shared resources and prompts -- Organization `CLAUDE.md` and `AGENTS.md` - -This mirrors Claude Code's familiar pattern: **`.claude/`** (project) and **`~/.claude/`** (global). - -## Project Scope and Routing - -The route determines the operational scope. When connecting to: - -``` -/:org/projects/:project_id -``` - -MCP clients operate within that project's virtual MCP boundary, accessing: - -- Project's own resources, tools, and prompts -- Connections dynamically wired to the project -- Project-specific context from `CLAUDE.md` and `AGENTS.md` +**Projects** are organizational units that leverage [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to manage tools, resources, and prompts within a specific work context. Use projects to isolate capabilities by product, client, team, or initiative. - - Scope isolation ensures that project A cannot access project B's tools or credentials, while still allowing shared organization-level capabilities. - +Projects provide: -## CLAUDE.md and AGENTS.md Support - -Both levels support configuration files loaded into context: - -**CLAUDE.md**: Provides contextual instructions for AI agents -- **Project-level**: Project-specific coding standards, domain knowledge, workflows -- **Organization-level**: Company-wide guidelines, security policies, best practices - -**AGENTS.md**: Defines specialized capabilities via MCP server instructions -- **Project-level**: Project-specific agent configurations -- **Organization-level**: Cross-project agent configurations - -## MCP Clients in Project Scope - -When MCP clients connect to a project, they become scope-aware: - -```typescript -// MCP client operation in project scope -{ - "scope": "/:org/projects/mobile-app-rewrite", - "availableTools": [ - "CREATE_PR", // from GitHub connection - "GET_DESIGN", // from Figma connection - "RUN_MOBILE_TESTS" // project-specific tool - ], - "availableResources": [ - "project://mobile-app-rewrite/guidelines" - ] -} -``` - -AI agents can use any organization-level or project-specific capabilities to accomplish tasks, always operating within the project's boundary. - -## Example: E-commerce Redesign Project - -```typescript -{ - "projectId": "ecommerce-redesign", - "name": "E-commerce Platform Redesign", - "connections": [ - { - "connectionId": "shopify-conn-789", - "tools": ["GET_PRODUCTS", "UPDATE_THEME", "DEPLOY_STOREFRONT"] - }, - { - "connectionId": "analytics-conn-101", - "tools": ["GET_CONVERSION_RATE", "GET_USER_FLOW"] - } - ], - "resources": [ - { - "uri": "project://ecommerce-redesign/brand-guidelines", - "name": "Brand Guidelines", - "mimeType": "text/markdown" - } - ] -} -``` - -AI agents can deploy storefronts, analyze conversion metrics, and reference brand guidelines—all within the project's scope. +- **Work organization** - Group capabilities by product line, client, or feature initiative +- **Scope isolation** - Each project operates with its own set of tools and credentials +- **Contextual configuration** - Project-specific guidelines, documentation, and workflows +- **Team boundaries** - Match your organizational structure with technical boundaries -## Use Cases +Projects are available in the sidebar under the **Projects** section, where each operates as a self-contained workspace. + +## How Projects Work + +Create a project, then configure it by remixing capabilities: + +1. **Name** - Identifies the project (e.g., "Mobile App Rewrite", "Client XYZ Portal") +2. **Description** - Explains the project's purpose, scope, and goals for your team +3. **Instructions** - Guidelines for how AI agents should work in this project (like `CLAUDE.md` or `AGENTS.md`) +4. **Tools** - Actions agents may take on this project (select from [connections](/en/mcp-mesh/connections) or create inline) +5. **Resources** - Extra info for detailed skills the agent may need (documentation, guidelines, domain knowledge) +6. **Prompts** - How users are supposed to use this project (detailed workflows that combine tools and resources to accomplish specific goals) + +Since projects are [Virtual MCPs](/en/mcp-mesh/virtual-mcps), you get full composability—remix external capabilities with custom definitions to build exactly what your team needs. -- **Client Projects**: Agencies can create one project per client, each with client-specific tools and credentials -- **Product Lines**: Separate projects for web, mobile, and backend with different toolsets -- **Feature Development**: Temporary projects for major features, with curated tools for that work -- **Multi-tenant SaaS**: Projects as tenant boundaries with isolated capabilities +## Example: E-commerce Project + +An e-commerce redesign project might aggregate Shopify tools for storefront management, analytics tools for conversion tracking, and brand guidelines as resources. AI agents working in this project deploy storefronts, analyze metrics, and follow brand standards—all within the project's isolated scope. + +## Scope Isolation + +Projects enforce boundaries through routing. When AI agents connect to a project, they: + +- Access only tools configured for that project +- See project-specific resources and guidelines +- Operate within isolated credentials and permissions + +Project A cannot access Project B's tools or credentials. Organization-level capabilities remain available across all projects. + +## Use Cases -## Benefits +- **Client work** - One project per client with isolated tools and credentials +- **Product lines** - Separate mobile, web, and backend projects with distinct toolsets +- **Feature initiatives** - Temporary projects for major features with curated capabilities +- **Multi-tenancy** - Projects as tenant boundaries in SaaS applications -Projects as virtual MCPs provide: +## Why Use Projects? -- **Clear boundaries**: Scope isolation prevents cross-contamination -- **Flexible configuration**: Two-level hierarchy matches organizational structure -- **Dynamic capabilities**: Add or remove tools without infrastructure changes -- **Familiar patterns**: Mirrors `.claude/` local and `~/.claude/` global convention +- **Clear boundaries** - Prevent tool and credential cross-contamination between initiatives +- **Organized work** - Match technical scope to organizational structure +- **Flexible tooling** - Add or remove capabilities without infrastructure changes +- **Familiar patterns** - `.claude/` (project) and `~/.claude/` (global) convention --- -**Ready to create your first project?** Projects are built on [Virtual MCPs](/en/mcp-mesh/virtual-mcps)—start there to understand the underlying system. For authorization details, see [Authorization and Roles](/en/mcp-mesh/authorization-and-roles). +**Next steps**: Learn about [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to understand how projects aggregate capabilities, or see [Authorization and Roles](/en/mcp-mesh/authorization-and-roles) for access control. diff --git a/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx index eb9a905bce..2978d7970c 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx @@ -100,7 +100,7 @@ Create an API key with the minimum tool permissions needed (see [API Keys](/en/m Use **Monitoring** to confirm: -- tool calls are being logged +- tool invocations are being logged - latency + error rates show up - filters (time range, tool name, connection, agent) work as expected diff --git a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx index a54f468aeb..b4afd9d834 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx @@ -116,11 +116,14 @@ Tools and prompts use `connection_id::CAPABILITY_NAME` format (max 64 chars). Re ## Features Powered by Virtual MCPs -Virtual MCPs provide the **foundational capability** that powers specialized features across decocms. All of these inherit full [monitoring capabilities](/en/mcp-mesh/monitoring) for audit trails and observability: +Virtual MCPs provide the **foundational capability** that powers specialized features across decocms. All of these inherit full [monitoring capabilities](/en/mcp-mesh/monitoring) for audit trails and observability. + +**MCP Client Compatibility**: Virtual MCPs are callable by any MCP-compatible client—including Cursor, Claude Code, VS Code extensions, and any application that implements the Model Context Protocol. This makes your composed capability packages universally accessible across the AI tooling ecosystem. + +**Specialized features built on virtual MCPs:** - **[Agents](/en/mcp-mesh/agents)**: Single-purpose capability packages optimized for specific tasks - **[Projects](/en/mcp-mesh/projects)**: Team-scoped capability packages for organizational boundaries -- **Organization MCP**: Default capability package that aggregates all your connections ## Use Cases & Benefits @@ -130,6 +133,7 @@ Virtual MCPs turn fragmented MCP connections into unified, reusable capability p - **Unified Deployment Ops**: Package GitHub (PRs, releases) + Slack (notifications) + database (migrations) into one deployment MCP - **Custom Code Review**: Remix GitHub tools with inline security/performance prompts and team style guides - **Development Assistant**: Combine GitHub + Jira tools with inline workflow prompts and project context +- **Team-wide MCP Sharing**: Share access to a Cloudflare MCP connection across your team while filtering out administrative operations—giving developers safe, scoped access to DNS management and Workers deployment without exposing account-level controls - **Cross-system Orchestration**: Package CRM, analytics, and communication tools for end-to-end business processes **Key benefits:** diff --git a/apps/docs/client/src/content/en/no-code-guides/creating-agents.mdx b/apps/docs/client/src/content/en/no-code-guides/creating-agents.mdx index 5ff6729628..7044cc75bd 100644 --- a/apps/docs/client/src/content/en/no-code-guides/creating-agents.mdx +++ b/apps/docs/client/src/content/en/no-code-guides/creating-agents.mdx @@ -266,7 +266,7 @@ Install Pinecone from **Integrations** → **Browse Store** → **Pinecone**, th Fine-tune behavior (most agents work well with defaults): **Max Steps** (default: 15) -- How many tool calls the agent can make per response +- How many tool invocations the agent can make per response - Higher = can complete more complex tasks - Lower = faster, simpler responses @@ -334,7 +334,7 @@ Open the agent in a thread and try real conversations. Watch which tools it call Track agent performance and usage: - Go to **Usage** in your org -- See conversations, messages, tool calls, costs per agent +- See conversations, messages, tool invocations, costs per agent - Filter threads by agent to see all conversations Use these insights to: diff --git a/apps/docs/client/src/content/pt-br/introduction.mdx b/apps/docs/client/src/content/pt-br/introduction.mdx index 50b8b38ab8..c1ac6f1917 100644 --- a/apps/docs/client/src/content/pt-br/introduction.mdx +++ b/apps/docs/client/src/content/pt-br/introduction.mdx @@ -91,7 +91,7 @@ A aplicação ficará disponível em `http://localhost:8080`. - **[Visão geral](/pt-br/mcp-mesh/overview)** - **[Quickstart](/pt-br/mcp-mesh/quickstart)** - **[Conceitos](/pt-br/mcp-mesh/concepts)** -- **[MCP Servers](/pt-br/mcp-mesh/mcp-servers)** +- **[Conexões](/pt-br/mcp-mesh/connections)** - **[Virtual MCPs](/pt-br/mcp-mesh/virtual-mcps)** - **[API Keys](/pt-br/mcp-mesh/api-keys)** - **[Monitoring](/pt-br/mcp-mesh/monitoring)** diff --git a/apps/docs/client/src/i18n/ui.ts b/apps/docs/client/src/i18n/ui.ts index 93bc6437d8..fd1dfd2182 100644 --- a/apps/docs/client/src/i18n/ui.ts +++ b/apps/docs/client/src/i18n/ui.ts @@ -10,6 +10,12 @@ export const ui = { "head.title": "Deco - Docs", "sidebar.section.admin-decocms-com": "Legacy Admin", "sidebar.section.getting-started": "Getting Started", + "sidebar.section.core-concepts": "Core Concepts", + "sidebar.section.working-with-mcp": "Working with MCP", + "sidebar.section.decopilot": "Decopilot", + "sidebar.section.security": "Security & Access Control", + "sidebar.section.operations": "Operations & Deployment", + "sidebar.section.reference": "Reference", "sidebar.section.no-code-guides": "No-Code Guides", "sidebar.section.full-code-guides": "Full-Code Guides", "sidebar.section.mcp-mesh": "decocms", @@ -27,6 +33,12 @@ export const ui = { "head.title": "Deco - Documentação", "sidebar.section.admin-decocms-com": "Admin Legado", "sidebar.section.getting-started": "Primeiros Passos", + "sidebar.section.core-concepts": "Conceitos Principais", + "sidebar.section.working-with-mcp": "Trabalhando com MCP", + "sidebar.section.decopilot": "Decopilot", + "sidebar.section.security": "Segurança e Controle de Acesso", + "sidebar.section.operations": "Operações e Implantação", + "sidebar.section.reference": "Referência", "sidebar.section.no-code-guides": "Guias No-Code", "sidebar.section.full-code-guides": "Guias Full-Code", "sidebar.section.mcp-mesh": "decocms", From 11a3ff91e3610c964885ee5bea20a529a71441d8 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 09:53:49 -0300 Subject: [PATCH 22/51] docs(decopilot): simplify page titles and update cross-references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename "Context Management" → "Context" for brevity - Rename "Tasks and Agent Spawning" → "Tasks" for clarity - Update all internal links and navigation references - Maintain content structure and information hierarchy Co-Authored-By: Claude Sonnet 4.5 --- .../client/src/components/ui/Sidebar.astro | 2 +- .../{context-management.mdx => context.mdx} | 8 +++---- .../en/mcp-mesh/decopilot/overview.mdx | 22 +++++++++---------- .../en/mcp-mesh/decopilot/quickstart.mdx | 4 ++-- .../mcp-mesh/decopilot/tasks-and-spawning.mdx | 6 ++--- apps/docs/client/src/utils/navigation.ts | 2 +- 6 files changed, 21 insertions(+), 23 deletions(-) rename apps/docs/client/src/content/en/mcp-mesh/decopilot/{context-management.mdx => context.mdx} (97%) diff --git a/apps/docs/client/src/components/ui/Sidebar.astro b/apps/docs/client/src/components/ui/Sidebar.astro index 340bb905df..15f4faeb96 100644 --- a/apps/docs/client/src/components/ui/Sidebar.astro +++ b/apps/docs/client/src/components/ui/Sidebar.astro @@ -103,7 +103,7 @@ function buildTree(docs: any[]): TreeNode[] { const decopilotOrder = [ "overview", "quickstart", - "context-management", + "context", "tasks-and-spawning", "tools", "scopes", diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx similarity index 97% rename from apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx rename to apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx index 41f94fd656..27ba24f762 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context-management.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx @@ -1,5 +1,5 @@ --- -title: Context Management +title: Context description: How decopilot manages context across scopes and maintains efficient token usage icon: FileText --- @@ -7,7 +7,7 @@ icon: FileText import Callout from "../../../../components/ui/Callout.astro"; - This page documents the **planned architecture** for decopilot context management. The implementation is in development. + This page documents the **planned architecture** for decopilot context. The implementation is in development. Decopilot manages context through a priority-based system that balances completeness with efficiency. Context includes conversation history, tool definitions, resources, and project-specific instructions—all within the model's limited token window. @@ -186,7 +186,7 @@ This isolation ensures agents focus on their specific task without distraction f ## Optimizing Context in Practice -Understanding context management concepts is essential, but applying them effectively requires practical strategies. Here are proven approaches for optimizing context in real workflows. +Understanding context concepts is essential, but applying them effectively requires practical strategies. Here are proven approaches for optimizing context in real workflows. ### Strategy 1: Strategic Agent Spawning @@ -444,7 +444,7 @@ Total: ~12,300 tokens ## Summary -Decopilot balances completeness with efficiency through priority-based inclusion, tool filtering, on-demand resources, and agent spawning. Virtual MCPs enable dynamic, scope-aware context management for efficient operation within token limits. +Decopilot balances completeness with efficiency through priority-based inclusion, tool filtering, on-demand resources, and agent spawning. Virtual MCPs enable dynamic, scope-aware context for efficient operation within token limits. --- diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx index 3d40e1564c..8b3543bff5 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx @@ -48,24 +48,26 @@ Model choice affects reasoning quality, speed, and cost. Configure which model d When this documentation says "decopilot chooses" or "decopilot decides," it's the model doing the reasoning—selecting which MCP servers to query, which tools to enable, and how to coordinate work across distributed systems. -## Context Management +## Context -Context management is critical in decopilot. Your conversation history, tool definitions, resources, and MCP server configurations all compete for space in the model's limited token window. The more MCP servers you connect and tools you enable, the more context you consume. +Context is critical in decopilot. Your conversation history, tool definitions, resources, and MCP server configurations all compete for space in the model's limited token window. The more MCP servers you connect and tools you enable, the more context you consume. + +When decopilot starts a task, it loads context based on your current scope—org-level instructions, project-specific guidelines, and agent instructions are all layered according to the scope levels described above. Resources and tools are loaded strategically to keep context usage under control. Decopilot manages context through: - **Strategic tool filtering**: Only enabled tools consume context. Use the discover → enable → use pattern to keep overhead low. - **Agent spawning for isolation**: Spawn agents with fresh context for focused work. They return summaries instead of full conversation history. - **Reserved token slots**: Decopilot reserves slots for certain operations, ensuring room for critical work even when context is full. -You can always check your current context usage in the decopilot UI to understand what's consuming space and when to spawn an agent for complex work. See [Context Management](/en/mcp-mesh/decopilot/context-management) for token budgets, optimization strategies, and practical examples. +You can always check your current context usage in the decopilot UI to understand what's consuming space and when to spawn an agent for complex work. See [Context](/en/mcp-mesh/decopilot/context) for token budgets, optimization strategies, and practical examples. -## Tasks and Agent Spawning +## Tasks As you work, decopilot can delegate specialized work to **[agents](/en/mcp-mesh/agents)**—focused assistants optimized for specific tasks like customer support, research, or data analysis. When you spawn an agent, it gets its own fresh context to work independently, then reports back with a summary. This lets you handle complex work in parallel. For example, spawn a support agent to answer a customer question about product compatibility while you continue building the checkout flow. The agent works separately with clean context, preventing your main conversation from getting bloated with support details. -Learn more about when to spawn agents and spawning patterns in [Tasks and Agent Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning). +Learn more about when to spawn agents and spawning patterns in [Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning). ## Scopes @@ -85,7 +87,7 @@ Scopes layer naturally as you navigate: - **Org + Project scope**: Access org capabilities plus project-specific context - **Org + Agent scope**: Access org capabilities plus agent-specific instructions -This layered approach means you're never locked into a narrow view—org-level tools remain available even when working in focused project or agent contexts. See [Context Management](/en/mcp-mesh/decopilot/context-management#scope-specific-context-loading) for technical details on what context loads at each scope level, and [Tasks and Agent Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning) to understand how spawned agents create isolated task scopes with fresh context. +This layered approach means you're never locked into a narrow view—org-level tools remain available even when working in focused project or agent contexts. See [Context](/en/mcp-mesh/decopilot/context#scope-specific-context-loading) for technical details on what context loads at each scope level, and [Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning) to understand how spawned agents create isolated task scopes with fresh context. ## Built-in Tools @@ -101,19 +103,15 @@ These built-in tools are always available and provide the foundation for working See [Tools](/en/mcp-mesh/decopilot/tools) for complete specifications, usage patterns, and examples of coordinating tools across multiple services. -## Loading Context - -When decopilot starts a task, it loads context based on your current scope—org-level instructions, project-specific guidelines, and agent instructions are all layered according to the layers described above. Resources and tools are loaded strategically to keep context usage under control. For complete details on context loading priorities, token budgets, and optimization strategies, see [Context Management](/en/mcp-mesh/decopilot/context-management). - ## Next Steps Ready to learn more? Explore these guides to understand how decopilot works: **[Quick Start](/en/mcp-mesh/decopilot/quickstart)**: See decopilot in action with step-by-step workflows. Start here for hands-on examples. -**[Context Management](/en/mcp-mesh/decopilot/context-management)**: Learn strategies for managing token usage, when to spawn agents, and how to optimize context. +**[Context](/en/mcp-mesh/decopilot/context)**: Learn strategies for managing token usage, when to spawn agents, and how to optimize context. -**[Tasks and Agent Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning)**: Understand task lifecycles, agent selection, and patterns for parallel execution. +**[Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning)**: Understand task lifecycles, agent selection, and patterns for parallel execution. **[Tools](/en/mcp-mesh/decopilot/tools)**: Complete reference for built-in tools and working with target virtual MCP tools. diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx index bf1ada8054..e16b3bff2b 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx @@ -583,11 +583,11 @@ if (status.status === "completed") { **[Scopes](/en/mcp-mesh/decopilot/scopes)**: Understand how org/project/agent scopes determine behavior and tool availability. Essential for effective decopilot use. -**[Tasks and Agent Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning)**: Learn advanced patterns for agent spawning, including fan-out/fan-in, conditional spawning, and agent selection. +**[Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning)**: Learn advanced patterns for agent spawning, including fan-out/fan-in, conditional spawning, and agent selection. **[Tools](/en/mcp-mesh/decopilot/tools)**: Explore the comprehensive toolset, discover patterns, and troubleshoot common issues. -**[Context Management](/en/mcp-mesh/decopilot/context-management)**: Optimize token usage through strategic agent spawning and context filtering. +**[Context](/en/mcp-mesh/decopilot/context)**: Optimize token usage through strategic agent spawning and context filtering. **[Architecture](/en/mcp-mesh/decopilot/architecture)**: Deep-dive into decopilot's technical implementation and distributed MCP coordination. diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx index 8922cc0cdd..a99e099fc7 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx @@ -1,5 +1,5 @@ --- -title: Tasks and Agent Spawning +title: Tasks description: How decopilot uses tasks with isolated contexts and spawns agents for parallel execution icon: Layers --- @@ -173,7 +173,7 @@ Spawned tasks receive isolated context with selective inheritance. - Parent-loaded resources - Parent context accumulation -Results integrate as 200-500 token summaries. See [Context Management](/en/mcp-mesh/decopilot/context-management) for details. +Results integrate as 200-500 token summaries. See [Context](/en/mcp-mesh/decopilot/context) for details. ## Agent Selection and Discovery @@ -642,4 +642,4 @@ const coordinatorTask = await decopilot.invokeTool("agent_spawn", { --- -**Ready to start?** See [Tools](/en/mcp-mesh/decopilot/tools) for agent_spawn details, [Context Management](/en/mcp-mesh/decopilot/context-management) for isolation mechanics, or [Scopes](/en/mcp-mesh/decopilot/scopes) for scope effects. +**Ready to start?** See [Tools](/en/mcp-mesh/decopilot/tools) for agent_spawn details, [Context](/en/mcp-mesh/decopilot/context) for isolation mechanics, or [Scopes](/en/mcp-mesh/decopilot/scopes) for scope effects. diff --git a/apps/docs/client/src/utils/navigation.ts b/apps/docs/client/src/utils/navigation.ts index 7cc8bfbd18..d6964aee04 100644 --- a/apps/docs/client/src/utils/navigation.ts +++ b/apps/docs/client/src/utils/navigation.ts @@ -39,7 +39,7 @@ export async function getNavigationLinks( // 6. Decopilot "mcp-mesh/decopilot/overview", "mcp-mesh/decopilot/quickstart", - "mcp-mesh/decopilot/context-management", + "mcp-mesh/decopilot/context", "mcp-mesh/decopilot/tasks-and-spawning", "mcp-mesh/decopilot/tools", "mcp-mesh/decopilot/scopes", From d54e613ba62827fa54c9289a818358e11c17da53 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 12:01:43 -0300 Subject: [PATCH 23/51] docs(decopilot): simplify scopes page for non-technical users Significantly condensed and simplified the scopes documentation: - Reduced from 444 lines to 74 lines (83% reduction) - Removed technical implementation details (route patterns, code examples) - Replaced "organization settings" with "organization view" and "project view" - Simplified scope determination to two factors: view location + agent selection - Removed Virtual MCP technical sections - Made language more user-friendly and accessible Co-Authored-By: Claude Sonnet 4.5 --- .../content/en/mcp-mesh/decopilot/scopes.mdx | 452 ++---------------- 1 file changed, 41 insertions(+), 411 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx index c07f35225c..acf52e567d 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/scopes.mdx @@ -1,6 +1,6 @@ --- title: Scopes -description: Understanding scope-based routing and how decopilot operates across different virtual MCP contexts +description: Understanding how decopilot adapts to different contexts and what's available at each level icon: Target --- @@ -12,444 +12,74 @@ import Callout from "../../../../components/ui/Callout.astro"; ## What is Scope? -**Scope** is the current virtual MCP context in which decopilot operates. It determines what tools, resources, and prompts are available, and how decopilot behaves when you interact with it. +**Scope** is decopilot's current working context—it determines what instructions, tools, and resources are available as you work. -Unlike traditional tools that operate in a single global context, decopilot is **scope-sensitive**—it automatically adapts based on where you are in the application. Think of scope as your current working environment that changes as you navigate routes in decocms. - -Scope affects every operation: tool availability, resource reading, prompt loading, and tool execution. This architecture ensures isolation (projects cannot access each other's tools), security (access control at the scope level), and clarity (you always know what capabilities are available). +Scope links your current task context with an MCP (Model Context Protocol server) where tools, resources, and prompts are pulled from. Decopilot automatically adapts based on which view you're in, shifting between organization and project contexts. ## Three Scope Types -Decopilot operates in three distinct scopes, each a **virtual MCP** with its own capabilities. - -### Org Scope - -**Route**: `/:org/settings`, `/:org/connections` - -**Behavior**: Operates like an org-admin, similar to `~/.claude` in Claude Code. Provides org-wide resources, prompts, and tools accessible across all projects and agents. This is the foundation level where shared context is defined. - -### Project Scope - -**Route**: `/:org/projects/:project_id` +**Organization Scope**: Work on organization-wide infrastructure, connections, and team management. -**Behavior**: Projects **ARE virtual MCPs**, not containers. Each project is a self-contained MCP server with project-specific tools, resources, and connected MCPs (GitHub, Figma, etc.). Mirrors Claude Code's `.claude/` pattern—isolated work context. +**Project Scope**: Day-to-day development work with project-specific tools and resources. -### Agent Scope - -**Route**: `/:org/agents/:agent_id` - -**Behavior**: Agents **ARE virtual MCPs** optimized for single-purpose tasks. They are bounded and focused, with agent-specific capabilities and resources. Most narrowly focused scope for repeatable, well-defined tasks. +**Agent Scope**: Focused, specialized tasks with bounded capabilities (security reviews, code analysis, testing). ## How Scope is Determined -Scope is **automatically determined by the route** you navigate to in decocms. As you move through the application, decopilot seamlessly adapts to the new context. - -```mermaid -graph LR - A[Route: /:org/settings] --> B[Org Scope] - C[Route: /:org/projects/:id] --> D[Project Scope] - E[Route: /:org/agents/:id] --> F[Agent Scope] - - B --> G[Org Virtual MCP] - D --> H[Project Virtual MCP] - F --> I[Agent Virtual MCP] - - G --> J[Org Tools/Resources/Prompts] - H --> K[Project Tools/Resources/Prompts] - I --> L[Agent Tools/Resources/Prompts] -``` - -### Route-to-Scope Mapping - -| Route Pattern | Scope Type | Virtual MCP | -|---|---|---| -| `/:org/settings` | Org | Organization virtual MCP | -| `/:org/connections` | Org | Organization virtual MCP | -| `/:org/projects/:project_id` | Project | Project-specific virtual MCP | -| `/:org/projects/:project_id/settings` | Project | Project-specific virtual MCP | -| `/:org/agents/:agent_id` | Agent | Agent-specific virtual MCP | -| `/:org/agents/:agent_id/config` | Agent | Agent-specific virtual MCP | - -## Scope-Sensitive Operations - -All decopilot operations are **scope-aware**. The current scope determines what happens when you execute commands, read resources, or invoke tools. - - - The examples below use conceptual API syntax to illustrate scope behavior. - - -### Reading Resources - -```typescript -// Resources are read from the current scope's virtual MCP -decopilot.readResource("org://guidelines") // Org scope -decopilot.readResource("project://mobile-app/arch") // Project scope -decopilot.readResource("agent://reviewer/checklist") // Agent scope -``` - -### Tool Availability - -```typescript -// Tools depend on the current scope -decopilot.listTools() -// Org: ["ORG_CONNECTION_CREATE", "ORG_RESOURCE_CREATE", ...] -// Project: ["CREATE_PR", "GET_DESIGN", "RUN_TESTS", ...] -// Agent: ["REVIEW_CODE", "ANALYZE_SECURITY", ...] -``` - -## Practical Scope Workflows - -Understanding scope concepts is essential, but seeing them in action clarifies how they enable real work. Here are practical workflows demonstrating each scope type. - -### Workflow 1: Org-Level Setup - -**Context**: You're setting up organization-wide resources and connections. - -**Route**: `/:org/settings` - -**Operations**: - -```typescript -// 1. Create org-level CLAUDE.md with coding standards -await resource_create({ - uri: "org://coding-standards", - name: "CLAUDE.md", - content: `# Coding Standards - -## Style -- Use TypeScript strict mode -- Prefer functional patterns -- Document public APIs - -## Security -- Never commit credentials -- Validate all user input -- Use parameterized queries` -}) - -// 2. Connect external MCP servers at org level -await connection_create({ - name: "GitHub Organization", - type: "github", - scope: "org", - config: { - org: "my-company", - auth: "oauth" - } -}) - -await connection_create({ - name: "Slack Workspace", - type: "slack", - scope: "org", - config: { - workspace: "my-company", - channel_defaults: ["#engineering", "#deploys"] - } -}) +Scope is determined by **two simple factors**: -// 3. Create shared security policy resource -await resource_create({ - uri: "org://security-policy", - name: "Security Policy", - content: `# Security Policy +1. **Which view you're in**: Organization view or project view +2. **Agent selection**: Whether you have an agent selected in the bottom-left of the chat -## Authentication -- Use OAuth 2.1 with PKCE -- Require MFA for production access +**When viewing organization**: +- No agent selected → **Organization scope** +- Agent selected → **Agent scope** -## Data Handling -- Encrypt PII at rest and in transit -- Implement data retention policies` -}) +**When viewing a project**: +- No agent selected → **Project scope** +- Agent selected → **Agent scope** -// 4. Define org-wide prompt templates -await prompt_create({ - name: "code-review-template", - scope: "org", - template: `Review this code for: -1. Security vulnerabilities -2. Performance issues -3. Code style adherence -4. Test coverage` -}) -``` - -**Result**: Organization foundation established. All projects inherit these resources, connections, and prompts. - -### Workflow 2: Project Development - -**Context**: You're working on a mobile app project, coordinating across multiple services. - -**Route**: `/:org/projects/mobile-app` - -**Operations**: +Each scope is completely isolated—there's no inheritance between scopes. When you select an agent, you only have access to that agent's specific tools and resources. -```typescript -// 1. Read project CLAUDE.md (inherits org + project-specific) -const guidelines = await resource_read({ - uri: "project://mobile-app/guidelines" -}) -// Returns: Org coding standards + project-specific patterns +## Scope and Subtasks -// 2. Use GitHub tools to create branch (via org GitHub connection) -await tool_enable({ tool_name: "CREATE_BRANCH" }) -await CREATE_BRANCH({ - repo: "mobile-app", - name: "feature/push-notifications", - base: "main" -}) +[Subtasks](/en/mcp-mesh/decopilot/tasks-and-spawning) can run in different scopes than your main task—this enables agent collaboration. -// 3. Use Figma tools to export assets (via project Figma connection) -await tool_enable({ tool_name: "EXPORT_ASSETS" }) -await EXPORT_ASSETS({ - file_id: "mobile-app-designs", - node_ids: ["notification-icons"], - format: "svg" -}) - -// 4. Create project resource for architecture decisions -await resource_create({ - uri: "project://mobile-app/architecture-decisions", - name: "Architecture Decision: Push Notifications", - content: `# ADR: Push Notifications - -## Decision -Use Firebase Cloud Messaging (FCM) for cross-platform push. - -## Rationale -- Native iOS/Android support -- Reliable delivery -- Cost effective at scale - -## Alternatives Considered -- OneSignal (3rd party dependency) -- Native APNS/GCM (platform-specific complexity)` -}) - -// 5. Spawn security agent for review -await agent_spawn({ - agent_id: "security-reviewer", - task: "Review push notification implementation for security", - context: { - files: ["src/notifications/push.ts"], - focus: "credential storage, message encryption" - } -}) -``` +**Example**: While working in project scope on order fulfillment, you can spawn multiple agents: +- **Inventory Agent** - Assesses stock availability +- **Shipping Agent** - Plans logistics +- **Customer Service Agent** - Prepares support strategy -**Result**: Feature developed with project-specific context, coordinating GitHub, Figma, and security review—all scoped to the project. +Your main task coordinates the strategy while each agent handles specialized work in isolation. -### Workflow 3: Agent Execution - -**Context**: A spawned security agent is reviewing code with bounded capabilities. - -**Route**: `/:org/agents/security-reviewer` - -**Operations**: - -```typescript -// 1. Read agent-specific checklist resource -const checklist = await resource_read({ - uri: "agent://security-reviewer/checklist" -}) -// Returns: Security-specific checklist, not full project context - -// 2. Use bounded tools for security scanning -await tool_enable({ tool_name: "SECURITY_SCAN" }) -const scanResults = await SECURITY_SCAN({ - files: ["src/notifications/push.ts"], - rules: ["credential-exposure", "insecure-storage", "xss"] -}) -// => { -// findings: [ -// { -// severity: "high", -// rule: "credential-exposure", -// message: "FCM server key hardcoded on line 42" -// } -// ] -// } - -// 3. Check known vulnerabilities -await tool_enable({ tool_name: "CVE_LOOKUP" }) -const cveResults = await CVE_LOOKUP({ - dependencies: ["firebase-admin", "node-notifier"] -}) - -// 4. Generate findings report (can't modify project resources) -return { - status: "completed", - findings: { - critical: ["FCM server key hardcoded"], - high: [], - medium: ["Consider rate limiting push notifications"], - info: ["Update firebase-admin to latest version"] - } -} -``` - -**Result**: Security analysis completed with fresh context and bounded tools. Agent cannot modify project resources—only reads and returns findings. - -## Scope Transitions - -When you navigate between routes, decopilot automatically transitions between scopes. Understanding these transitions helps you predict behavior. - -### Org → Project Transition - -```typescript -// Before: /:org/settings (Org scope) -await tools_list() -// => ["ORG_CONNECTION_CREATE", "ORG_RESOURCE_CREATE", ...] - -// Navigate to: /:org/projects/mobile-app - -// After: /:org/projects/mobile-app (Project scope) -await tools_list() -// => [ -// // Inherited org tools -// "ORG_CONNECTION_CREATE", -// // Project-specific tools -// "CREATE_PR", "EXPORT_ASSETS", "RUN_TESTS", -// // Inline project tools -// "RUN_MOBILE_TESTS_ALL_PLATFORMS" -// ] -``` - -**What changes**: -- Context switches from org to project virtual MCP -- Tool availability updates (adds project + external MCP tools) -- Resource inheritance recalculates (org resources + project resources) -- Connected MCPs refresh (org connections + project connections) - -### Project → Agent Transition - -```typescript -// Before: /:org/projects/mobile-app (Project scope) -await tools_list() -// => ["CREATE_PR", "EXPORT_ASSETS", "RUN_TESTS", ...] - -// Spawn agent: agent_spawn({ agent_id: "security-reviewer", ... }) - -// Inside agent: /:org/agents/security-reviewer (Agent scope) -await tools_list() -// => [ -// // Only bounded agent tools -// "SECURITY_SCAN", "CVE_LOOKUP", "CODE_ANALYSIS" -// ] -``` - -**What changes**: -- Context switches to isolated agent virtual MCP -- Tool availability dramatically narrows (bounded to agent purpose) -- Resources limited to agent-specific only (no automatic project inheritance) -- Fresh token context (no pollution from parent scope) - -**Key insight**: Agent scope is intentionally restricted. This prevents agents from accidentally modifying project state and keeps their context focused. - -## When to Use Each Scope - -Knowing which scope to operate in for different tasks improves efficiency and organization. - -### Use Org Scope When: - -**Setting up infrastructure**: -- Connecting external MCP servers (GitHub org, Slack workspace, Figma teams) -- Creating organization-wide resources (coding standards, security policies) -- Defining shared prompt templates -- Managing organization members and permissions - -**Example tasks**: -- "Connect our GitHub organization" -- "Create org-wide coding standards" -- "Set up Slack integration for all projects" - -### Use Project Scope When: - -**Developing features**: -- Creating branches, pull requests, commits -- Coordinating work across multiple services (GitHub + Figma + Slack) -- Creating project-specific resources (architecture decisions, test plans) -- Using connected MCP tools for project work - -**Example tasks**: -- "Create a PR for the authentication feature" -- "Export Figma assets for the onboarding flow" -- "Run the mobile test suite on all platforms" -- "Document the architecture decision for push notifications" - -### Use Agent Scope When: - -**Running focused, repeatable tasks**: -- Security reviews with specialized scanning -- Code quality analysis with bounded tools -- Research tasks exploring specific architecture -- Testing workflows with dedicated test runners - -**Example tasks**: -- "Review this authentication code for security vulnerabilities" -- "Analyze performance of the notification service" -- "Research state management patterns in the codebase" -- "Run comprehensive integration tests" - -**Decision rule**: If the task needs full project context and multiple services, use project scope. If the task is focused, repeatable, and benefits from isolation, spawn an agent. - - -Start in project scope for most work. Spawn agents when you need: -- **Parallel execution** (security review while implementing) -- **Fresh context** (researching architecture without bloat) -- **Bounded capabilities** (testing, analysis, review tasks) + +Start in project scope for most work. Switch to agents when you need specialized capabilities or parallel execution. -## Virtual MCPs at Every Level - -**Everything in decocms is a virtual MCP**. Orgs, projects, and agents are all virtual MCPs with tools, resources, prompts, and configuration. The scope hierarchy creates an inheritance model where projects and agents access org-level capabilities while maintaining their own scope-specific additions. - -## Practical Examples - -### Project Scope Example - -Working on a mobile app project (`/:org/projects/mobile-app`): - -```typescript -// Tools include GitHub, Figma, project-specific capabilities -decopilot.listTools() -// Returns: CREATE_PR, GET_DESIGN, RUN_MOBILE_TESTS +## Switching Scopes -// Read project context -decopilot.readResource("project://mobile-app/guidelines") +Use the agent selector at the bottom-left of the chat to switch between scopes: -// Create PR using project's GitHub connection -decopilot.invokeTool("CREATE_PR", { - title: "Add login screen" -}) +**Example workflow**: ``` - -### Agent Scope Example - -Using a code review agent (`/:org/agents/code-reviewer`): - -```typescript -// Bounded tools for specific task -decopilot.listTools() -// Returns: SECURITY_REVIEW, PERFORMANCE_REVIEW, CODE_ANALYSIS - -// Execute security analysis -decopilot.invokeTool("SECURITY_REVIEW", { - code: "const query = `SELECT * FROM users WHERE id = ${userId}`" -}) +Project (no agent) → implementing features + ↓ +Select security agent → agent scope for security review + ↓ +Deselect agent → back to project scope ``` +When you switch, decopilot automatically adjusts available tools and context. + ## Key Takeaways -- **Scope is fundamental**: Every operation happens within a scope -- **Routes determine scope**: Navigation automatically changes context -- **Three scope types**: Org, Project, Agent -- **Everything is a virtual MCP**: Each level has tools, resources, and prompts -- **Automatic adaptation**: Decopilot adjusts behavior as you navigate +- **Scope adjusts automatically** based on which view you're in and whether an agent is selected +- **Three scope types** provide different capabilities: organization, project, and agent +- **Each scope is isolated** with its own tools and resources +- **Agents are focused** on specialized tasks to maintain clarity -Understanding scope is essential to using decopilot effectively—it ensures clarity, security, and organization. +Understanding scope helps you work effectively with decopilot—you'll know what's available and how to organize your work. --- -**Ready to dive deeper?** Learn about [Virtual MCPs](/en/mcp-mesh/virtual-mcps) or explore [Projects](/en/mcp-mesh/projects). +**Next steps**: Explore [Tools](/en/mcp-mesh/decopilot/tools) to see what decopilot can do, or check out [Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning) to understand task organization. From b3bfb0ef23e1d6c99adaa66900c579992180760e Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 12:06:01 -0300 Subject: [PATCH 24/51] docs(api): add decopilot built-in tools reference Added comprehensive documentation for decopilot's built-in tools: - Tool discovery & enablement (tool_search, tool_enable) - Agent management (agent_search) - Task management (subtask_run) - User interaction (user_ask) - Context access (resource_read, prompt_read) Includes descriptions, restrictions, and expected output for each tool. Co-Authored-By: Claude Sonnet 4.5 --- .../src/content/en/mcp-mesh/api-reference.mdx | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference.mdx index b2f4a49833..a669317c59 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/api-reference.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference.mdx @@ -35,4 +35,69 @@ Aggregates tools/resources/prompts across multiple connections. - `GET /health` - `GET /metrics` +## Decopilot Built-in Tools + +These tools are provided by decopilot and are always available (subject to task/subtask restrictions). + +### Tool Discovery & Enablement + +**`tool_search(search_term?: string)`** +- Searches for tools available in the current scope (organization, project, or agent) +- Returns tools from the current scope's virtual MCP only +- Empty search returns all available tools in the current scope +- Output: Array of tool definitions with name, description, and source + +**`tool_enable(tool_name: string)`** +- Enables a tool for use in the current task +- Can only enable tools that exist in the current scope's virtual MCP +- Tool remains enabled for task duration only +- Must be called before invoking target tools +- Output: Success status and enabled confirmation + +### Agent Management + +**`agent_search(search_term?: string)`** +- Searches for agents configured in the organization +- Returns agent metadata including purpose and capabilities +- Empty search returns all available agents +- **Restriction**: Tasks only (not available in subtasks) +- Output: Array of agent definitions + +### Task Management + +**`subtask_run(prompt: string, agent_id?: string)`** +- Spawns a subtask with isolated context +- Optionally specify an agent to use for the subtask +- If agent_id is omitted, subtask uses current scope capabilities +- Subtask runs until completion, then returns results +- **Restriction**: Tasks only (not available in subtasks) +- Output: Subtask results and completion status + +### User Interaction + +**`user_ask(question: string, options?: object)`** +- Asks the user a question to gather input or clarification +- Supports text input, multiple choice, or confirmation +- Task status changes to "Needs Input" until user responds +- **Restriction**: Tasks only (not available in subtasks) +- Output: User's response + +### Context Access + +**`resource_read(resource_uri: string, lineStart?: number, lineEnd?: number)`** +- Reads a resource from the current scope +- Supports scope inheritance (project inherits from org, agent inherits from project+org) +- Parameters: + - `resource_uri`: URI identifier for the resource + - `lineStart`: Starting line number (default: 0) + - `lineEnd`: Ending line number (default: 20) + - Set both to 0 to read entire resource +- Output: Resource content and metadata + +**`prompt_read(prompt_name: string, lineStart?: number, lineEnd?: number)`** +- Reads a prompt template from the current scope +- Supports scope inheritance like resources +- Same line range parameters as resource_read +- Output: Prompt template content and metadata + From 283c5a4168b06b655ca18d49b2aa7ba8dbf7c8e4 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 12:06:10 -0300 Subject: [PATCH 25/51] docs(decopilot): simplify context page for non-technical users Significantly condensed and simplified the context documentation: - Reduced from 442 lines to 141 lines (68% reduction) - Introduced accessible "context window" and "working memory" metaphors - Added clear "40/80 rule" for context health monitoring - Removed technical scope inheritance tables and code examples - Simplified language around context slots and compactification - Made content more user-friendly and less implementation-focused Co-Authored-By: Claude Sonnet 4.5 --- .../content/en/mcp-mesh/decopilot/context.mdx | 491 ++++-------------- 1 file changed, 95 insertions(+), 396 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx index 27ba24f762..7ebd315f41 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/context.mdx @@ -1,6 +1,6 @@ --- title: Context -description: How decopilot manages context across scopes and maintains efficient token usage +description: Understanding context windows and how decopilot keeps your workspace focused and efficient icon: FileText --- @@ -10,442 +10,141 @@ import Callout from "../../../../components/ui/Callout.astro"; This page documents the **planned architecture** for decopilot context. The implementation is in development. -Decopilot manages context through a priority-based system that balances completeness with efficiency. Context includes conversation history, tool definitions, resources, and project-specific instructions—all within the model's limited token window. +Every AI [model](https://code.claude.com/docs/en/how-claude-code-works#models) works within a fixed context window—think of it as the model's "working memory" for your conversation. Managing this space well is essential for smooth, productive workflows with decopilot. -## How Context Loading Works +Decopilot automatically balances what goes into your context window: instructions from your current [scope](/en/mcp-mesh/decopilot/overview#scopes), available [tools](/en/mcp-mesh/concepts#tools), conversation history, and more. Larger context windows mean you can accomplish more complex work in a single session before needing to refresh. -When decopilot starts a task, it loads context in priority order. This ensures essential context is always present while managing token usage efficiently: +## Understanding Context Slots -1. **System instructions**: Core behavior definition (always present, ~800 tokens) -2. **CLAUDE.md**: Organization and project persistent rules (scope-dependent, see below) -3. **AGENTS.md**: Agent-specific instructions via MCP server's instructions property (only for spawned agents) -4. **Conversation history**: Recent messages automatically managed and truncated as needed -5. **MCP tool definitions**: Only enabled tools consume context (filtered by agent type to reduce overhead) -6. **Resources**: Loaded on-demand when explicitly requested through tool invocations +Decopilot organizes your context window into distinct slots, each serving a specific purpose: -The priority system ensures essential instructions and rules are loaded first, with heavier elements (conversation history, tools, resources) added strategically based on need and scope. +1. **System prompt** - Core decopilot behavior and capabilities +2. **Scope instructions** - Guidelines from your current scope (organization, project, or agent-specific) +3. **Built-in tools** - Essential decopilot operations always available +4. **Enabled tools** - Additional [tools](/en/mcp-mesh/concepts#tools) you've activated during your session +5. **Conversation history** - Your recent messages and decopilot's responses +6. **Compactification buffer** - Summarized older conversation context -## Scope-Specific Context Loading +This slot system ensures the most important context stays available while managing space efficiently. -Different scopes load different context automatically. Understanding scope-based loading helps you work efficiently and avoid unnecessary context bloat. +## Context Health: The 40/80 Rule -### Organization Scope +Your context window performs best when it's not too full. Here's what to watch for: -When working at org scope (the default level): -- **System instructions**: Always present -- **Org CLAUDE.md**: Organization-wide rules and standards -- **Org-level tools**: Tools enabled at organization level -- **Conversation history**: Current session -- **NO project-specific context**: No project CLAUDE.md, no project tools +- **Below 40%**: Optimal performance—plenty of room for complex reasoning and long conversations +- **40-80%**: Context starts to degrade—still functional but approaching limits +- **Above 80%**: Time to refresh—decopilot automatically compactifies your conversation history -Use org scope for cross-project work, administrative tasks, or when you don't need project-specific context. +When your context reaches 80% capacity, decopilot automatically clears the conversation history slot and compactifies it into the buffer. This process summarizes your conversation while preserving important context, giving you room to continue working. -### Project Scope - -When working at project scope: -- **System instructions**: Always present -- **Org CLAUDE.md**: Inherited from organization -- **Project CLAUDE.md**: Project-specific rules (takes precedence on conflicts) -- **Project tools**: Tools enabled at project level -- **Conversation history**: Current session -- **Resources**: Available on-demand through `resource_read` - -Project scope inherits org context and adds project-specific layers. This is the most common scope for development work. - -### Agent Scope - -When you spawn an agent: -- **System instructions**: Always present -- **CLAUDE.md**: Inherited based on spawn location (org or project) -- **AGENTS.md**: Agent-specific instructions from MCP server's instructions property -- **Task prompt**: The specific task you assigned -- **Filtered tools**: Only tools relevant to agent type -- **NO parent conversation history**: Fresh context, no accumulated history from parent -- **NO parent resources**: Clean slate, loads own resources if needed - -Agent scope provides fresh, focused context for specific tasks. See [Context Isolation via Agent Spawning](#context-isolation-via-agent-spawning) for details. - -### Context Inheritance - -| Context Element | Org Scope | Project Scope | Agent Scope (from project) | -|----------------|-----------|---------------|---------------------------| -| System instructions | ✓ | ✓ | ✓ | -| Org CLAUDE.md | ✓ | ✓ (inherited) | ✓ (inherited) | -| Project CLAUDE.md | ✗ | ✓ | ✓ (inherited) | -| AGENTS.md | ✗ | ✗ | ✓ | -| Parent conversation | ✓ (own) | ✓ (own) | ✗ (fresh start) | -| Parent resources | N/A | N/A | ✗ (clean slate) | - -See [Scopes](/en/mcp-mesh/decopilot/overview#scopes) in the overview for more on how scope layering works in practice. - -## CLAUDE.md Support - -CLAUDE.md provides persistent context at two levels: **org scope** for organization-wide rules, and **project scope** for project-specific guidelines. When working in project scope, both org and project CLAUDE.md files are loaded—project context inherits from org context. - -**Precedence handling**: When both levels define conflicting rules, project-level CLAUDE.md takes precedence. This allows project-specific overrides while maintaining organization-wide defaults. For example, an org-admin might enforce Conventional Commits across all projects, but a specific project could override commit message format for integration with external systems. - -**Conflict resolution**: Decopilot merges non-conflicting rules. If org-admin specifies testing requirements and project-level adds deployment guidelines, both apply. Only direct conflicts trigger precedence resolution. - -**Best practices**: Keep CLAUDE.md concise (under 500 words), focus on persistent rules rather than one-time instructions, use clear markdown formatting, and update content as patterns emerge across multiple conversations. - -### Example: Project-Level CLAUDE.md - -```markdown -# Mobile App Project - -## Stack -- React Native 0.74, TypeScript 5.9, Expo SDK 52 - -## Code Conventions -- Functional components with hooks -- API calls in `src/services/` -- Colocate tests, use Zod for validation - -## Testing -- Run `bun test` before committing -``` - -### Example: Org-Admin Level CLAUDE.md - -```markdown -# Organization Guidelines - -## Principles -- Security first: validate all inputs -- WCAG 2.1 AA compliance -- Update docs alongside code - -## Git Workflow -- Conventional commits: `type(scope): message` -- PR review required -``` - -## AGENTS.md Support - -AGENTS.md provides agent-specific instructions via the MCP server's `instructions` property. **This content only appears in agent scope**—when decopilot spawns an agent. When spawned from project scope, agents receive both org CLAUDE.md and project CLAUDE.md plus AGENTS.md. When spawned from org scope, agents receive only org CLAUDE.md plus AGENTS.md. - -### Example: AGENTS.md Structure - -```markdown -# Agent Instructions - -## Research Agents -**Purpose**: Explore and analyze without modification - -**Guidelines**: -- Read-only operations only -- Document findings in structured format -- Tools: LIST_FILES, READ_FILE, SEARCH_CODE - -## Development Agents -**Purpose**: Implement features and fix bugs - -**Guidelines**: -- Create feature branches -- Write tests alongside implementation -- Tools: CREATE_BRANCH, COMMIT_CHANGES, RUN_TESTS -``` - -## Context Cost Management - -Tool definitions consume significant tokens—a typical MCP server with 50 tools can use 5,000-10,000 tokens just for tool definitions. With Claude's 200K context window, unfiltered tools from multiple servers quickly exhaust available space. - -**Token cost examples**: A single comprehensive tool definition (name, description, parameters with JSON schema) averages 100-200 tokens. A project with 3 MCP servers (filesystem, git, API client) exposing 150 total tools could consume 15,000-30,000 tokens before any conversation begins. This leaves less room for conversation history, code context, and reasoning. - -### Tool Filtering - -Virtual MCPs enable dynamic filtering based on agent type and task requirements. Rather than exposing all tools to every agent, decopilot selectively includes only relevant tools: - -```typescript -// Research agent sees filtered tools -{ - agentType: "research", - tools: ["LIST_FILES", "READ_FILE", "SEARCH_CODE"] - // CREATE_PR, DEPLOY filtered out -} -``` - -**Filtering strategies**: Development agents receive write operations (CREATE_BRANCH, COMMIT_CHANGES), research agents get read-only tools (READ_FILE, SEARCH_CODE), and deployment agents access infrastructure tools (DEPLOY, ROLLBACK). This reduces average tool context from 15,000 tokens to 3,000-5,000 tokens depending on agent type. - -Resources load only when explicitly requested through tool invocations, preventing automatic inclusion in base context. This on-demand approach keeps initial context minimal while providing access to full project resources when needed. - -## Context Isolation via Agent Spawning - -Agent spawning provides fresh context for specific tasks. As decopilot works through complex problems, context accumulates—conversation history grows, resources are loaded, and the context window fills. Spawning an agent creates clean context focused on one task, then integrates results back without polluting the parent context. - -**Technical implementation**: Each spawned agent receives a new task ID and isolated context. The parent decopilot maintains its conversation history and resources, while the child agent starts with only essential context. When the agent completes, results are summarized and returned to the parent—typically 200-500 tokens instead of the full 10,000+ token conversation the agent had. - -Spawned agents receive: -- System instructions, CLAUDE.md, AGENTS.md -- Task description and filtered tools -- NO parent conversation history or accumulated resources - -This isolation ensures agents focus on their specific task without distraction from unrelated context. A security review agent doesn't need to know about UI design decisions from earlier in the conversation. A documentation agent doesn't need git history from unrelated branches. - -**Benefits**: Faster processing due to smaller context, better focus on specific objectives, parallel execution of independent tasks, and cleaner results integrated back to parent. See [Task-Based Agent Spawning](/en/mcp-mesh/decopilot/architecture#task-based-agent-spawning) for implementation details. - -## Optimizing Context in Practice - -Understanding context concepts is essential, but applying them effectively requires practical strategies. Here are proven approaches for optimizing context in real workflows. - -### Strategy 1: Strategic Agent Spawning - -**Problem**: Main context becomes bloated with exploratory work, test results, and detailed analysis. - -**Solution**: Spawn agents for any work that generates significant context but doesn't need to persist in the main conversation. - -**Example: Context Bloat (Avoid)** - -```typescript -// Main decopilot context -User: "Implement push notifications" - -// Decopilot explores options (adds ~5000 tokens) -- Researches Firebase Cloud Messaging -- Compares with OneSignal, APNs, AWS SNS -- Reads documentation for each -- Analyzes pros/cons - -// Implements feature (adds ~8000 tokens) -- Creates notification service files -- Implements iOS handler -- Implements Android handler -- Adds error handling - -// Tests implementation (adds ~6000 tokens) -- Runs unit tests (full output) -- Runs integration tests -- Reviews test results -- Fixes failing tests - -// Total context: ~19,000 tokens for one feature -// Main conversation is polluted with exploratory details -``` - -**Example: Fresh Context Isolation (Better)** - -```typescript -// Main decopilot context (~2000 tokens total) -User: "Implement push notifications" - -// Spawn research agent (isolated context) -const researchTask = await agent_spawn({ - agent_id: "research-agent", - prompt: "Research push notification solutions. Compare Firebase, OneSignal, AWS SNS. Recommend best fit." -}) -// Agent generates ~5000 tokens internally -// Returns ~300 token summary: "Recommend Firebase Cloud Messaging because..." - -// Spawn development agent (isolated context) -const devTask = await agent_spawn({ - agent_id: "development-agent", - prompt: "Implement Firebase Cloud Messaging for push notifications. Support iOS and Android." -}) -// Agent generates ~8000 tokens internally -// Returns ~400 token summary: "Implemented push service in src/notifications/..." - -// Spawn testing agent (isolated context) -const testTask = await agent_spawn({ - agent_id: "testing-agent", - prompt: "Write tests for push notification service. Test all platforms." -}) -// Agent generates ~6000 tokens internally -// Returns ~300 token summary: "Tests passing. Coverage 94%..." - -// Main context: ~2000 + 300 + 400 + 300 = ~3000 tokens total -// Fresh context for each task, summaries only in main conversation -``` - -**Key insight**: Spawning agents prevents context bloat by isolating detailed work. Main conversation stays focused on high-level decisions and results. - -### Strategy 2: Resource Management - -**Problem**: Loading all project resources upfront exhausts context before work begins. - -**Solution**: Load resources on-demand only when actually needed for specific tasks. - -**Example: Upfront Loading (Avoid)** - -```typescript -// Load everything upfront -await resource_read({ uri: "project://mobile-app/architecture" }) // 2000 tokens -await resource_read({ uri: "project://mobile-app/api-docs" }) // 3000 tokens -await resource_read({ uri: "project://mobile-app/testing-guide" }) // 1500 tokens -await resource_read({ uri: "org://coding-standards" }) // 1000 tokens -await resource_read({ uri: "org://security-policy" }) // 1500 tokens - -// Total: 9000 tokens consumed before any work starts -// Most resources never actually used -``` - -**Example: On-Demand Loading (Better)** - -```typescript -// Load only what's needed for current task -User: "Add biometric authentication" - -// Only load architecture doc (relevant to feature design) -const arch = await resource_read({ uri: "project://mobile-app/architecture" }) -// 2000 tokens - actually used - -// If security question arises later, load then -const security = await resource_read({ uri: "org://security-policy" }) -// 1500 tokens - loaded when needed - -// Total: 3500 tokens, all actually used -``` - -**Key insight**: Resources should be loaded just-in-time. Don't preemptively load "everything that might be useful." - -### Strategy 3: Tool Filtering + +You can manually trigger compactification anytime using the `/compact` command—useful when you want to free up space before starting a new phase of work. + -**Problem**: All tools from all connected MCP servers are included in context, even if irrelevant. +## Keeping Context Lean -**Solution**: Enable only the tools you actually need for the current task. +The best way to work efficiently is to avoid filling your context unnecessarily. Here are two key techniques: -**Example: Unfiltered Tools (Wasteful)** +### Compactification -```typescript -// All tools available from 3 connected MCPs: -// - GitHub MCP: 50 tools (~5000 tokens) -// - Figma MCP: 30 tools (~3000 tokens) -// - Slack MCP: 20 tools (~2000 tokens) -// Total: 100 tools, ~10,000 tokens +Compactification summarizes older conversation history while preserving key information. Think of it as consolidating your notes—you keep the important decisions and outcomes, but remove the back-and-forth exploration that led there. -// But task only needs GitHub PR creation -``` +**When to compact:** +- Automatically triggers at 80% context capacity +- Manually via `/compact` command before starting complex work +- After completing a major task but before moving to the next one -**Example: Selective Enabling (Efficient)** +### Subtasks -```typescript -// Search for specific tools needed -const tools = await tools_search({ search_term: "pull request" }) +Using subtasks for specific work keeps your main context clean. Subtasks run in their own isolated context space, then return only a summary of results to your main conversation. You can optionally spawn [agents](/en/mcp-mesh/agents)—specialists in specific fields—into subtasks to bring domain expertise to the isolated work. -// Enable only what's needed -await tool_enable({ tool_name: "CREATE_PR" }) -await tool_enable({ tool_name: "LIST_FILES" }) +**Example with subtask only:** -// Context: ~200 tokens for 2 tools vs 10,000 for all ``` - -**Key insight**: The discover → enable → use pattern naturally filters tools. Only enabled tools consume context. - -### Strategy 4: Scope Awareness - -**Problem**: Working in wrong scope, loading unnecessary inherited context. - -**Solution**: Use the most specific scope appropriate for your task. See [Scopes](/en/mcp-mesh/decopilot/overview#scopes) for details on scope-based capabilities and [Scope-Specific Context Loading](#scope-specific-context-loading) for what context is available at each level. - -**Example: Wrong Scope (Bloated)** - -```typescript -// Working in org scope when you need project-specific work -// Org scope includes: -// - All org-level tools (~3000 tokens) -// - All org resources (~5000 tokens) -// - Org CLAUDE.md (~500 tokens) -// But you're implementing a project feature - -// Total: ~8500 tokens of irrelevant org context +You: "Spawn subtask to analyze stock ruptures" + │ + ▼ +Decopilot creates subtask + │ + ▼ +Subtask analyzes inventory (isolated context) + │ + ▼ +Returns: "3 critical SKUs need reorder, 5 can wait..." + │ + ▼ +Main context: Only sees summary ``` -**Example: Right Scope (Focused)** +**Example with specialist agent:** -```typescript -// Navigate to project scope: /:org/projects/mobile-app -// Project scope includes: -// - Project-specific tools (~2000 tokens) -// - Project resources (~2000 tokens) -// - Project CLAUDE.md + inherited org CLAUDE.md (~800 tokens) -// All relevant to the project feature - -// Total: ~4800 tokens, all relevant ``` - -**Key insight**: Navigate to the most specific scope for your work. Don't work in org scope when you need project context. - -## Context Budget Examples - -Understanding typical token budgets helps plan workflows and predict when to spawn agents. - -### Scenario 1: Simple PR Creation - -**Task**: Create a pull request for a completed feature. - -**Context breakdown**: -``` -System instructions: ~800 tokens -CLAUDE.md (project): ~500 tokens -Conversation history: ~1000 tokens (user request + planning) -Tool definitions: ~100 tokens (CREATE_PR only) -Total: ~2400 tokens +You: "Use inventory specialist to analyze stock ruptures" + │ + ▼ +Decopilot searches for agents + │ + ▼ +Finds: "Inventory Optimizer" & "Supply Chain Analyst" + │ + ▼ +Decopilot: "Which agent would you prefer?" + │ + ▼ +You: "Inventory Optimizer" + │ + ▼ +Spawns Inventory Optimizer as subtask + │ + ▼ +Specialist forecasts demand, optimizes reorders (isolated context) + │ + ▼ +Returns: "Reorder 500 units SKU-123 from supplier B..." + │ + ▼ +Main context: Only sees summary ``` -**Remaining budget**: ~197,600 tokens available for PR creation, tool responses, and conversation. - -**Assessment**: Plenty of room. No need for agent spawning. Single-task workflow works well. +This pattern is especially powerful for: +- Research and exploration tasks +- Running tests and analyzing results +- Code reviews and security scans +- Any work that generates lots of output you don't need to see in full detail -### Scenario 2: Complex Multi-Agent Workflow +See [Agents](/en/mcp-mesh/agents) for more on how agents provide fresh, focused context for specific tasks. -**Task**: Implement feature with research, development, testing, and review. +## How Scopes Affect Context -**Context breakdown (without agent spawning)**: -``` -System instructions: ~800 tokens -CLAUDE.md (project): ~500 tokens -Research work: ~5000 tokens (exploration, docs) -Development work: ~8000 tokens (implementation, iteration) -Testing work: ~6000 tokens (test runs, results) -Review work: ~4000 tokens (security scan, findings) -Tool definitions: ~5000 tokens (many tools enabled) -Conversation history: ~10,000 tokens (accumulated) -Total: ~39,300 tokens -``` +Each [scope](/en/mcp-mesh/decopilot/scopes) has access only to its own tools and resources. When you switch scopes, the tools available through `tool_search` change to match that scope's virtual MCP, and the instructions that load into the scope instructions slot change—organization, project, or agent-specific. See [Scopes](/en/mcp-mesh/decopilot/scopes) for details. -**Remaining budget**: ~160,700 tokens +## Practical Tips -**Assessment**: Works but polluted context. Better approach: spawn agents. +Here are actionable ways to keep your context healthy and productive: -**With agent spawning**: -``` -System instructions: ~800 tokens -CLAUDE.md (project): ~500 tokens -Research summary: ~300 tokens (from spawned agent) -Development summary: ~400 tokens (from spawned agent) -Testing summary: ~300 tokens (from spawned agent) -Review summary: ~300 tokens (from spawned agent) -Tool definitions: ~100 tokens (minimal in main) -Conversation history: ~2000 tokens (high-level only) -Total: ~4700 tokens -``` +**Watch your context health** - Pay attention to how full your context is. When it hits 40%, consider wrapping up the current phase of work or compacting. -**Remaining budget**: ~195,300 tokens +**Use `/compact` strategically** - Manually compact before starting complex new work, after completing major tasks, or when switching between different focus areas. -**Assessment**: Much more efficient. Main context stays focused. Each agent worked with fresh context. +**Spawn agents for heavy lifting** - Research, testing, code reviews, and any work that generates verbose output should happen in spawned agents. Keep summaries, not details, in your main context. -### Scenario 3: Research Agent Spawn +**Enable tools selectively** - Don't enable every available tool "just in case." Enable tools from your current scope as you need them for specific tasks. -**Task**: Spawned agent exploring codebase architecture. +**Work in the right scope** - Use organization scope for cross-project work, project scope for focused development, and let agents handle task-specific work with fresh context. -**Context breakdown (spawned agent)**: -``` -System instructions: ~800 tokens -CLAUDE.md (project): ~500 tokens -AGENTS.md (research): ~300 tokens -Task prompt: ~200 tokens -Tool definitions: ~500 tokens (read-only tools) -Agent conversation: ~10,000 tokens (detailed exploration) -Total: ~12,300 tokens -``` +**Think modular** - Break complex work into phases. Complete one phase, compact or spawn for the next. This keeps each phase focused and your context manageable. -**Parent receives**: ~400 token summary of findings +## Why Context Matters -**Key insight**: Agent uses ~12,300 tokens internally, but parent only receives ~400. Fresh context enables deep work without polluting parent. +Good context management isn't just about staying under limits—it's about maintaining quality. When context is clean and focused: -## Summary +- Decopilot reasons more clearly about your specific problem +- Conversations stay on track without getting lost in accumulated details +- Complex multi-step workflows remain manageable +- You spend more time making progress, less time resetting context -Decopilot balances completeness with efficiency through priority-based inclusion, tool filtering, on-demand resources, and agent spawning. Virtual MCPs enable dynamic, scope-aware context for efficient operation within token limits. +By understanding how context works and using the tools available—compactification, agent spawning, selective tool enabling—you can work more effectively with decopilot across projects of any complexity. --- -Explore [Scopes](/en/mcp-mesh/decopilot/scopes) to understand how routing determines context, or [Task-Based Agent Spawning](/en/mcp-mesh/decopilot/architecture#task-based-agent-spawning) for fresh context isolation. +**Next steps**: Learn about [Scopes](/en/mcp-mesh/decopilot/overview#scopes) to understand how context changes at different levels, or explore [Agents](/en/mcp-mesh/agents) to see how fresh context isolation works in practice. From 3e8045e84170d1eb010edf649343170eec1551f5 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 12:06:16 -0300 Subject: [PATCH 26/51] docs(decopilot): simplify tasks page for non-technical users Significantly condensed and simplified the tasks documentation: - Reduced from 645 lines to 191 lines (70% reduction) - Replaced technical "agent spawning" language with user-friendly "tasks and subtasks" - Added clear task state explanations (In Progress, Requires Action, Success, Failed) - Introduced task timeout behavior (30 minutes) with practical guidance - Removed internal implementation details (threads vs tasks terminology) - Made content more accessible to non-technical users Co-Authored-By: Claude Sonnet 4.5 --- .../mcp-mesh/decopilot/tasks-and-spawning.mdx | 660 +++--------------- 1 file changed, 103 insertions(+), 557 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx index a99e099fc7..6b3f9c0943 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tasks-and-spawning.mdx @@ -1,645 +1,191 @@ --- title: Tasks -description: How decopilot uses tasks with isolated contexts and spawns agents for parallel execution +description: Understanding how tasks and subtasks keep your work organized and context efficient icon: Layers --- import Callout from "../../../../components/ui/Callout.astro"; - This page documents the **planned architecture** for agent spawning in decopilot. The implementation is in development. + This page documents the **planned architecture** for tasks in decopilot. The implementation is in development. -## What is Agent Spawning? +## What Are Tasks? -Agent spawning creates isolated tasks with specialized agents to accomplish specific work. Decopilot creates a new task with fresh context, delegates work, and integrates results when complete. +A **task** is your conversation with decopilot. It's where work happens—where you chat back and forth, decopilot uses tools, and context accumulates as you progress. -Think of spawning as delegating to focused specialists. Decopilot breaks work into focused tasks, spawns agents for each piece, and orchestrates results. +Tasks are accessible throughout decocms: +- **Homepage** - Your organization's chat interface shows the current task +- **Sidebar** - Click the chat icon to open the side panel and continue your task +- **Task history** - Browse past tasks to review previous work -A **task** is an isolated chat session with a specific agent. The codebase uses "threads" internally, but UI and documentation use "tasks." Future versions will unify terminology. +Every task has a [scope](/en/mcp-mesh/decopilot/scopes) (organization, project, or agent) that determines which instructions load into context. You can switch scopes anytime using the button at the bottom of the chat input—switch between organization-wide work, project-specific focus, or specialized agent scopes as needed. -Learn more in [Agents](/en/mcp-mesh/agents) and [Virtual MCPs](/en/mcp-mesh/virtual-mcps). +Think of tasks as persistent workspaces where context builds up naturally as you work. -## Benefits of Task Spawning +## Task States and Monitoring -**Parallel execution**: Spawn multiple agents for independent work simultaneously. +Tasks move through different states as work progresses. Understanding these states helps you manage work and know when tasks need your attention. -**Context isolation**: Each task gets fresh context focused on its objective. Parent context doesn't pollute child tasks. +### Task Status Overview -**Focused capabilities**: Agents have bounded tool access appropriate to their purpose. +Every task has one of four statuses: -**Efficient token usage**: Fresh context means minimal overhead. Results integrate as summaries. +- **In Progress** - Active work happening, agent is executing or waiting for next message +- **Requires Action** - Paused, waiting for your input (tool approval or question response) +- **Success** - Work completed successfully +- **Failed** - Something went wrong or task timed out -**Composable workflows**: Break complex work into focused steps handled by specialized agents. +### When Tasks Require Attention -## Understanding Tasks vs Threads +Tasks pause and transition to "Requires Action" status when: -The codebase uses "threads" for what users see as "tasks." This terminology will converge with "tasks" becoming consistent throughout. +**Tool approval needed** - Some tools require explicit user approval before execution. The task pauses until you review and approve or deny the tool call. -**For users**: Think "tasks"—the UI shows tasks. +**Question from agent** - When decopilot needs clarification or decisions, it asks questions using the `user_ask` tool. The task waits for your response. -**For developers**: Currently "threads" in code, transitioning to "tasks." +You can see all tasks requiring attention by clicking the **tasks icon** in the decocms sidebar. This view shows tasks grouped by status—letting you quickly identify which tasks need your input. -Spawned agents create child tasks with limited context inheritance. +### Task Timeouts -## How agent_spawn Works +Tasks automatically timeout after **30 minutes of inactivity**. When this happens: -The `agent_spawn` tool creates a new task with a specified agent and prompt. +- Task transitions from "In Progress" to "Failed" status +- You'll see the timeout noted in task history +- You can restart work by creating a new task -**Signature**: `agent_spawn(agent_id: string, prompt: string): task_id: string` +Timeouts prevent tasks from staying in limbo indefinitely. If you're working on something that naturally takes longer, just send a message or interact with the task periodically to keep it active. -**Behavior**: Creates new task with agent's [virtual MCP](/en/mcp-mesh/virtual-mcps), passes prompt as initial message, parent continues immediately. +### Viewing Subtask Progress -```typescript -const taskId = await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer-001", - prompt: "Review src/auth/login.ts for vulnerabilities." -}) -``` +Subtasks appear in the chat interface while they execute. You can see: -The spawned task runs independently. Parent doesn't block—results return when task completes. +- Subtask status and progress +- Tools being used +- Agent reasoning (if enabled) -### Complete Spawn Lifecycle Example +However, **inputs are disabled** during subtask execution—you can't interact with a subtask directly. Subtasks run autonomously and return summaries to the parent task when complete. -Understanding the full lifecycle from spawn to completion helps predict behavior and handle edge cases. +## What Are Subtasks? -```typescript -// T0: Parent task spawns security agent -const taskId = await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer", - prompt: "Review src/auth/biometric.ts for security vulnerabilities" -}) -// Returns immediately: { task_id: "task-abc-123" } -// Task status: "active" +A **subtask** is a separate conversation that branches off from your main task to handle focused work. The key difference: subtasks start with fresh [context](/en/mcp-mesh/decopilot/context)—they don't inherit your accumulated conversation history. -// T1: Spawned agent starts executing -// - Loads agent virtual MCP configuration -// - Reads CLAUDE.md (org + project context) -// - Reads AGENTS.md (agent-specific instructions) -// - Receives prompt as initial message -// - Begins agentic loop (gather → act → verify) +This makes subtasks perfect for intensive work that would otherwise fill up your main context window. -// T2: Agent discovers and enables tools -await tools_search({ search_term: "security" }) -await tool_enable({ tool_name: "SECURITY_SCAN" }) +### How Subtasks Work -// T3: Agent invokes tools -const scanResults = await SECURITY_SCAN({ - files: ["src/auth/biometric.ts"], - rules: ["credential-exposure", "insecure-storage"] -}) +When you spawn a subtask: -// T4: Agent generates response -// Response includes findings, recommendations, severity levels -// Task status transitions: "active" -> "successful" +1. **Fresh start** - Subtask begins with clean context (just scope instructions and system prompt) +2. **Independent execution** - Subtask is a regular task with restricted built-in tools (no `subtask_run` or `user_ask`) +3. **Summary return** - Parent task receives only a concise summary (200-500 tokens) +4. **Full details preserved** - Complete subtask conversation saved in task history -// T5: Parent task receives result notification -// Result integrated as ~200-500 token summary: -// "Security review complete. Found 2 high-severity issues: -// 1. Biometric templates stored without encryption (line 42) -// 2. Auth threshold too permissive (line 68) -// See full report in task-abc-123" +The parent task sees just the summary—keeping your main conversation lean—while full details remain accessible in the subtask history. -// T6: Parent continues with integrated findings -await resource_create({ - uri: "project://mobile-app/security-findings", - name: "Security Review: Biometric Auth", - content: scanResults.report -}) -``` +### Key Differences -**Key lifecycle points**: -- Spawn returns immediately (non-blocking) -- Agent loads isolated context -- Agent executes autonomously -- Results integrate as summaries -- Parent task continues throughout +| Feature | Main Task | Subtask | +|---------|-----------|---------| +| Context | Accumulated history | Fresh, clean start | +| Available tools | All built-in tools + current scope's tools | Same, but no `subtask_run` or `user_ask` | +| Result visibility | Full conversation | Summary only to parent | +| User interaction | Can ask questions (`user_ask`) | Cannot ask questions | -## Task States and Lifecycle +Subtasks can't spawn additional subtasks (prevents infinite nesting) and can't ask user questions (they run autonomously). -**Active**: Task being processed by agent. +## When to Use Subtasks -**Needs Input**: Requires user input to continue (via `user_ask` tool or cheap model determination). +Subtasks shine when you need focused work that would clutter your main conversation. -**Successful**: Task completed. Cheap model detects completion criteria. +### Research and Analysis -**Failed**: Encountered error preventing completion. +Deep dives into data, exploring options, or investigating issues work well in subtasks. -```typescript -const taskId = await decopilot.invokeTool("agent_spawn", { - agent_id: "research-agent", - prompt: "Analyze architecture" -}) -// Active -> needs_input (if user_ask) -> active -> successful -``` +**Example**: You're planning inventory purchases and need demand analysis. Spawn a subtask to research sales trends, seasonal patterns, and competitor behavior—then get back just the recommendation, not the dozens of data points analyzed. -Handle `needs_input` state by providing input via task UI: +### Complex Calculations -```typescript -// Task calls user_ask -> needs_input state -// Navigate to task, provide input -// Task resumes -> active state -``` +Number-crunching work that generates verbose output belongs in subtasks. -## Task Variants: Top-level vs Child +**Example**: Calculating optimal shipping routes across multiple warehouses. The subtask analyzes distances, traffic, carrier schedules—you get back just the routing plan, not the calculation details. -**Top-level tasks** are user-initiated with full tool access: -- `user_ask` available -- `agent_spawn` available -- Full access to built-in and virtual MCP tools +### Quality Checks and Reviews -**Child tasks** are agent-spawned with restrictions: -- `user_ask` disabled (prevents blocking on input) -- `agent_spawn` disabled by default (prevents deep nesting) -- Access to other tools - -Child tasks work with provided information, return partial results if clarification needed, or fail gracefully. The parent calls `user_ask` and re-spawns with additional context. - -This maintains flat hierarchy: top-level spawns children, children return results, top-level coordinates. - -## Context Isolation and Inheritance - -Spawned tasks receive isolated context with selective inheritance. - -**Spawned agents receive**: -- System instructions -- CLAUDE.md (org/project rules) -- AGENTS.md (agent-specific instructions) -- Task prompt -- Filtered tools - -**Spawned agents do NOT receive**: -- Parent conversation history -- Parent-loaded resources -- Parent context accumulation - -Results integrate as 200-500 token summaries. See [Context](/en/mcp-mesh/decopilot/context) for details. - -## Agent Selection and Discovery - -The `agent_search` tool discovers available agents. - -**Signature**: `agent_search(search_term?: string): Agent[]` - -**Output**: List with `agent_id`, `name`, `purpose`, `capabilities`. - -```typescript -const result = await decopilot.invokeTool("agent_search", { - search_term: "security" -}) -``` - -Specialized agents optimize for their purpose and produce better results. - -## Choosing the Right Agent - -Selecting the appropriate agent for your task improves results and reduces iteration. Different agent types excel at different work. - -### Research Agents - -**Best for**: -- Exploring codebases and understanding architecture -- Investigating bugs and tracing execution paths -- Analyzing options before making decisions -- Understanding third-party libraries and APIs - -**Characteristics**: -- Read-heavy tool access (file reading, code search, documentation lookup) -- No write permissions (safe for exploratory work) -- Fresh context ideal for deep dives +Audits, validation, and review work benefit from isolated context. -**Example usage**: -```typescript -await decopilot.invokeTool("agent_spawn", { - agent_id: "research-agent", - prompt: "Analyze the authentication flow in src/auth/. Map the complete user login journey from form submission to session creation." -}) -``` +**Example**: Before transferring 500 SKUs between warehouses, spawn a subtask with an "Inventory Auditor" agent to verify stock levels. Get back a summary of issues found and transfers validated—keep the detailed audit work out of your main task. -### Development Agents - -**Best for**: -- Implementing features based on specifications -- Writing code with clear requirements -- Refactoring existing code -- Adding tests for new functionality - -**Characteristics**: -- Read and write tool access (file editing, code generation) -- Focused on implementation, not exploration -- Benefits from clear specs and acceptance criteria - -**Example usage**: -```typescript -await decopilot.invokeTool("agent_spawn", { - agent_id: "development-agent", - prompt: "Implement push notification service using Firebase Cloud Messaging. Requirements: support iOS and Android, handle background notifications, respect user preferences." -}) -``` - -### Review Agents - -**Best for**: -- Code quality analysis -- Security vulnerability scanning -- Performance profiling -- Accessibility auditing - -**Characteristics**: -- Specialized analysis tools (linters, security scanners, profilers) -- Domain expertise in specific review type -- Generate structured findings reports +### Parallel Work -**Example usage**: -```typescript -await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer", - prompt: "Review src/auth/biometric.ts for security issues. Focus on credential storage, authentication bypass risks, and biometric data handling. Report findings with severity levels." -}) -``` +When you have independent operations that can run simultaneously, spawn multiple subtasks. -### Testing Agents - -**Best for**: -- Writing unit tests for new code -- Creating integration tests -- Running test suites and analyzing failures -- Generating test data +**Example**: Monthly reporting across departments—spawn separate subtasks for apparel, electronics, and home goods analysis. All run in parallel, summaries come back to your main task for synthesis. -**Characteristics**: -- Test framework tools (Jest, Pytest, etc.) -- Coverage analysis capabilities -- Can execute tests and interpret results +## Working with Agent Scopes -**Example usage**: -```typescript -await decopilot.invokeTool("agent_spawn", { - agent_id: "testing-agent", - prompt: "Write comprehensive unit tests for src/notifications/push.ts. Cover success cases, error handling, edge cases. Aim for 90%+ coverage." -}) -``` - -### Deployment Agents - -**Best for**: -- Releasing features to staging/production -- Infrastructure configuration -- Deployment verification -- Rollback procedures - -**Characteristics**: -- Deployment pipeline tools (kubectl, terraform, CI/CD) -- Environment-specific configurations -- Health check and monitoring capabilities - -**Example usage**: -```typescript -await decopilot.invokeTool("agent_spawn", { - agent_id: "deployment-agent", - prompt: "Deploy feature/push-notifications to staging. Run health checks. Monitor for 5 minutes. Report deployment status and any errors." -}) -``` - -### Decision Guide - -Use this flowchart to choose the right agent: - -``` -Need to understand code? → Research Agent - ├─ Exploring architecture - ├─ Investigating bugs - └─ Analyzing options - -Need to write code? → Development Agent - ├─ Implementing features - ├─ Refactoring - └─ Adding tests - -Need to check quality? → Review Agent - ├─ Security scan → Security Reviewer - ├─ Performance → Performance Analyzer - └─ Accessibility → Accessibility Checker - -Need to test? → Testing Agent - ├─ Unit tests - ├─ Integration tests - └─ Test execution - -Need to deploy? → Deployment Agent - ├─ Staging release - ├─ Production deploy - └─ Rollback -``` - -**Pro tip**: When unsure, use `agent_search` with descriptive terms to find specialized agents: -```typescript -await decopilot.invokeTool("agent_search", { - search_term: "security vulnerability scanning" -}) -``` - -## UI Integration and Task Management - -**Tasks menu**: Shows all tasks for current scope with status indicators. - -**Task list view**: Displays tasks with active/needs input/successful/failed indicators. - -**Task detail view**: Full conversation history with chat interface (top-level) or read-only view (child). - -**Notifications**: Badge counts and toasts for state changes. +Subtasks can run in different [agent](/en/mcp-mesh/agents) scopes than your main task—this is how specialized agents collaborate. -Monitor multiple agents, respond when needed, review results when complete. +**Example**: Your main task is in organization scope working on order fulfillment. You spawn subtasks using: +- **Inventory Agent** - Assesses stock availability +- **Shipping Agent** - Plans logistics and routing +- **Customer Service Agent** - Prepares support strategies -## Spawning Workflows - -### Single Task Spawn +Each agent brings specialized expertise. Your main task coordinates the overall strategy while agents handle domain-specific details in isolation. -Spawn one agent for focused work on a single objective. +This pattern keeps specialized work contained while letting you benefit from agent expertise. -```typescript -const taskId = await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer-001", - prompt: "Review auth files for vulnerabilities. Report with severity levels." -}) -``` +## Common Patterns -### Parallel Task Spawning +### Pattern 1: Parallel Execution -Spawn multiple agents simultaneously for independent work that can run concurrently. +Spawn multiple subtasks for independent work that can run simultaneously. -```typescript -const archTaskId = await decopilot.invokeTool("agent_spawn", { - agent_id: "research-agent-001", - prompt: "Analyze architecture patterns." -}) +**When to use**: Monthly reporting, multi-department analysis, independent validations -const secTaskId = await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer-001", - prompt: "Perform security audit." -}) -``` +**Benefit**: Faster execution, isolated contexts prevent cross-contamination -### Sequential Workflow +### Pattern 2: Sequential Delegation -Spawn agents in sequence where each task depends on previous results. +Chain subtasks where each step builds on previous results. -```typescript -// Research options -const researchTaskId = await decopilot.invokeTool("agent_spawn", { - agent_id: "research-agent-001", - prompt: "Research React state libraries." -}) +**When to use**: Multi-stage workflows, progressive refinement, decision pipelines -// Implement chosen solution -const devTaskId = await decopilot.invokeTool("agent_spawn", { - agent_id: "development-agent-001", - prompt: "Implement Zustand store." -}) +**Benefit**: Clear progression, focused subtasks, results build toward comprehensive outcome -// Test implementation -const testTaskId = await decopilot.invokeTool("agent_spawn", { - agent_id: "testing-agent-001", - prompt: "Write tests for store." -}) -``` +### Pattern 3: Specialist Collaboration -## Advanced Spawning Patterns +Use different agent scopes for subtasks requiring specialized knowledge. -Beyond basic single or parallel spawning, these advanced patterns enable sophisticated workflows. +**When to use**: Cross-functional work, domain expertise needed, coordinated strategies -### Pattern 1: Fan-out/Fan-in +**Benefit**: Leverage specialized agents, integrate multi-domain insights -Spawn multiple agents for parallel work, then collect and synthesize results. +## Practical Tips -```typescript -// Fan-out: Spawn multiple review agents -const securityTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer", - prompt: "Security audit of src/auth/" -}) +**Offload heavy lifting** - Research, calculations, and analysis should happen in subtasks. Keep summaries in your main task, not verbose details. -const performanceTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "performance-analyzer", - prompt: "Performance analysis of src/auth/" -}) +**Match scope to work** - Use specialized agents for domain tasks, organization scope for general work. The right scope brings relevant instructions and context. -const accessibilityTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "accessibility-checker", - prompt: "Accessibility audit of auth UI" -}) +**Work in parallel** - Independent subtasks can run simultaneously. Don't wait if the next subtask doesn't depend on the previous one. -// All three tasks run in parallel, each with isolated context +**Name clearly** - Give descriptive prompts when spawning: "Analyze Q4 apparel demand trends" rather than "Do analysis". This helps when reviewing task history. -// Fan-in: Collect results (after tasks complete) -// Results integrate as summaries -// Parent synthesizes findings: +**Review full details when needed** - The complete subtask conversation lives in task history. If you need raw data or detailed analysis, open the subtask from history. -await resource_create({ - uri: "project://mobile-app/auth-review-summary", - name: "Authentication Review Summary", - content: `# Authentication Review +**Watch for clutter signals** - When your main task feels heavy or context-full, spawn subtasks for the next phase of work. -## Security -${securityTaskResults} +## Context Benefits -## Performance -${performanceTaskResults} - -## Accessibility -${accessibilityTaskResults} - -## Action Items -[Synthesized priorities based on all findings]` -}) -``` - -**When to use**: Comprehensive analysis requiring multiple specialized perspectives. Each agent brings domain expertise. - -**Benefits**: -- Parallel execution (faster than sequential) -- Isolated contexts (no cross-contamination) -- Specialized focus (each agent optimized) - -### Pattern 2: Conditional Spawning - -Spawn agents based on runtime conditions or previous task results. - -```typescript -// Step 1: Research implementation options -const researchTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "research-agent", - prompt: "Research React state management options. Compare Redux, Zustand, Jotai. Recommend best fit for our architecture." -}) - -// Step 2: Wait for research completion -// (In practice, decopilot integrates results automatically) - -// Step 3: Conditional spawn based on recommendation -if (researchResults.recommendation === "Zustand") { - // Spawn Zustand implementation agent - await decopilot.invokeTool("agent_spawn", { - agent_id: "development-agent", - prompt: "Implement Zustand store following the research recommendations. Focus on user state management." - }) -} else if (researchResults.recommendation === "Redux") { - // Spawn Redux implementation agent - await decopilot.invokeTool("agent_spawn", { - agent_id: "development-agent", - prompt: "Implement Redux store with Redux Toolkit following best practices." - }) -} - -// Step 4: Always spawn testing agent after implementation -await decopilot.invokeTool("agent_spawn", { - agent_id: "testing-agent", - prompt: "Write comprehensive tests for the state management implementation." -}) -``` - -**When to use**: Multi-stage workflows where later steps depend on earlier results. - -**Benefits**: -- Adaptive workflows (adjust based on findings) -- Efficient resource use (only spawn what's needed) -- Clear decision points - -### Pattern 3: Iterative Refinement - -Spawn agents in a loop to refine results based on quality checks. - -```typescript -// Iteration 1: Initial implementation -let implementationTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "development-agent", - prompt: "Implement biometric authentication with Face ID support" -}) - -// Quality check -const qualityTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer", - prompt: "Review biometric implementation. Check for security issues." -}) - -// Iteration 2: If issues found, refine -if (qualityResults.criticalIssues.length > 0) { - implementationTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "development-agent", - prompt: `Refine biometric implementation addressing: -${qualityResults.criticalIssues.map(issue => `- ${issue}`).join('\n')} - -Focus on security and correctness.` - }) - - // Re-check quality - await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer", - prompt: "Re-review refined implementation. Verify issues addressed." - }) -} -``` +Subtasks are powerful for managing your [context window](/en/mcp-mesh/decopilot/context): -**When to use**: Quality-critical work requiring validation and refinement cycles. +- **Main task stays lean** - Only summaries accumulate, not analysis details +- **Fresh context for complexity** - Subtasks start clean, ideal for deep work +- **Longer productivity** - Avoid premature compactification in main task +- **Focused execution** - Each subtask tackles one thing without baggage -**Benefits**: -- Ensures quality standards met -- Fresh context for each iteration -- Clear validation checkpoints - -### Pattern 4: Pipeline Architecture - -Chain agents in a processing pipeline where each stage adds value. - -```typescript -// Stage 1: Research -const researchTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "research-agent", - prompt: "Research push notification best practices. Document patterns." -}) - -// Stage 2: Implement (uses research findings) -const implementTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "development-agent", - prompt: "Implement push notifications using research findings. Follow documented patterns." -}) - -// Stage 3: Test (validates implementation) -const testTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "testing-agent", - prompt: "Write integration tests for push notification system. Test all platforms." -}) - -// Stage 4: Review (ensures quality) -const reviewTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer", - prompt: "Security review of push notification implementation. Check credential handling." -}) - -// Stage 5: Document (captures knowledge) -const docTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "documentation-agent", - prompt: "Document push notification system: setup, usage, troubleshooting." -}) - -// Each stage builds on previous work, creating comprehensive delivery -``` - -**When to use**: Complex features requiring multiple specialized stages (research → implement → test → review → document). - -**Benefits**: -- Clear separation of concerns -- Each agent focuses on one aspect -- Comprehensive feature delivery -- Knowledge capture throughout - -### Pattern 5: Hierarchical Delegation - -Spawn a coordinator agent that spawns its own sub-agents (requires enabling `agent_spawn` in child tasks). - -```typescript -// Top-level: Spawn feature coordinator -const coordinatorTask = await decopilot.invokeTool("agent_spawn", { - agent_id: "feature-coordinator", - prompt: "Coordinate implementation of complete authentication system: backend API, frontend UI, testing, documentation.", - allowChildSpawn: true // Enable agent_spawn in child task -}) - -// Coordinator spawns sub-agents: -// - backend-agent for API implementation -// - frontend-agent for UI components -// - testing-agent for test suites -// - documentation-agent for docs - -// Coordinator manages dependencies and integration -// Top-level task receives final coordinated result -``` - -**When to use**: Very complex features requiring orchestration of multiple work streams. - -**Caution**: Increases complexity. Use sparingly and only when clear coordination benefits exist. - -**Benefits**: -- Distributes coordination responsibility -- Enables complex multi-agent workflows -- Maintains context isolation - -## Best Practices - -**Choose appropriate agents**: Match agent capabilities to task requirements. Specialized agents produce better results. - -**Clear prompts**: Include context, specific files, focus areas, and success criteria. - -**Parallel spawning**: Use for independent work to maximize throughput. - -**Monitor states**: Check tasks menu, respond to "Needs Input" promptly. - -**Handle failures**: Review errors, adjust approach, re-spawn with corrections. - -**Focused objectives**: One clear goal per spawned task. - -**Leverage inheritance**: Tasks inherit org/project context automatically. - -**Validate results**: Successful completion doesn't guarantee correctness. +By keeping intensive work in subtasks, your main task remains focused and productive across longer sessions. --- -**Ready to start?** See [Tools](/en/mcp-mesh/decopilot/tools) for agent_spawn details, [Context](/en/mcp-mesh/decopilot/context) for isolation mechanics, or [Scopes](/en/mcp-mesh/decopilot/scopes) for scope effects. +**Next steps**: Learn about [Context](/en/mcp-mesh/decopilot/context) to understand how tasks manage your working memory, explore [Tools](/en/mcp-mesh/decopilot/tools) to see what decopilot can do, or check out [Agents](/en/mcp-mesh/agents) for specialized scopes you can use with subtasks. From 03dc539ca461a081bd0d7cd3d1d618c7852e1963 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 12:06:23 -0300 Subject: [PATCH 27/51] docs(decopilot): simplify tools page for non-technical users Dramatically condensed and simplified the tools documentation: - Reduced from 1608 lines to 103 lines (94% reduction) - Introduced clear two-tier model: built-in tools vs scope tools - Added concise reference table for built-in tools with task/subtask availability - Removed extensive code examples and technical implementation details - Simplified explanation of tool discovery and enablement workflow - Made content significantly more scannable and user-friendly Co-Authored-By: Claude Sonnet 4.5 --- .../content/en/mcp-mesh/decopilot/tools.mdx | 1627 +---------------- 1 file changed, 66 insertions(+), 1561 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx index 4042b15ef9..c572dbbe73 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx @@ -1,6 +1,6 @@ --- title: Tools -description: Built-in decopilot tools and how to work with target virtual MCP tools +description: Understanding how decopilot discovers and enables capabilities to stay focused on what matters icon: Wrench --- @@ -10,1598 +10,103 @@ import Callout from "../../../../components/ui/Callout.astro"; This page documents the **planned architecture** for decopilot tools. The specification serves as the implementation guide for the decopilot module. -## What are Decopilot Tools? +## Overview -Decopilot tools are the mechanism through which decopilot interacts with virtual MCPs, spawns agents, asks users questions, and manages capabilities across different scopes. Tools fall into two fundamental categories with distinct purposes and availability patterns. +Decopilot uses two types of tools: **built-in tools** for discovering capabilities and managing work, and **scope tools** from the current [scope](/en/mcp-mesh/decopilot/scopes) for domain-specific actions. Tools are discovered with `tool_search` and activated on-demand with `tool_enable`, keeping execution focused and preventing tool overload. -**Built-in tools** are always available to decopilot regardless of scope. These core capabilities enable decopilot to manage agents, interact with users, and manipulate the current virtual MCP's configuration. +## Tool Reference -**Target virtual MCP tools** are capabilities from the target virtual MCP (current scope) that decopilot must discover and enable before use. These include tools from connected external MCP servers and inline tools defined within the virtual MCP. +### Built-in Tools -Understanding the distinction between these two categories is essential—built-in tools provide foundational capabilities, while target virtual MCP tools provide domain-specific operations that vary by scope. +All built-in tools are available across all scopes. Availability varies between tasks and subtasks. -## Tool Architecture +| Tool | Task | Subtask | Description | +|------|:----:|:-------:|-------------| +| **Discovery** | +| `tool_search` | ✓ | ✓ | Search for tools in current scope | +| `tool_enable` | ✓ | ✓ | Activate a tool for use in current task | +| `agent_search` | ✓ | ✓ | Find agents configured in the organization | +| **Execution** | +| `subtask_run` | ✓ | ✗ | Spawn subtask with fresh context, optionally specifying an agent | +| `user_ask` | ✓ | ✗ | Ask user for input or clarification | +| **Context** | +| `resource_read` | ✓ | ✓ | Read documentation/guidelines from current scope (supports line ranges) | +| `prompt_read` | ✓ | ✓ | Read prompt templates from current scope | -Decopilot's tool architecture follows a two-tier model that separates meta-level operations from domain-specific capabilities. +### Scope Tools -### Category 1: Built-in Tools (Always Available) +Scope tools come from the current scope—domain-specific capabilities like GitHub, Slack, or deployment tools. These are discovered via `tool_search` and enabled via `tool_enable`. -Built-in tools will be implemented directly in the decopilot module and are always available regardless of the current scope. These tools enable: +**Example**: A project with GitHub and Slack connections might expose: +- `CREATE_PR` - Create a pull request +- `CREATE_BRANCH` - Create a git branch +- `SEND_MESSAGE` - Send a Slack message +- `LIST_ISSUES` - List GitHub issues -- **Agent management**: Spawning and searching for agents across the organization -- **User interaction**: Asking questions and gathering input (restricted in child tasks) -- **Virtual MCP manipulation**: Reading, editing, searching, and enabling capabilities within the current scope +Scope tool availability in tasks vs subtasks depends on the tool's configuration. -Built-in tools operate at the meta level—they manage the environment itself rather than performing domain-specific work. For example, `agent_spawn` doesn't write code or create pull requests; it delegates to another agent that has those capabilities. +#### Tool Annotations -```typescript -// Built-in tool example (specification) -const AGENT_SPAWN = { - name: "agent_spawn", - description: "Spawn an agent with context to work on a specific task", - inputSchema: { - type: "object", - properties: { - agent_id: { - type: "string", - description: "ID of the agent to spawn" - }, - prompt: { - type: "string", - description: "Task description and context for the agent" - } - }, - required: ["agent_id", "prompt"] - }, - outputSchema: { - type: "object", - properties: { - task_id: { - type: "string", - description: "ID of the created task" - } - }, - required: ["task_id"] - } -} -``` +All tools (both built-in and scope tools) use [standard MCP annotations](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/f385c94cbd5857ac17b611edc823a37606bdb1cc/schema/2025-03-26/schema.ts#L737) to declare their capabilities and restrictions: -### Category 2: Target Virtual MCP Tools (Discovered/Enabled) +- **`readOnlyHint`** - Tool does not modify its environment (default: false) +- **`destructiveHint`** - Tool may perform destructive updates vs. only additive updates (default: true, only meaningful when `readOnlyHint` is false) +- **`idempotentHint`** - Calling repeatedly with same arguments has no additional effect (default: false, only meaningful when `readOnlyHint` is false) +- **`openWorldHint`** - Tool may interact with external entities; false means closed domain (default: true) -Target virtual MCP tools come from the current scope's virtual MCP. These tools must be: +These annotations allow decopilot to respect tool constraints automatically. For example, a read-only agent will only discover and enable tools marked as `readOnlyHint: true`, ensuring it never performs destructive actions. -1. **Discovered** via `tools_search` to find available capabilities -2. **Enabled** via `tool_enable` before they can be invoked -3. **Used** once enabled within the current task +## Understanding Availability -These tools include: +### Tasks vs Subtasks -- **External MCP tools**: Connected from external servers like GitHub, Slack, or databases -- **Inline tools**: Defined directly within the virtual MCP configuration +**Tasks** are user-initiated and top-level. They have full access to all built-in tools, can spawn subtasks, and can ask user questions. -The discovery and enablement requirement ensures decopilot explicitly chooses which capabilities to use, preventing tool overload and maintaining focused execution. +**Subtasks** are spawned by decopilot for parallel work, specialized execution, or isolated context. They have restricted access: +- **Cannot spawn additional subtasks** - Prevents infinite delegation +- **Cannot ask user questions** - Subtasks run autonomously without blocking -```typescript -// Workflow: discover and enable tools -// 1. Search for available tools -decopilot.invokeTool("tools_search", { search_term: "github" }) -// Returns: ["CREATE_PR", "LIST_ISSUES", "CREATE_BRANCH"] +These restrictions ensure subtasks complete independently and don't create blocking dependencies. -// 2. Enable specific tool -decopilot.invokeTool("tool_enable", { tool_name: "CREATE_PR" }) -// Tool is now available for invocation +## Tool Discovery Flow -// 3. Use the enabled tool -decopilot.invokeTool("CREATE_PR", { - title: "Add authentication feature", - body: "Implements biometric authentication" -}) -``` +Decopilot starts each task with only built-in tools, then discovers and enables capabilities as needed: -## Understanding Scope-Sensitive Tools +1. **Explore** - Use `tool_search` to see what's available in the current scope +2. **Enable** - Use `tool_enable` to activate specific tools for the task +3. **Execute** - Use enabled tools to accomplish work +4. **Delegate** - Spawn subtasks via `subtask_run` for parallel or specialized work -All built-in tools that operate on the current virtual MCP are **scope-sensitive**—they adapt behavior based on whether decopilot is in org, project, or agent scope. +This discover-and-enable pattern ensures decopilot deliberately chooses its toolset rather than being overwhelmed by every available capability. -### Scope-Dependent Behavior +## Common Workflows -The same tool invocation produces different results depending on the current scope: +### Discover-Enable-Execute -**In org scope** (`/:org/settings`): -- `resource_read("org://acme-corp/security-policy")` reads from org virtual MCP -- `tools_search()` lists org-level tools and all connected external MCPs -- `tool_enable()` enables tools within the org virtual MCP context +The most common pattern for using scope tools: -**In project scope** (`/:org/projects/:mobile-app`): -- `resource_read("project://mobile-app/architecture")` reads from project virtual MCP -- `tools_search()` lists project tools, inherited org tools, and project-connected external MCPs -- `tool_enable()` enables tools within the project virtual MCP context +1. Search for capabilities with `tool_search` +2. Enable specific tools with `tool_enable` +3. Use enabled tools to accomplish work -**In agent scope** (`/:org/agents/:security-reviewer`): -- `resource_read("agent://security-reviewer/checklist")` reads from agent virtual MCP -- `tools_search()` lists bounded agent tools and inherited capabilities -- `tool_enable()` enables tools within the agent virtual MCP context +### Delegate to Specialists -The scope determines which virtual MCP the tool operates on. This automatic adaptation ensures tools always work with the correct context without requiring explicit scope parameters. +For work requiring specialized expertise: -### Scope Inheritance +1. Search for agents with `agent_search` +2. Spawn a subtask with `subtask_run` and specific agent +3. Continue main task while subtask runs in parallel -Virtual MCPs inherit capabilities from parent scopes: +### Context-Driven Execution -- **Agent scope** inherits from project (if spawned in project context) and org -- **Project scope** inherits from org -- **Org scope** is the foundation level +For tasks requiring domain knowledge: -When `tools_search` runs in project scope, it returns project-specific tools AND org-level tools. When `resource_read` looks for a resource, it checks the current scope first, then falls back to parent scopes. - -## Tool Categories - -Built-in tools are organized by functional category based on their purpose. - -### Org-Related Tools (Always Available) - -These tools manage agents and user interaction across the organization. - -**`agent_spawn`**: Spawn an agent with context to execute a specific task. Creates a child task with isolated context. Agent runs until completion, then returns results to the main decopilot loop. - -**`agent_search`**: Search or list agents configured in the current organization. Empty search term returns all agents. Used to discover available agents before spawning. - -**`user_ask_question`**: Ask the user questions to gather input or clarification. Disabled in child tasks (agent-spawned) to prevent blocking execution. Only available in top-level tasks (user-initiated). - -### Current Virtual MCP Tools (Always Available, Scope-Sensitive) - -These tools operate on the current scope's virtual MCP, adapting behavior based on org/project/agent context. - -**`resource_read`**: Read a resource by URI from the current scope's virtual MCP. Supports scope inheritance—searches current scope first, then parent scopes. - -**`resource_edit`**: Create, update, or delete a resource in the current scope. Scope determines which virtual MCP is modified. Supports content updates and deletion. - -**`prompt_read`**: Read a prompt by name from the current scope's virtual MCP. Prompts are templates with variables that can be invoked with parameters. - -**`prompt_edit`**: Create, update, or delete a prompt in the current scope. Enables decopilot to define reusable prompt templates as it works. - -**`tools_read`**: Read detailed information about a specific tool by name from the current scope. Returns full tool specification including input/output schemas. - -**`tools_edit`**: Edit an inline tool by name within the current scope. Can modify tool definitions, including changing which scope the tool belongs to. Cannot edit external MCP tools (read-only). - -**`tools_search`**: Search or list tools available in the target virtual MCP. Empty search term returns all tools. Returns tools from current scope, inherited parent scopes, and connected external MCPs. - -**`tool_enable`**: Enable a tool from the target virtual MCP before invoking it. Required before calling any target virtual MCP tool. Once enabled, the tool becomes available for the current task. - -## Built-in Tool Reference - -This section provides detailed specifications for each built-in tool. - -### agent_spawn - -Spawn an agent with context to work on a specific task. Creates a child task with isolated context that runs until the agent responds. - -**Signature**: `agent_spawn(agent_id: string, prompt: string) -> task_id: string` - -**Input Schema**: -```typescript -{ - agent_id: string // ID of the agent to spawn - prompt: string // Task description and context for the agent -} -``` - -**Output Schema**: -```typescript -{ - task_id: string // ID of the created child task -} -``` - -**Behavior**: -- Creates a child task with isolated context -- Agent receives fresh context (no parent conversation history) -- Agent runs until it responds with findings or completion -- Main decopilot loop continues without blocking -- Results integrate back into parent context when task completes - -**Restrictions**: -- Disabled in child tasks by default (prevents infinite spawning) -- Only available in top-level tasks unless explicitly enabled - -**Example**: -```typescript -// Spawn security review agent on specific files -const result = await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer-001", - prompt: "Review src/auth/login.ts and src/auth/session.ts for security vulnerabilities. Focus on SQL injection, XSS, and auth bypasses." -}) -// Returns: { task_id: "task-abc-123" } -``` - -### agent_search - -Search or list agents configured in the current organization. Empty search term returns all agents. - -**Signature**: `agent_search(search_term?: string) -> Agent[]` - -**Input Schema**: -```typescript -{ - search_term?: string // Optional search term (empty = list all) -} -``` - -**Output Schema**: -```typescript -{ - agents: [ - { - agent_id: string - name: string - purpose: string - capabilities: string[] - } - ] -} -``` - -**Behavior**: -- Queries organization agent registry -- Filters by search term if provided (matches name, purpose, capabilities) -- Returns all agents if search term is empty -- Results ordered by relevance (if searching) or alphabetically (if listing) - -**Example**: -```typescript -// Search for security-related agents -const result = await decopilot.invokeTool("agent_search", { - search_term: "security" -}) -// Returns: [{ agent_id: "security-reviewer-001", name: "Security Reviewer", ... }] - -// List all agents -const allAgents = await decopilot.invokeTool("agent_search", {}) -``` - -### user_ask_question - -Ask the user a question to gather input or clarification. Disabled in child tasks to prevent blocking execution. - -**Signature**: `user_ask_question(question: string, options?: { type: string, choices?: string[] }) -> string` - -**Input Schema**: -```typescript -{ - question: string // Question to ask the user - options?: { - type: "text" | "choice" | "confirmation" - choices?: string[] // For choice type - } -} -``` - -**Output Schema**: -```typescript -{ - answer: string // User's response -} -``` - -**Behavior**: -- Presents question to user in UI -- Task status changes to "Needs Input" -- Execution pauses until user responds -- Returns user's answer when provided - -**Restrictions**: -- **Disabled in child tasks** (agent-spawned tasks cannot ask user questions) -- Only available in top-level tasks (user-initiated) -- Prevents agents from blocking on user input - -**Example**: -```typescript -// Ask for confirmation before deployment -const result = await decopilot.invokeTool("user_ask_question", { - question: "Deploy to production? This will affect live users.", - options: { type: "confirmation" } -}) -// Returns: { answer: "yes" } or { answer: "no" } - -// Ask for choice -const result = await decopilot.invokeTool("user_ask_question", { - question: "Which environment should we deploy to?", - options: { - type: "choice", - choices: ["staging", "production", "development"] - } -}) -``` - -### resource_read - -Read a resource by URI from the current scope's virtual MCP. Supports scope inheritance. - -**Signature**: `resource_read(uri: string) -> { content: string, mimeType: string }` - -**Input Schema**: -```typescript -{ - uri: string // Resource URI (e.g., "project://mobile-app/architecture") -} -``` - -**Output Schema**: -```typescript -{ - content: string // Resource content - mimeType: string // MIME type (e.g., "text/markdown") - name: string // Resource name -} -``` - -**Behavior**: -- Resolves URI based on current scope -- Searches current scope's virtual MCP first -- Falls back to parent scopes if not found (inheritance) -- Returns resource content and metadata - -**Scope-sensitive**: -- Org scope: reads from org virtual MCP -- Project scope: reads from project virtual MCP (with org inheritance) -- Agent scope: reads from agent virtual MCP (with project/org inheritance) - -**Example**: -```typescript -// In project scope: read project architecture doc -const result = await decopilot.invokeTool("resource_read", { - uri: "project://mobile-app/architecture" -}) -// Returns: { content: "# Architecture\n\n...", mimeType: "text/markdown", ... } - -// Read org-level resource (inheritance) -const orgResource = await decopilot.invokeTool("resource_read", { - uri: "org://acme-corp/security-policy" -}) -``` - -### resource_edit - -Create, update, or delete a resource in the current scope's virtual MCP. - -**Signature**: `resource_edit(uri: string, content?: string, operation: "create" | "update" | "delete") -> { success: boolean }` - -**Input Schema**: -```typescript -{ - uri: string // Resource URI - content?: string // Resource content (required for create/update) - mimeType?: string // MIME type (default: "text/markdown") - name?: string // Resource name (required for create) - operation: "create" | "update" | "delete" -} -``` - -**Output Schema**: -```typescript -{ - success: boolean -} -``` - -**Behavior**: -- Creates, updates, or deletes resource in current scope's virtual MCP -- Scope determines which virtual MCP is modified -- Create fails if resource already exists -- Update fails if resource doesn't exist -- Delete removes resource from virtual MCP - -**Scope-sensitive**: -- Org scope: modifies org virtual MCP -- Project scope: modifies project virtual MCP -- Agent scope: modifies agent virtual MCP - -**Example**: -```typescript -// Create new resource in project scope -const result = await decopilot.invokeTool("resource_edit", { - uri: "project://mobile-app/deployment-checklist", - name: "Deployment Checklist", - content: "# Deployment\n\n- [ ] Run tests\n- [ ] Update changelog", - mimeType: "text/markdown", - operation: "create" -}) - -// Update existing resource -await decopilot.invokeTool("resource_edit", { - uri: "project://mobile-app/deployment-checklist", - content: "# Deployment\n\n- [ ] Run tests\n- [ ] Update changelog\n- [ ] Notify team", - operation: "update" -}) - -// Delete resource -await decopilot.invokeTool("resource_edit", { - uri: "project://mobile-app/old-doc", - operation: "delete" -}) -``` - -### prompt_read - -Read a prompt by name from the current scope's virtual MCP. - -**Signature**: `prompt_read(name: string) -> { template: string, description: string }` - -**Input Schema**: -```typescript -{ - name: string // Prompt name -} -``` - -**Output Schema**: -```typescript -{ - name: string - description: string - template: string // Template with {{variables}} -} -``` - -**Behavior**: -- Searches current scope's virtual MCP for prompt -- Falls back to parent scopes if not found (inheritance) -- Returns prompt template and metadata - -**Scope-sensitive**: -- Org scope: reads from org virtual MCP -- Project scope: reads from project virtual MCP (with org inheritance) -- Agent scope: reads from agent virtual MCP (with project/org inheritance) - -**Example**: -```typescript -// Read code review prompt -const result = await decopilot.invokeTool("prompt_read", { - name: "security-review" -}) -// Returns: { name: "security-review", template: "Review for:\n- SQL injection\n...", ... } -``` - -### prompt_edit - -Create, update, or delete a prompt in the current scope's virtual MCP. - -**Signature**: `prompt_edit(name: string, template?: string, operation: "create" | "update" | "delete") -> { success: boolean }` - -**Input Schema**: -```typescript -{ - name: string // Prompt name - description?: string // Prompt description (required for create) - template?: string // Template with {{variables}} (required for create/update) - operation: "create" | "update" | "delete" -} -``` - -**Output Schema**: -```typescript -{ - success: boolean -} -``` - -**Behavior**: -- Creates, updates, or deletes prompt in current scope's virtual MCP -- Scope determines which virtual MCP is modified -- Prompts can include variables using `{{variableName}}` syntax - -**Scope-sensitive**: -- Org scope: modifies org virtual MCP -- Project scope: modifies project virtual MCP -- Agent scope: modifies agent virtual MCP - -**Example**: -```typescript -// Create new prompt template -const result = await decopilot.invokeTool("prompt_edit", { - name: "mobile-pr-template", - description: "PR template for mobile features", - template: "## Mobile Feature PR\n\n{{description}}\n\n### Testing\n- [ ] iOS tested\n- [ ] Android tested", - operation: "create" -}) - -// Update prompt template -await decopilot.invokeTool("prompt_edit", { - name: "mobile-pr-template", - template: "## Mobile Feature PR\n\n{{description}}\n\n### Testing\n- [ ] iOS tested\n- [ ] Android tested\n- [ ] Tablet tested", - operation: "update" -}) -``` - -### tools_read - -Read detailed information about a specific tool by name from the current scope. - -**Signature**: `tools_read(tool_name: string) -> { name: string, description: string, inputSchema: object, outputSchema: object }` - -**Input Schema**: -```typescript -{ - tool_name: string // Name of the tool to read -} -``` - -**Output Schema**: -```typescript -{ - name: string - description: string - inputSchema: object // JSON Schema for input - outputSchema: object // JSON Schema for output - source: "inline" | "external" // Whether tool is inline or from external MCP -} -``` - -**Behavior**: -- Returns full tool specification including schemas -- Searches current scope's virtual MCP -- Includes inherited tools from parent scopes -- Useful for understanding tool capabilities before enabling - -**Scope-sensitive**: -- Resolves from current scope's virtual MCP and parent scopes -- Includes tools from connected external MCPs - -**Example**: -```typescript -// Read CREATE_PR tool specification -const result = await decopilot.invokeTool("tools_read", { - tool_name: "CREATE_PR" -}) -// Returns: { name: "CREATE_PR", description: "Create a pull request", inputSchema: {...}, ... } -``` - -### tools_edit - -Edit an inline tool by name within the current scope. Can modify tool definitions including scope assignment. - -**Signature**: `tools_edit(tool_name: string, definition?: object, operation: "create" | "update" | "delete") -> { success: boolean }` - -**Input Schema**: -```typescript -{ - tool_name: string // Tool name - definition?: { - description?: string - inputSchema?: object - outputSchema?: object - handler?: string // Tool implementation (inline code or composite workflow) - } - operation: "create" | "update" | "delete" -} -``` - -**Output Schema**: -```typescript -{ - success: boolean -} -``` - -**Behavior**: -- Creates, updates, or deletes inline tool in current scope's virtual MCP -- **Cannot edit external MCP tools** (read-only) -- Can change which scope a tool belongs to -- Scope determines which virtual MCP is modified - -**Scope-sensitive**: -- Org scope: modifies org virtual MCP -- Project scope: modifies project virtual MCP -- Agent scope: modifies agent virtual MCP - -**Restrictions**: -- Only works with inline tools (tools defined in virtual MCP) -- External MCP tools are read-only and cannot be modified - -**Example**: -```typescript -// Create new inline tool -const result = await decopilot.invokeTool("tools_edit", { - tool_name: "DEPLOY_STAGING", - definition: { - description: "Deploy to staging environment", - inputSchema: { - type: "object", - properties: { - branch: { type: "string" } - } - }, - handler: "composite" // Orchestrates other tools - }, - operation: "create" -}) - -// Update existing inline tool -await decopilot.invokeTool("tools_edit", { - tool_name: "DEPLOY_STAGING", - definition: { - description: "Deploy to staging environment with health checks", - inputSchema: { - type: "object", - properties: { - branch: { type: "string" }, - runHealthChecks: { type: "boolean", default: true } - } - } - }, - operation: "update" -}) -``` - -### tools_search - -Search or list tools available in the target virtual MCP. Empty search term returns all tools. - -**Signature**: `tools_search(search_term?: string) -> Tool[]` - -**Input Schema**: -```typescript -{ - search_term?: string // Optional search term (empty = list all) -} -``` - -**Output Schema**: -```typescript -{ - tools: [ - { - name: string - description: string - source: "inline" | "external" - enabled: boolean // Whether tool is currently enabled for use - } - ] -} -``` - -**Behavior**: -- Lists tools from current scope's virtual MCP -- Includes inherited tools from parent scopes -- Includes tools from connected external MCPs -- Filters by search term if provided -- Returns all tools if search term is empty - -**Scope-sensitive**: -- Org scope: lists org tools and connected external MCPs -- Project scope: lists project tools, inherited org tools, and project-connected external MCPs -- Agent scope: lists bounded agent tools and inherited capabilities - -**Example**: -```typescript -// Search for GitHub-related tools -const result = await decopilot.invokeTool("tools_search", { - search_term: "github" -}) -// Returns: [{ name: "CREATE_PR", description: "...", enabled: false }, ...] - -// List all available tools -const allTools = await decopilot.invokeTool("tools_search", {}) -// Returns all tools from current scope and parents -``` - -### tool_enable - -Enable a tool from the target virtual MCP before invoking it. Required before calling any target virtual MCP tool. - -**Signature**: `tool_enable(tool_name: string) -> { success: boolean }` - -**Input Schema**: -```typescript -{ - tool_name: string // Name of the tool to enable -} -``` - -**Output Schema**: -```typescript -{ - success: boolean - enabled: boolean // Whether tool is now enabled -} -``` - -**Behavior**: -- Enables tool for use in the current task -- Must be called before invoking any target virtual MCP tool -- Tool remains enabled for the duration of the task -- Does not persist across tasks (each task must enable tools explicitly) - -**Scope-sensitive**: -- Enables tool from current scope's virtual MCP -- Includes inherited tools from parent scopes - -**Example**: -```typescript -// Enable CREATE_PR before using it -const result = await decopilot.invokeTool("tool_enable", { - tool_name: "CREATE_PR" -}) -// Returns: { success: true, enabled: true } - -// Now CREATE_PR is available for invocation -await decopilot.invokeTool("CREATE_PR", { - title: "Add authentication feature", - body: "Implements biometric authentication" -}) -``` - -## Working with Target Virtual MCP Tools - -Target virtual MCP tools require a discovery and enablement workflow before use. This section explains the complete process. - -### Discovery Workflow - -Before using any target virtual MCP tool, you must discover what tools are available in the current scope: - -```typescript -// Step 1: Discover available tools -const result = await decopilot.invokeTool("tools_search", {}) -// Returns list of all tools in current scope - -// Step 2: Filter or search for specific capabilities -const githubTools = await decopilot.invokeTool("tools_search", { - search_term: "github" -}) -// Returns only GitHub-related tools - -// Step 3: Read tool details to understand capabilities -const toolDetails = await decopilot.invokeTool("tools_read", { - tool_name: "CREATE_PR" -}) -// Returns full specification with input/output schemas -``` - -### Enablement Workflow - -Once you've discovered a tool, enable it before invoking: - -```typescript -// Step 1: Enable the tool -await decopilot.invokeTool("tool_enable", { - tool_name: "CREATE_PR" -}) - -// Step 2: Use the enabled tool -await decopilot.invokeTool("CREATE_PR", { - title: "Add authentication", - body: "Implements biometric auth for iOS and Android", - base: "main", - head: "feature/biometric-auth" -}) -``` - -### Common Patterns - -Understanding common tool usage patterns improves efficiency and reduces errors. - -#### Pattern 1: Discover-Enable-Use - -The most common pattern for working with target virtual MCP tools: - -```typescript -// 1. Discover what's available -const tools = await decopilot.invokeTool("tools_search", { - search_term: "github" -}) -// => [{ name: "CREATE_PR", enabled: false }, { name: "CREATE_BRANCH", enabled: false }] - -// 2. Enable the specific tool needed -await decopilot.invokeTool("tool_enable", { - tool_name: "CREATE_PR" -}) - -// 3. Use the enabled tool -await decopilot.invokeTool("CREATE_PR", { - title: "Add feature", - body: "Feature description", - base: "main", - head: "feature/new-feature" -}) -``` - -**When to use**: Default pattern for any target virtual MCP tool. Always follow this sequence. - -#### Pattern 2: Explore-Then-Enable - -When you're not sure what capabilities exist, explore first: - -```typescript -// 1. List all available tools -const allTools = await decopilot.invokeTool("tools_search", {}) - -// 2. Read details for promising tools -const prDetails = await decopilot.invokeTool("tools_read", { - tool_name: "CREATE_PR" -}) -console.log("Input schema:", prDetails.inputSchema) - -const issueDetails = await decopilot.invokeTool("tools_read", { - tool_name: "CREATE_ISSUE" -}) -console.log("Input schema:", issueDetails.inputSchema) - -// 3. Enable the right tool for your task -await decopilot.invokeTool("tool_enable", { - tool_name: "CREATE_ISSUE" -}) - -// 4. Use it -await decopilot.invokeTool("CREATE_ISSUE", { - title: "Bug: Login fails on iOS", - body: "Steps to reproduce..." -}) -``` - -**When to use**: When you're exploring a new project or unfamiliar MCP server. Take time to understand available tools before committing. - -#### Pattern 3: Multi-Tool Workflow - -Enable multiple tools for complex workflows: - -```typescript -// Enable all tools you'll need upfront -await decopilot.invokeTool("tool_enable", { tool_name: "CREATE_BRANCH" }) -await decopilot.invokeTool("tool_enable", { tool_name: "COMMIT_CHANGES" }) -await decopilot.invokeTool("tool_enable", { tool_name: "CREATE_PR" }) -await decopilot.invokeTool("tool_enable", { tool_name: "SEND_MESSAGE" }) - -// Then orchestrate the workflow -await decopilot.invokeTool("CREATE_BRANCH", { - name: "feature/notification-system", - base: "main" -}) - -await decopilot.invokeTool("COMMIT_CHANGES", { - message: "Add push notification service", - files: ["src/notifications/push.ts"] -}) - -await decopilot.invokeTool("CREATE_PR", { - title: "Add push notification system", - body: "Implements FCM-based push notifications" -}) - -await decopilot.invokeTool("SEND_MESSAGE", { - channel: "engineering", - text: "PR ready for review: push notification system" -}) -``` - -**When to use**: Complex workflows spanning multiple services. Enable all tools first, then execute the workflow smoothly. - -### Complete Example: GitHub PR Creation - -```typescript -// Full workflow from discovery to invocation -async function createPullRequest() { - // 1. Search for GitHub tools - const githubTools = await decopilot.invokeTool("tools_search", { - search_term: "github" - }) - console.log("Available GitHub tools:", githubTools) - - // 2. Read CREATE_PR specification - const prToolSpec = await decopilot.invokeTool("tools_read", { - tool_name: "CREATE_PR" - }) - console.log("CREATE_PR input schema:", prToolSpec.inputSchema) - - // 3. Enable CREATE_PR - await decopilot.invokeTool("tool_enable", { - tool_name: "CREATE_PR" - }) - - // 4. Create the PR - const result = await decopilot.invokeTool("CREATE_PR", { - title: "Add biometric authentication", - body: "Implements face ID and fingerprint authentication for mobile app", - base: "main", - head: "feature/biometric-auth" - }) - - console.log("PR created:", result.url) -} -``` - -### External vs Inline Tools - -Target virtual MCP tools come from two sources: - -**External MCP tools**: -- Connected from external MCP servers (GitHub, Slack, databases) -- Read-only (cannot be modified via `tools_edit`) -- Must be enabled before use -- Source shows as `"external"` in `tools_search` results - -**Inline tools**: -- Defined directly in the virtual MCP configuration -- Can be modified via `tools_edit` -- Must be enabled before use -- Source shows as `"inline"` in `tools_search` results - -```typescript -// Check tool source before attempting to edit -const toolInfo = await decopilot.invokeTool("tools_read", { - tool_name: "CREATE_PR" -}) - -if (toolInfo.source === "external") { - console.log("Cannot edit external MCP tool") -} else { - // Safe to edit inline tool - await decopilot.invokeTool("tools_edit", { - tool_name: "DEPLOY_STAGING", - definition: { /* updated definition */ }, - operation: "update" - }) -} -``` - -## Tool Workflows by Use Case - -Practical examples showing tool usage patterns for common development tasks. - - -Check the [Quick Start](/en/mcp-mesh/decopilot/quickstart) for complete workflow examples with detailed context. - - -### Use Case 1: Code Review Workflow - -**Goal**: Create a PR and spawn a security review agent. - -**Tools needed**: `tools_search`, `tool_enable`, GitHub MCP tools, `agent_spawn` - -```typescript -// 1. Discover GitHub tools -const githubTools = await decopilot.invokeTool("tools_search", { - search_term: "github pull request" -}) - -// 2. Enable PR creation -await decopilot.invokeTool("tool_enable", { - tool_name: "CREATE_PR" -}) - -// 3. Create the PR -const pr = await decopilot.invokeTool("CREATE_PR", { - title: "Add biometric authentication", - body: "Implements face ID and fingerprint auth", - base: "main", - head: "feature/biometric-auth" -}) - -// 4. Spawn security agent for parallel review -await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer", - prompt: `Review PR #${pr.number} for security vulnerabilities. -Focus on: -- Credential storage -- Biometric data handling -- Authentication bypass risks` -}) - -// Main loop continues while agent reviews in parallel -``` - -**Key pattern**: Coordinate external MCP tools (GitHub) with built-in tools (agent spawning) for parallel workflows. - -### Use Case 2: Resource Management - -**Goal**: Create and organize project resources as you work. - -**Tools needed**: `resource_read`, `resource_edit` - -```typescript -// 1. Read existing architecture doc (if exists) -const existingArch = await decopilot.invokeTool("resource_read", { - uri: "project://mobile-app/architecture" -}).catch(() => null) // May not exist yet - -// 2. Create new architecture decision document -await decopilot.invokeTool("resource_edit", { - uri: "project://mobile-app/adr-001-push-notifications", - name: "ADR 001: Push Notifications", - content: `# ADR 001: Push Notification Strategy - -## Decision -Use Firebase Cloud Messaging for cross-platform push. - -## Rationale -- Native iOS/Android support -- Reliable delivery at scale -- Cost effective - -## Consequences -- Adds Firebase SDK dependency -- Requires Firebase project setup -- Lock-in to Google infrastructure`, - mimeType: "text/markdown", - operation: "create" -}) - -// 3. Update main architecture doc with reference -const updatedContent = existingArch - ? `${existingArch.content}\n\n## ADRs\n- [ADR 001: Push Notifications](project://mobile-app/adr-001-push-notifications)` - : `# Architecture\n\n## ADRs\n- [ADR 001: Push Notifications](project://mobile-app/adr-001-push-notifications)` - -await decopilot.invokeTool("resource_edit", { - uri: "project://mobile-app/architecture", - name: "Mobile App Architecture", - content: updatedContent, - operation: existingArch ? "update" : "create" -}) -``` - -**Key pattern**: Use resources to document decisions and maintain project knowledge. Resources persist across tasks and are inherited by spawned agents. - -### Use Case 3: Multi-Server Coordination - -**Goal**: Coordinate work across GitHub, Figma, and Slack in a single workflow. - -**Tools needed**: `tools_search`, `tool_enable`, tools from multiple external MCPs - -```typescript -// 1. Discover and enable tools from multiple sources -await decopilot.invokeTool("tool_enable", { tool_name: "CREATE_BRANCH" }) // GitHub -await decopilot.invokeTool("tool_enable", { tool_name: "EXPORT_ASSETS" }) // Figma -await decopilot.invokeTool("tool_enable", { tool_name: "SEND_MESSAGE" }) // Slack - -// 2. Create feature branch -await decopilot.invokeTool("CREATE_BRANCH", { - repo: "mobile-app", - name: "feature/new-onboarding", - base: "main" -}) - -// 3. Export Figma assets for the feature -const assets = await decopilot.invokeTool("EXPORT_ASSETS", { - file_id: "mobile-app-designs", - node_ids: ["onboarding-flow", "welcome-screen"], - format: "svg", - scale: 2 -}) - -// 4. Notify team with context -await decopilot.invokeTool("SEND_MESSAGE", { - channel: "engineering", - text: `🚀 Started new onboarding feature -Branch: feature/new-onboarding -Figma assets: ${assets.files.length} files exported -Ready for development` -}) -``` - -**Key pattern**: Decopilot orchestrates distributed MCP servers through a single workflow. Each tool invocation reaches the appropriate external MCP via the MCP protocol (HTTP for remote servers, stdio for local servers). - -### Use Case 4: Dynamic Tool Creation - -**Goal**: Create a project-specific tool for a recurring operation. - -**Tools needed**: `tools_edit`, `tool_enable`, composite workflow capability - -```typescript -// 1. Check existing tools for mobile testing -const testTools = await decopilot.invokeTool("tools_search", { - search_term: "test mobile" -}) - -// 2. Create composite tool that orchestrates existing tools -await decopilot.invokeTool("tools_edit", { - tool_name: "RUN_MOBILE_TESTS_ALL_PLATFORMS", - definition: { - description: "Run complete mobile test suite on iOS and Android", - inputSchema: { - type: "object", - properties: { - suite: { - type: "string", - enum: ["unit", "integration", "e2e", "all"], - description: "Test suite to run" - } - }, - required: ["suite"] - }, - outputSchema: { - type: "object", - properties: { - ios: { type: "object" }, - android: { type: "object" } - } - }, - handler: "composite", // Orchestrates other tools - workflow: [ - { tool: "RUN_TESTS", input: { platform: "ios", suite: "{{input.suite}}" } }, - { tool: "RUN_TESTS", input: { platform: "android", suite: "{{input.suite}}" } } - ] - }, - operation: "create" -}) - -// 3. Enable and use immediately -await decopilot.invokeTool("tool_enable", { - tool_name: "RUN_MOBILE_TESTS_ALL_PLATFORMS" -}) - -const results = await decopilot.invokeTool("RUN_MOBILE_TESTS_ALL_PLATFORMS", { - suite: "integration" -}) - -// 4. Save results as project resource -await decopilot.invokeTool("resource_edit", { - uri: "project://mobile-app/test-results-latest", - name: "Latest Test Results", - content: JSON.stringify(results, null, 2), - mimeType: "application/json", - operation: "create" -}) -``` - -**Key pattern**: Create inline tools to encapsulate project-specific operations. These tools become part of the project's virtual MCP and are available to all future tasks. - -## Scope-Specific Tool Behavior Examples - -This section provides concrete examples of how tools behave differently across scopes. - -### Example 1: Resource Management Across Scopes - -```typescript -// In org scope (/:org/settings) -await decopilot.invokeTool("resource_edit", { - uri: "org://acme-corp/security-policy", - name: "Security Policy", - content: "# Security Policy\n\nAll code must be reviewed for security issues.", - operation: "create" -}) -// Creates resource in org virtual MCP (available to all projects) - -// In project scope (/:org/projects/mobile-app) -await decopilot.invokeTool("resource_edit", { - uri: "project://mobile-app/architecture", - name: "Mobile Architecture", - content: "# Architecture\n\nMobile app uses React Native with...", - operation: "create" -}) -// Creates resource in project virtual MCP (available only to this project) - -// Reading resources with inheritance -const securityPolicy = await decopilot.invokeTool("resource_read", { - uri: "org://acme-corp/security-policy" -}) -// Works from any scope (org, project, or agent) via inheritance -``` - -### Example 2: Tool Discovery by Scope - -```typescript -// In org scope: lists org-wide tools -const orgTools = await decopilot.invokeTool("tools_search", {}) -// Returns: ["ORG_CONNECTION_CREATE", "ORG_RESOURCE_CREATE", ...] - -// In project scope: lists project + org + connected external tools -const projectTools = await decopilot.invokeTool("tools_search", {}) -// Returns: ["CREATE_PR", "DEPLOY_STAGING", "ORG_RESOURCE_CREATE", ...] - -// In agent scope: lists bounded agent tools + inherited tools -const agentTools = await decopilot.invokeTool("tools_search", {}) -// Returns: ["SECURITY_SCAN", "CVE_LOOKUP", "ORG_RESOURCE_CREATE", ...] -``` - -### Example 3: Prompt Templates by Scope - -```typescript -// Create org-level prompt (available to all projects) -await decopilot.invokeTool("prompt_edit", { - name: "code-review-checklist", - description: "Standard code review checklist", - template: "## Code Review\n\n- [ ] Security reviewed\n- [ ] Tests added\n- [ ] Docs updated", - operation: "create" -}) - -// Create project-level prompt (overrides org for this project) -await decopilot.invokeTool("prompt_edit", { - name: "code-review-checklist", - description: "Mobile-specific code review checklist", - template: "## Mobile Code Review\n\n- [ ] iOS tested\n- [ ] Android tested\n- [ ] Security reviewed", - operation: "create" -}) - -// Reading prompts respects scope hierarchy -const prompt = await decopilot.invokeTool("prompt_read", { - name: "code-review-checklist" -}) -// In project scope: returns project-specific version -// In org scope: returns org-level version -``` - -## Tool Availability by Task Type - -Tool availability varies depending on whether the task is user-initiated (top-level) or agent-spawned (child). - -### Top-Level Tasks (User-Initiated) - -Top-level tasks have full tool access: - -- All built-in tools available (including `user_ask_question` and `agent_spawn`) -- Can discover and enable target virtual MCP tools -- Can spawn child tasks via `agent_spawn` -- Can ask user questions via `user_ask_question` - -```typescript -// Top-level task can use all tools -await decopilot.invokeTool("user_ask_question", { - question: "Deploy to production?" -}) -// Works in top-level tasks - -await decopilot.invokeTool("agent_spawn", { - agent_id: "security-reviewer-001", - prompt: "Review authentication code" -}) -// Works in top-level tasks -``` - -### Child Tasks (Agent-Spawned) - -Child tasks have restricted tool access: - -- Most built-in tools available -- **`user_ask_question` DISABLED** (cannot ask user questions) -- **`agent_spawn` DISABLED by default** (prevents infinite spawning) -- Can discover and enable target virtual MCP tools -- Can spawn grandchild tasks if explicitly enabled - -```typescript -// Child task (agent-spawned) -await decopilot.invokeTool("user_ask_question", { - question: "Deploy to production?" -}) -// Throws error: "user_ask_question not available in child tasks" - -await decopilot.invokeTool("agent_spawn", { - agent_id: "another-agent", - prompt: "Do more work" -}) -// Throws error: "agent_spawn disabled in child tasks" (unless explicitly enabled) - -// But can still use other built-in tools -await decopilot.invokeTool("resource_read", { - uri: "project://mobile-app/architecture" -}) -// Works in child tasks - -await decopilot.invokeTool("tools_search", { - search_term: "security" -}) -// Works in child tasks -``` - -### Task State Transitions - -Tasks transition through states based on execution and completion detection: - -**Active**: Task is currently being processed by decopilot or an agent. - -**Needs Input**: Task requires user input. Triggered by `user_ask_question` or when a cheap model determines additional input is required. - -**Successful**: Task completed successfully. Determined by cheap model checking conversation history and tool invocations. - -**Failed**: Task encountered an error that prevents completion. - -```typescript -// Task state example -const task = { - taskId: "task-001", - status: "active", // Initial state when task starts - - // After user_ask_question is called - status: "needs_input", - - // After user responds and work completes - status: "successful", - - // Or if error occurs - status: "failed" -} -``` - -## Tool Specification Format - -All tools (built-in and target virtual MCP) follow a consistent specification format: - -```typescript -interface ToolSpecification { - name: string // Tool name (UPPERCASE_SNAKE_CASE convention) - description: string // What the tool does - inputSchema: object // JSON Schema for input validation - outputSchema: object // JSON Schema for output validation - handler?: Function // Tool implementation (inline tools only) - source: "inline" | "external" // Whether tool is inline or from external MCP -} -``` - -### Input Schema - -Input schemas use JSON Schema Draft 7: - -```typescript -{ - type: "object", - properties: { - param1: { - type: "string", - description: "Parameter description" - }, - param2: { - type: "number", - description: "Another parameter" - } - }, - required: ["param1"] // Required parameters -} -``` - -### Output Schema - -Output schemas define expected return values: - -```typescript -{ - type: "object", - properties: { - result: { - type: "string", - description: "Result description" - }, - success: { - type: "boolean", - description: "Whether operation succeeded" - } - }, - required: ["success"] -} -``` - -### Example Complete Specification - -```typescript -const DEPLOY_STAGING_TOOL = { - name: "DEPLOY_STAGING", - description: "Deploy the application to staging environment", - inputSchema: { - type: "object", - properties: { - branch: { - type: "string", - description: "Git branch to deploy" - }, - runTests: { - type: "boolean", - description: "Whether to run tests before deployment", - default: true - } - }, - required: ["branch"] - }, - outputSchema: { - type: "object", - properties: { - deploymentUrl: { - type: "string", - description: "URL of the deployed application" - }, - success: { - type: "boolean", - description: "Whether deployment succeeded" - } - }, - required: ["success"] - }, - source: "inline", - handler: async (input) => { - // Tool implementation - } -} -``` - -## Troubleshooting Common Issues - -Common problems when working with decopilot tools and how to resolve them. - -### Issue: Tool Not Found - -**Symptoms**: `tools_search` doesn't return the expected tool, or `tool_enable` fails with "Tool not found". - -**Causes**: -1. Tool doesn't exist in current scope -2. Connected MCP server not properly configured -3. Wrong scope context (e.g., looking for project tool in org scope) - -**Solutions**: - -```typescript -// 1. List ALL available tools to verify existence -const allTools = await decopilot.invokeTool("tools_search", {}) -console.log("All available tools:", allTools) - -// 2. Check if you're in the right scope -// Navigate to /:org/projects/:id for project tools -// Navigate to /:org/settings for org tools - -// 3. Verify connection status for external MCP tools -// Check that GitHub, Slack, etc. are properly connected in settings - -// 4. Check tool source and scope -const toolInfo = await decopilot.invokeTool("tools_read", { - tool_name: "CREATE_PR" -}) -console.log("Tool source:", toolInfo.source) -``` - -**Prevention**: Always use `tools_search` to discover tools before attempting to enable them. Don't assume tools exist. - -### Issue: Tool Enable Fails - -**Symptoms**: `tool_enable` returns `{ success: false }` or throws an error. - -**Causes**: -1. Tool doesn't exist (see "Tool Not Found" above) -2. Insufficient permissions in current scope -3. External MCP server connection error - -**Solutions**: - -```typescript -// 1. Verify tool exists first -const tools = await decopilot.invokeTool("tools_search", { - search_term: "CREATE_PR" -}) - -if (tools.tools.length === 0) { - console.error("CREATE_PR tool not available in current scope") -} else { - // 2. Check tool details - const toolInfo = await decopilot.invokeTool("tools_read", { - tool_name: "CREATE_PR" - }) - console.log("Tool info:", toolInfo) - - // 3. Try enabling - const result = await decopilot.invokeTool("tool_enable", { - tool_name: "CREATE_PR" - }) - - if (!result.success) { - console.error("Enable failed. Check permissions and connection status") - } -} -``` - -**Prevention**: Check tool existence with `tools_search` before enabling. Verify external MCP connections are active. - -### Issue: Agent Spawn Blocked - -**Symptoms**: `agent_spawn` fails with "agent_spawn not available" or permission error. - -**Causes**: -1. Attempting to spawn from child task (agent-spawned task) -2. Agent doesn't exist in organization -3. Insufficient permissions to spawn agents - -**Solutions**: - -```typescript -// 1. Check if you're in a top-level task -// agent_spawn is disabled in child tasks by default - -// 2. Search for available agents -const agents = await decopilot.invokeTool("agent_search", { - search_term: "security" -}) -console.log("Available security agents:", agents) - -// 3. Use exact agent_id from search results -if (agents.agents.length > 0) { - await decopilot.invokeTool("agent_spawn", { - agent_id: agents.agents[0].agent_id, - prompt: "Review code for security issues" - }) -} else { - console.error("No security agents available") -} -``` - -**Prevention**: Always use `agent_search` to discover available agents. Only spawn from top-level tasks unless explicitly enabled. - -### Issue: Resource Not Found - -**Symptoms**: `resource_read` fails with "Resource not found" error. - -**Causes**: -1. Resource doesn't exist -2. Wrong URI format -3. Resource exists in different scope - -**Solutions**: - -```typescript -// 1. Check URI format -// Correct formats: -// - "org://org-slug/resource-name" -// - "project://project-slug/resource-name" -// - "agent://agent-id/resource-name" - -// 2. Try reading with proper URI -try { - const resource = await decopilot.invokeTool("resource_read", { - uri: "project://mobile-app/architecture" - }) - console.log("Resource found:", resource) -} catch (error) { - console.error("Resource doesn't exist. Creating...") - - // 3. Create the resource if it doesn't exist - await decopilot.invokeTool("resource_edit", { - uri: "project://mobile-app/architecture", - name: "Architecture", - content: "# Architecture\n\nInitial content...", - operation: "create" - }) -} -``` - -**Prevention**: Use consistent URI formats. Create resources explicitly rather than assuming they exist. - -### Issue: Scope Confusion - -**Symptoms**: Tools behave unexpectedly, or expected tools aren't available. - -**Causes**: -1. Misunderstanding current scope -2. Expecting project tools in org scope (or vice versa) -3. Scope inheritance not working as expected - -**Solutions**: - -```typescript -// 1. Always check what scope you're in based on route -// /:org/settings = Org scope -// /:org/projects/:id = Project scope -// /:org/agents/:id = Agent scope - -// 2. List available tools to understand current context -const tools = await decopilot.invokeTool("tools_search", {}) -console.log(`Available tools in current scope: ${tools.tools.length}`) - -// 3. Remember inheritance: project scope inherits from org, agent inherits from project+org -// Resources, prompts, and tools inherit automatically - -// 4. For scope-specific tools, navigate to the right route first -// Don't try to use project tools while in org scope -``` - -**Prevention**: Pay attention to which route you're on. Understand that scope determines tool availability and behavior. - -## Key Takeaways - -**Two tool categories**: Built-in tools (always available) and target virtual MCP tools (must be discovered and enabled). - -**Scope-sensitive behavior**: Built-in tools that operate on virtual MCPs adapt automatically based on org/project/agent scope. - -**Discovery and enablement**: Target virtual MCP tools require `tools_search` to discover and `tool_enable` to activate before use. - -**Task type restrictions**: Top-level tasks have full tool access; child tasks have `user_ask_question` and `agent_spawn` disabled. - -**Scope inheritance**: Resources, prompts, and tools inherit from parent scopes, enabling reuse and consistency. - -**External vs inline**: External MCP tools are read-only; inline tools can be modified via `tools_edit`. - -Understanding these concepts is essential for working effectively with decopilot—tools are the mechanism through which decopilot interacts with virtual MCPs and accomplishes work. +1. Read relevant resources with `resource_read` +2. Read workflow templates with `prompt_read` +3. Use context to inform tool selection and execution --- -**Ready to dive deeper?** Explore [Scopes](/en/mcp-mesh/decopilot/scopes) to understand scope-based routing, [Architecture](/en/mcp-mesh/decopilot/architecture) for implementation details, or [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to understand the foundation layer. +**Next steps**: Learn about [Tasks and Spawning](/en/mcp-mesh/decopilot/tasks-and-spawning) to understand how decopilot manages work, or explore [Context](/en/mcp-mesh/decopilot/context) to see how resources and prompts provide guidance. + +For technical API details, see [API Reference](/en/mcp-mesh/api-reference). From bcbf8f6b0f81d8cc557b0740d4242746140ca6ca Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 12:14:35 -0300 Subject: [PATCH 28/51] docs(decopilot): remove architecture page Removed the architecture page as part of documentation simplification. Content was overly technical and redundant with other pages. Co-Authored-By: Claude Sonnet 4.5 --- .../en/mcp-mesh/decopilot/architecture.mdx | 1570 ----------------- 1 file changed, 1570 deletions(-) delete mode 100644 apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx deleted file mode 100644 index 13826301ea..0000000000 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/architecture.mdx +++ /dev/null @@ -1,1570 +0,0 @@ ---- -title: Architecture -description: Deep-dive into decopilot's core architectural concepts and implementation design -icon: Building2 ---- - -import Callout from "../../../../components/ui/Callout.astro"; - - - This page documents the **planned architecture** for decopilot. The implementation is in development. - - -## Overview - -Decopilot is an MCP-native AI agent that operates through a scope-sensitive architecture where **everything is a virtual MCP**. Unlike traditional AI coding assistants that work with local filesystems, decopilot is built from the ground up to operate on virtual MCPs—editable, configurable MCP servers that can be dynamically modified at runtime. - -Decopilot operates through an **agentic loop**—gathering context from distributed MCP servers, taking coordinated actions, and verifying results—all while dynamically adapting based on scope. This continuous cycle enables autonomous workflows spanning multiple services, with decopilot orchestrating external MCPs (GitHub, Figma, Slack) while operating on editable virtual MCPs to reshape the environment as it works. - -The architecture is fundamentally defined by three core principles: - -**Scope-based operation**: Decopilot's behavior adapts based on the current route—operating in org scope (`/:org/settings`), project scope (`/:org/projects/:id`), or agent scope (`/:org/agents/:id`). Each scope corresponds to a different virtual MCP with distinct capabilities. - -**Virtual MCP foundation**: Organizations, projects, and agents are all virtual MCPs. This isn't just an implementation detail—it's the architectural constraint that enables decopilot's dynamic capabilities. - -**Task-based execution model**: Decopilot spawns agents on specific tasks with isolated contexts, enabling parallel work and focused execution without context pollution. - -This architecture enables decopilot to dynamically reshape the environment as it works, adding tools, creating resources, and configuring capabilities on the fly—operations that are only possible with editable virtual MCPs. - -## The Agentic Loop in Practice - -Decopilot's agentic loop—**gather → act → verify**—maps directly to the architecture, showing how system components enable autonomous workflows. - -### Gather Context Phase - -Decopilot gathers context through built-in tools that query the current scope's virtual MCP and connected external MCPs: - -- **`tools_search`**: Discovers available tools from virtual MCP and external connections -- **`resource_read`**: Loads project documentation, architecture decisions, guidelines -- **`tools_read`**: Inspects tool specifications to understand capabilities -- **External MCP queries**: Invokes tools from GitHub (branch status), Figma (design specs), databases (data state) - -**Architecture insight**: The scope determines which virtual MCP is queried and which external MCPs are accessible. Project scope provides project-specific context; agent scope provides bounded, focused context. - -### Take Action Phase - -Decopilot takes action by: - -- **Enabling and invoking external MCP tools**: `tool_enable` followed by tool invocation (CREATE_PR, EXPORT_ASSETS, SEND_MESSAGE) -- **Creating resources**: `resource_edit` to document decisions, findings, or generate artifacts -- **Creating inline tools**: `tools_edit` to add project-specific capabilities dynamically -- **Spawning agents**: `agent_spawn` to delegate specialized work with isolated context - -**Architecture insight**: Virtual MCPs are editable, enabling decopilot to create tools and resources on the fly. External MCPs provide read-only tool access—decopilot invokes but doesn't modify them. - -### Verify Results Phase - -Decopilot verifies outcomes through: - -- **Tool response checking**: Confirms successful execution and validates return values -- **Agent spawning for verification**: Spawns review agents (security, performance, quality) to validate work -- **Resource creation**: Documents findings and results for future reference -- **Status reporting**: Determines next actions based on verification results - -**Architecture insight**: Agent spawning provides fresh context for verification without polluting the main loop. Results integrate as summaries (~200-500 tokens), not full conversations. - -### Complete Loop Example - -```typescript -// User request in project scope -User: "Create a PR for the auth feature" - -// GATHER: Check current state -const branch = await GIT_BRANCH_STATUS({ repo: "mobile-app" }) -const commits = await GIT_LOG({ repo: "mobile-app", limit: 5 }) - -// ACT: Create PR -await tool_enable({ tool_name: "CREATE_PR" }) -const pr = await CREATE_PR({ - title: "Add biometric authentication", - body: "Implements face ID and fingerprint auth", - base: "main", - head: "feature/biometric-auth" -}) - -// VERIFY: Spawn security agent for review -await agent_spawn({ - agent_id: "security-reviewer", - prompt: `Review PR #${pr.number} for security issues` -}) - -// Loop continues: integrate findings, update PR if needed -``` - -**Key architectural benefit**: The agentic loop operates seamlessly across distributed MCP servers (via HTTP or stdio). Each phase leverages virtual MCPs for editability and external MCPs for domain-specific capabilities. - -## Architectural Constraint: Virtual MCPs Only - -Decopilot has a fundamental architectural constraint: **it only works with virtual MCPs**. This constraint exists for a critical reason—decopilot needs to operate on and edit the MCP configurations dynamically. - -### Why This Constraint Exists - -Traditional MCP servers (external servers like GitHub, Slack, or database MCPs) are **read-only connections** from decopilot's perspective. These servers expose a fixed set of tools through the MCP protocol, but their configuration cannot be modified by clients. Decopilot can invoke their tools, but it cannot add new tools, create resources, or update prompts on these servers. - -Virtual MCPs, by contrast, are **editable and configurable**. When decopilot operates in a project scope, that project IS a virtual MCP that decopilot can modify. This means decopilot can: - -- Add new tools to the current context -- Create documentation resources as it works -- Update prompts based on workflow patterns -- Configure connections dynamically -- Modify the virtual MCP structure itself - -Without this editability, decopilot would be limited to using predefined tools—essentially a chatbot with access to APIs. The virtual MCP constraint enables decopilot to be an active participant in shaping the environment, not just consuming it. - -### What This Means - -The constraint means that **every context decopilot operates in must be a virtual MCP**: - -- **Organization scope** (`/:org/settings`): The organization itself is a virtual MCP -- **Project scope** (`/:org/projects/:id`): Each project is a virtual MCP -- **Agent scope** (`/:org/agents/:id`): Each agent is a virtual MCP - -External MCP servers (GitHub, Slack, databases) are connected TO these virtual MCPs, not operated on BY decopilot. Decopilot uses the tools from external MCPs, but it operates on the virtual MCP that aggregates them. - -```typescript -// External MCP: read-only from decopilot's perspective -const githubMCP = { - tools: ["CREATE_PR", "LIST_ISSUES"], // Fixed toolset - // Decopilot can invoke these tools but cannot modify this server -} - -// Virtual MCP: editable by decopilot -const projectVirtualMCP = { - connections: [githubMCP], // Compose external MCPs - tools: ["DEPLOY_STAGING"], // Inline tools decopilot can add/remove - resources: [], // Resources decopilot can create - prompts: [], // Prompts decopilot can update - // Decopilot can modify this structure dynamically -} -``` - -### Benefits - -This architectural constraint provides: - -**Dynamic tool management**: Decopilot can add tools to the current scope as needed, creating workflows on the fly rather than requiring pre-configuration. - -**Resource creation**: As decopilot works, it can create documentation resources, guidelines, and context that persist in the virtual MCP for future use. - -**Prompt evolution**: Decopilot can update prompt templates based on successful patterns, continuously improving the virtual MCP. - -**Composable capabilities**: External MCPs remain isolated and secure, while virtual MCPs provide the editable layer that composes them. - -**Clear separation of concerns**: External MCPs focus on providing stable, secure tools. Virtual MCPs focus on dynamic aggregation and configuration. - -The constraint turns a potential limitation into a powerful architectural pattern—by requiring virtual MCPs, decopilot gains the editability foundation that makes its dynamic behavior possible. - -## The Virtual MCP Foundation - -At the core of decopilot's architecture is a simple but powerful concept: **everything is a virtual MCP**. Organizations, projects, and agents are all virtual MCP servers with tools, resources, prompts, and configuration. - -### Organizations as Virtual MCPs - -When you operate in org scope (`/:org/settings` or `/:org/connections`), you're working within the organization's virtual MCP. This virtual MCP contains: - -- **Organization-wide tools**: Capabilities available across all projects and agents -- **Shared resources**: Guidelines, policies, documentation that apply org-wide -- **Global prompts**: Templates and workflows for the entire organization -- **Connection registry**: All external MCP connections managed at the org level - -The organization virtual MCP serves as the foundation layer, comparable to `~/.claude/` in Claude Code—the global context that underlies all work. - -```typescript -// Organization virtual MCP structure -{ - "organizationId": "acme-corp", - "virtualMCPId": "org-acme-corp", - "tools": [ - "ORG_CONNECTION_CREATE", - "ORG_RESOURCE_CREATE", - "ORG_PROMPT_UPDATE" - ], - "resources": [ - { - "uri": "org://acme-corp/security-policy", - "name": "Security Policy", - "mimeType": "text/markdown" - }, - { - "uri": "org://acme-corp/coding-standards", - "name": "Coding Standards", - "mimeType": "text/markdown" - } - ], - "connections": ["github-conn-123", "slack-conn-456"] -} -``` - -### Projects as Virtual MCPs - -Projects ARE virtual MCPs, not containers for other resources. Each project (`/:org/projects/:id`) is a self-contained virtual MCP server with its own capabilities: - -- **Project-specific tools**: Inline tools or composed from connected MCPs -- **Project resources**: Documentation, architecture diagrams, guidelines -- **Project prompts**: Custom templates for the project's workflows -- **Project connections**: External MCPs wired to this project's scope - -Projects are the primary organizational unit for work, comparable to `.claude/` in Claude Code—the project-local context that isolates work. - -```typescript -// Project virtual MCP structure -{ - "projectId": "mobile-app-rewrite", - "virtualMCPId": "project-mobile-app-rewrite", - "organizationId": "acme-corp", - "connections": [ - { - "connectionId": "github-conn-123", - "tools": ["CREATE_PR", "LIST_ISSUES"] - }, - { - "connectionId": "figma-conn-456", - "tools": ["GET_DESIGN", "EXPORT_ASSETS"] - } - ], - "tools": [ - { - "name": "DEPLOY_STAGING", - "description": "Deploy mobile app to staging environment", - "inputSchema": {/* ... */} - } - ], - "resources": [ - { - "uri": "project://mobile-app-rewrite/architecture", - "name": "Mobile Architecture", - "mimeType": "text/markdown" - } - ], - "prompts": [ - { - "name": "mobile-pr-template", - "description": "PR template for mobile features", - "template": "## Mobile Feature PR\n\n{{description}}" - } - ] -} -``` - -### Agents as Virtual MCPs - -Agents ARE virtual MCPs optimized for single-purpose tasks. Each agent (`/:org/agents/:id`) is a focused virtual MCP with: - -- **Bounded tools**: Limited toolset specific to the agent's purpose -- **Agent-specific resources**: Documentation and context for the agent's task -- **Task prompts**: Specialized templates for the agent's workflows -- **Single-purpose focus**: Narrow scope ensures predictable, repeatable behavior - -Agents are the most focused scope level, providing specialized capabilities for well-defined tasks. - -```typescript -// Agent virtual MCP structure -{ - "agentId": "security-reviewer-001", - "virtualMCPId": "agent-security-reviewer-001", - "organizationId": "acme-corp", - "purpose": "Review code for security vulnerabilities", - "tools": [ - { - "name": "SECURITY_SCAN", - "description": "Scan code for security issues" - }, - { - "name": "CVE_LOOKUP", - "description": "Look up known vulnerabilities" - } - ], - "resources": [ - { - "uri": "agent://security-reviewer-001/checklist", - "name": "Security Review Checklist", - "mimeType": "text/markdown" - } - ], - "prompts": [ - { - "name": "security-analysis", - "description": "Analyze code for security issues", - "template": "Review this code for:\n- SQL injection\n- XSS\n- Auth bypasses\n\nCode:\n{{code}}" - } - ] -} -``` - -### Virtual MCP Hierarchy - -Virtual MCPs form a hierarchy where capabilities flow from org to project to agent: - -- **Org virtual MCP**: Foundation layer, provides org-wide capabilities -- **Project virtual MCP**: Inherits org capabilities, adds project-specific tools -- **Agent virtual MCP**: Most focused, bounded toolset for specific task - -This hierarchy ensures consistency while enabling specialization at each level. - -## Scope-Based Architecture - -Decopilot's behavior is determined by **scope**—the current virtual MCP context in which it operates. Scope is automatically determined by the route, and as you navigate through the application, decopilot seamlessly adapts to the new context. - -### Route-Based Scope Determination - -The route determines which virtual MCP decopilot operates on: - -```typescript -// Route-to-scope mapping -const SCOPE_ROUTES = { - // Organization scope - "/:org/settings": { - scopeType: "org", - virtualMCPId: "org-{orgId}" - }, - "/:org/connections": { - scopeType: "org", - virtualMCPId: "org-{orgId}" - }, - - // Project scope - "/:org/projects/:projectId": { - scopeType: "project", - virtualMCPId: "project-{projectId}" - }, - "/:org/projects/:projectId/settings": { - scopeType: "project", - virtualMCPId: "project-{projectId}" - }, - - // Agent scope - "/:org/agents/:agentId": { - scopeType: "agent", - virtualMCPId: "agent-{agentId}" - }, - "/:org/agents/:agentId/config": { - scopeType: "agent", - virtualMCPId: "agent-{agentId}" - } -} - -// Route parsing determines scope -function getScopeFromRoute(route: string) { - const match = matchRoute(route, SCOPE_ROUTES) - if (!match) throw new Error("Invalid route") - - return { - scopeType: match.scopeType, - virtualMCPId: match.virtualMCPId, - params: match.params - } -} -``` - -### Scope Characteristics - -Each scope type has distinct characteristics: - -**Org Scope**: -- **Breadth**: Organization-wide capabilities -- **Tools**: Connection management, org resource creation, global configuration -- **Resources**: Security policies, coding standards, org guidelines -- **Behavior**: Operates like an org-admin, managing shared infrastructure - -**Project Scope**: -- **Breadth**: Project-specific capabilities -- **Tools**: Project tools + composed from connected MCPs (GitHub, Figma, etc.) -- **Resources**: Project documentation, architecture diagrams, guidelines -- **Behavior**: Focused on project work, isolated from other projects - -**Agent Scope**: -- **Breadth**: Task-specific capabilities -- **Tools**: Bounded toolset for the agent's single purpose -- **Resources**: Agent-specific checklists and context -- **Behavior**: Highly focused, predictable execution for well-defined tasks - -### Scope Diagram - -```mermaid -graph TD - A[Route: /:org/settings] --> B[Org Scope] - C[Route: /:org/projects/:id] --> D[Project Scope] - E[Route: /:org/agents/:id] --> F[Agent Scope] - - B --> G[Org Virtual MCP] - D --> H[Project Virtual MCP] - F --> I[Agent Virtual MCP] - - G --> J[Org-wide Tools
Shared Resources
Global Prompts] - H --> K[Project Tools
Project Resources
Connected MCPs] - I --> L[Bounded Tools
Agent Resources
Task Prompts] - - style G fill:#e1f5ff - style H fill:#fff4e1 - style I fill:#ffe1e1 -``` - -## How Decopilot Operates - -Decopilot's operation changes based on the current scope. Each scope provides a different virtual MCP for decopilot to operate on, and the available tools, resources, and behavior adapt accordingly. - -### Operating in Org Scope - -In org scope (`/:org/settings`, `/:org/connections`), decopilot has access to organization-wide capabilities: - -```typescript -// Org scope operations -const orgScope = { - virtualMCPId: "org-acme-corp", - - availableTools: [ - "ORG_CONNECTION_CREATE", // Add external MCP connections - "ORG_RESOURCE_CREATE", // Create org-wide resources - "ORG_PROMPT_UPDATE", // Update global prompts - "ORG_PROJECT_CREATE" // Create new projects - ], - - availableResources: [ - "org://acme-corp/security-policy", - "org://acme-corp/coding-standards", - "org://acme-corp/deployment-guide" - ] -} - -// Example: Creating an org-wide resource -decopilot.invokeTool("ORG_RESOURCE_CREATE", { - uri: "org://acme-corp/api-guidelines", - name: "API Design Guidelines", - content: "# API Guidelines\n\n- RESTful design\n- Versioning strategy\n..." -}) -``` - -### Operating in Project Scope - -In project scope (`/:org/projects/:projectId`), decopilot operates on the project's virtual MCP: - -```typescript -// Project scope operations -const projectScope = { - virtualMCPId: "project-mobile-app-rewrite", - - availableTools: [ - // From connected GitHub MCP - "CREATE_PR", - "LIST_ISSUES", - "CREATE_BRANCH", - - // From connected Figma MCP - "GET_DESIGN", - "EXPORT_ASSETS", - - // Inline project tools - "DEPLOY_STAGING", - "RUN_MOBILE_TESTS" - ], - - availableResources: [ - "project://mobile-app-rewrite/architecture", - "project://mobile-app-rewrite/testing-guide", - // Also inherits org resources - "org://acme-corp/security-policy" - ] -} - -// Example: Creating a PR using project's GitHub connection -decopilot.invokeTool("CREATE_PR", { - title: "Add biometric authentication", - body: "Implements face ID and fingerprint authentication for iOS and Android", - base: "main", - head: "feature/biometric-auth" -}) -``` - -### Operating in Agent Scope - -In agent scope (`/:org/agents/:agentId`), decopilot operates on the agent's bounded virtual MCP: - -```typescript -// Agent scope operations -const agentScope = { - virtualMCPId: "agent-security-reviewer-001", - - availableTools: [ - "SECURITY_SCAN", // Bounded to agent's purpose - "CVE_LOOKUP", - "GENERATE_SECURITY_REPORT" - ], - - availableResources: [ - "agent://security-reviewer-001/checklist", - "agent://security-reviewer-001/patterns", - // Also inherits org and project resources if spawned in project context - "org://acme-corp/security-policy" - ] -} - -// Example: Running security scan with agent's tools -decopilot.invokeTool("SECURITY_SCAN", { - code: "SELECT * FROM users WHERE id = " + userId, - language: "sql" -}) -``` - -### Scope Inheritance - -Scopes inherit capabilities from their parent levels: - -- **Agent scope** inherits from project scope (if spawned in project) and org scope -- **Project scope** inherits from org scope -- **Org scope** is the foundation level - -This inheritance ensures consistency while enabling specialization. - -## External MCP Servers vs Virtual MCPs - -Understanding the distinction between external MCP servers and virtual MCPs is crucial to decopilot's architecture. - -### External MCP Servers - -External MCP servers are traditional MCP servers that expose tools through the MCP protocol: - -**Characteristics**: -- Fixed toolset defined by server implementation -- Cannot be modified by clients -- Provide stable, secure access to external systems -- Examples: GitHub MCP, Slack MCP, database MCPs - -**From decopilot's perspective**: -- **Read-only**: Can invoke tools but cannot modify the server -- **Consumed, not operated on**: Used for their capabilities, not edited -- **Connected TO virtual MCPs**: Aggregated into virtual MCPs for use - -```typescript -// External MCP server (GitHub) -const githubMCP = { - serverUrl: "https://github-mcp.example.com", - tools: [ - "CREATE_PR", - "LIST_ISSUES", - "CREATE_BRANCH", - "MERGE_PR" - ], - // This toolset is fixed and cannot be modified by decopilot -} -``` - -### Virtual MCPs - -Virtual MCPs are editable, configurable MCP servers managed by decocms: - -**Characteristics**: -- Dynamic toolset that can be modified at runtime -- Can aggregate tools from multiple external MCPs -- Can define inline tools, resources, and prompts -- Fully MCP-compliant endpoints - -**From decopilot's perspective**: -- **Editable**: Can add tools, create resources, update prompts -- **Operated on**: Decopilot modifies the virtual MCP as it works -- **Compose external MCPs**: Aggregate capabilities from external servers - -```typescript -// Virtual MCP (project) -const projectVirtualMCP = { - virtualMCPId: "project-mobile-app-rewrite", - - // Composed external MCPs - connections: [ - { - connectionId: "github-conn-123", - tools: ["CREATE_PR", "LIST_ISSUES"] // Selected from external MCP - }, - { - connectionId: "figma-conn-456", - tools: ["GET_DESIGN"] // Selected from external MCP - } - ], - - // Inline tools (editable by decopilot) - tools: [ - { - name: "DEPLOY_STAGING", - description: "Deploy to staging environment", - handler: async (input) => {/* ... */} - } - ], - - // Resources (created by decopilot) - resources: [ - { - uri: "project://mobile-app-rewrite/architecture", - name: "Architecture Documentation", - content: "# Architecture\n\n..." - } - ] -} -``` - -### Interaction Pattern - -External MCPs and virtual MCPs interact through composition: - -```typescript -// External MCP connection to virtual MCP -const externalToVirtual = { - // 1. Connect external MCP to decocms - externalMCP: { - id: "github-conn-123", - serverUrl: "https://github-mcp.example.com", - tools: ["CREATE_PR", "LIST_ISSUES", "CREATE_BRANCH", "MERGE_PR"] - }, - - // 2. Compose into virtual MCP (select tools) - virtualMCP: { - id: "project-mobile-app-rewrite", - connections: [ - { - connectionId: "github-conn-123", - tools: ["CREATE_PR", "LIST_ISSUES"] // Subset of external MCP tools - } - ] - }, - - // 3. Decopilot operates on virtual MCP - // - Can invoke CREATE_PR (from external MCP) - // - Can add new inline tools to virtual MCP - // - Cannot modify github-conn-123 (external MCP) -} -``` - -### Why This Separation Matters - -**Security**: External MCPs remain isolated and secure. Decopilot cannot modify their configuration or access unauthorized tools. - -**Flexibility**: Virtual MCPs can be edited dynamically, enabling decopilot to reshape the environment without touching external infrastructure. - -**Composition**: Multiple external MCPs can be aggregated into a single virtual MCP, providing unified access. - -**Clear boundaries**: External MCPs are stable, production systems. Virtual MCPs are dynamic, configurable contexts. - -### Diagram: External vs Virtual MCPs - -```mermaid -graph LR - A[External MCP
GitHub Server] -->|Connected to| B[Virtual MCP
Project] - C[External MCP
Figma Server] -->|Connected to| B - D[External MCP
Database] -->|Connected to| B - - B -->|Editable by| E[Decopilot] - - A -.->|Read-only| E - C -.->|Read-only| E - D -.->|Read-only| E - - E -->|Can modify| B - E -->|Can invoke tools from| A - E -->|Can invoke tools from| C - E -->|Can invoke tools from| D - - style A fill:#e1e1e1 - style C fill:#e1e1e1 - style D fill:#e1e1e1 - style B fill:#e1f5ff - style E fill:#ffe1e1 -``` - -## Task-Based Agent Spawning - -Decopilot uses a task-based execution model where agents are spawned on specific tasks with isolated contexts. This enables parallel work, focused execution, and clear separation of concerns. - -### Task System Overview - -The task system (also called the thread system—terminology is migrating from "tasks" to "threads") manages asynchronous agent execution: - -**Task types**: -- **Top-level tasks**: Initiated by users, represent primary work threads -- **Child tasks**: Spawned by agents or decopilot, represent sub-tasks - -**Task states**: -- **Active**: Task is currently being processed -- **Needs Input**: Task requires user input to continue -- **Successful**: Task completed successfully -- **Failed**: Task encountered an error - -### Spawning Agents on Tasks - -When decopilot spawns an agent, it creates a new task with isolated context: - -```typescript -// Task-based agent spawning -const spawnAgentTask = { - // Spawn agent on specific task - taskId: "task-001", - taskType: "child", // Spawned by parent (user or decopilot) - - agentId: "security-reviewer-001", - instruction: "Review authentication implementation for security vulnerabilities", - - context: { - // Isolated context for this task - projectId: "mobile-app-rewrite", - files: ["src/auth/login.ts", "src/auth/session.ts"], - scope: "project" // Agent runs in project scope - }, - - // Task runs until agent responds - status: "active" -} - -// Agent executes in isolated context -// Returns result when complete -const result = await agent.execute(spawnAgentTask) - -// Main decopilot loop continues -decopilot.continue() -``` - -### Task Isolation - -Each task has isolated context: - -```typescript -// Task context isolation -const taskContext = { - taskId: "task-001", - - // Isolated conversation history - messages: [ - { role: "user", content: "Review this authentication code" }, - { role: "agent", content: "Analyzing authentication implementation..." } - ], - - // Isolated tool invocations - toolInvocations: [ - { tool: "SECURITY_SCAN", input: {/* ... */}, output: {/* ... */} } - ], - - // Task-specific state - state: "active", - - // Parent task reference (if child task) - parentTaskId: "task-root" -} -``` - -### Tool Availability Per Task Type - -Different task types have different tool availability: - -**Top-level tasks** (user-initiated): -- Full tool access -- Can use `user_ask_question` to prompt user for input -- Can spawn child tasks - -**Child tasks** (agent-spawned): -- Bounded tool access -- **Cannot use `user_ask_question`** (no user interaction) -- Can spawn grandchild tasks (nested execution) - -```typescript -// Tool availability per task type -const taskTypeTools = { - topLevel: { - availableTools: [ - "CREATE_PR", - "SECURITY_SCAN", - "user_ask_question", // User interaction allowed - "spawn_agent" - ] - }, - - child: { - availableTools: [ - "CREATE_PR", - "SECURITY_SCAN", - // "user_ask_question" DISABLED - no user interaction - "spawn_agent" // Can spawn grandchild tasks - ] - } -} -``` - -### Completion Detection - -A cheap AI model detects task completion: - -```typescript -// Completion detection with cheap model -const detectCompletion = async (task: Task) => { - const prompt = ` -Has this task completed its objective? - -Task: ${task.instruction} - -Conversation: -${task.messages.map(m => `${m.role}: ${m.content}`).join("\n")} - -Tool invocations: -${task.toolInvocations.map(t => `${t.tool}: ${t.output}`).join("\n")} - -Answer: YES or NO -` - - const response = await cheapModel.complete(prompt) - - if (response.includes("YES")) { - task.status = "successful" - } -} -``` - -### UI Integration - -Tasks map to the UI as threads: - -- **Tasks menu**: Lists all tasks (threads), with status indicators -- **Task detail view**: Shows conversation history for a specific task (thread) -- **Active task indicator**: Shows which task is currently being processed - -```typescript -// UI representation of tasks -const tasksUI = { - taskList: [ - { - taskId: "task-001", - title: "Review authentication security", - status: "successful", - type: "child", - agentId: "security-reviewer-001" - }, - { - taskId: "task-002", - title: "Implement biometric auth", - status: "active", - type: "topLevel", - agentId: null // User task, no agent - }, - { - taskId: "task-003", - title: "Deploy to staging", - status: "needs_input", - type: "topLevel", - agentId: null - } - ], - - // Task detail = chat interface - taskDetail: { - taskId: "task-001", - messages: [/* conversation history */], - toolInvocations: [/* tools executed */] - } -} -``` - -### Async Execution Model - -Task-based spawning enables asynchronous execution: - -1. **Decopilot spawns agent on task**: Creates child task with isolated context -2. **Agent executes until complete**: Runs in background, no blocking -3. **Main decopilot loop continues**: Can work on other tasks in parallel -4. **Task completion**: Agent returns result, main loop integrates findings - -This model enables parallel work and ensures the main decopilot context remains clean. - -## Agent Selection - -When spawning agents, decopilot can select from any agent configured in your organization. Agents are single-purpose virtual MCPs optimized for specific tasks. - -### Agent Registry - -Organizations maintain a registry of available agents: - -```typescript -// Organization agent registry -const agentRegistry = { - organizationId: "acme-corp", - - agents: [ - { - agentId: "security-reviewer-001", - name: "Security Reviewer", - purpose: "Review code for security vulnerabilities", - virtualMCPId: "agent-security-reviewer-001", - tools: ["SECURITY_SCAN", "CVE_LOOKUP"], - capabilities: ["security-review", "vulnerability-analysis"] - }, - { - agentId: "performance-analyzer-002", - name: "Performance Analyzer", - purpose: "Analyze code for performance issues", - virtualMCPId: "agent-performance-analyzer-002", - tools: ["PROFILE_CODE", "DETECT_N_PLUS_ONE"], - capabilities: ["performance-analysis", "profiling"] - }, - { - agentId: "documentation-writer-003", - name: "Documentation Writer", - purpose: "Generate and update documentation", - virtualMCPId: "agent-documentation-writer-003", - tools: ["GENERATE_DOCS", "UPDATE_README"], - capabilities: ["documentation", "technical-writing"] - } - ] -} -``` - -### Agent Selection Criteria - -Decopilot selects agents based on task requirements: - -```typescript -// Agent selection based on task -const selectAgent = (task: { - instruction: string - requiredCapabilities: string[] - context: object -}) => { - // Filter agents by required capabilities - const eligibleAgents = agentRegistry.agents.filter(agent => - task.requiredCapabilities.every(cap => - agent.capabilities.includes(cap) - ) - ) - - // Score agents by relevance - const scoredAgents = eligibleAgents.map(agent => ({ - agent, - score: calculateRelevance(agent, task) - })) - - // Select best match - const selectedAgent = scoredAgents.sort((a, b) => b.score - a.score)[0] - - return selectedAgent.agent -} - -// Example: Select security reviewer for auth task -const agent = selectAgent({ - instruction: "Review authentication implementation", - requiredCapabilities: ["security-review"], - context: { files: ["src/auth/login.ts"] } -}) -// Returns: security-reviewer-001 -``` - -### Single-Purpose Virtual MCPs - -Agents are virtual MCPs with bounded, focused capabilities: - -**Characteristics**: -- **Single purpose**: Each agent optimized for one type of task -- **Bounded tools**: Limited toolset prevents scope creep -- **Predictable behavior**: Narrow focus ensures consistent results -- **Reusable**: Agents can be spawned on multiple tasks - -```typescript -// Agent as single-purpose virtual MCP -const securityReviewerAgent = { - agentId: "security-reviewer-001", - virtualMCPId: "agent-security-reviewer-001", - - // Bounded toolset - tools: [ - "SECURITY_SCAN", - "CVE_LOOKUP", - "GENERATE_SECURITY_REPORT" - ], - - // Focused resources - resources: [ - { - uri: "agent://security-reviewer-001/owasp-top-10", - name: "OWASP Top 10 Checklist" - }, - { - uri: "agent://security-reviewer-001/patterns", - name: "Security Anti-patterns" - } - ], - - // Specialized prompts - prompts: [ - { - name: "security-analysis", - template: "Analyze for: SQL injection, XSS, auth bypasses\n\nCode:\n{{code}}" - } - ] -} -``` - -### Agent Spawning Flow - -```mermaid -graph TD - A[Decopilot receives task] --> B{Task requires
specialized agent?} - B -->|Yes| C[Query agent registry] - B -->|No| D[Handle with decopilot] - - C --> E[Filter by capabilities] - E --> F[Score by relevance] - F --> G[Select best agent] - - G --> H[Create child task] - H --> I[Spawn agent on task] - I --> J[Agent executes] - - J --> K{Task complete?} - K -->|No| J - K -->|Yes| L[Return result] - - L --> M[Integrate findings] - M --> N[Continue main loop] - - D --> N - - style G fill:#e1f5ff - style J fill:#ffe1e1 -``` - -## Dynamic Virtual MCP Features - -Virtual MCPs are dynamically configurable, enabling decopilot to reshape the environment as it works. This is the core capability that differentiates decopilot from traditional AI assistants. - -### Inline Prompts - -Decopilot can create and update prompts within the current virtual MCP: - -```typescript -// Creating an inline prompt -decopilot.invokeTool("VIRTUAL_MCP_ADD_PROMPT", { - name: "mobile-pr-checklist", - description: "Checklist for mobile feature PRs", - template: ` -## Mobile Feature PR Checklist - -### Testing -- [ ] iOS device tested -- [ ] Android device tested -- [ ] Tablet layouts verified -- [ ] Dark mode tested - -### Performance -- [ ] Bundle size impact measured -- [ ] Load time profiled -- [ ] Memory usage checked - -### Accessibility -- [ ] Screen reader tested -- [ ] Keyboard navigation verified -- [ ] Color contrast validated - -Description: -{{description}} - `.trim() -}) - -// Using the prompt later -decopilot.invokePrompt("mobile-pr-checklist", { - description: "Add biometric authentication" -}) -``` - -### Inline Resources - -Decopilot can create resources that persist in the virtual MCP: - -```typescript -// Creating a resource as decopilot works -decopilot.invokeTool("VIRTUAL_MCP_ADD_RESOURCE", { - uri: "project://mobile-app-rewrite/auth-architecture", - name: "Authentication Architecture", - mimeType: "text/markdown", - content: ` -# Authentication Architecture - -## Overview -The mobile app uses biometric authentication with fallback to PIN/password. - -## Components -- BiometricAuthManager: Handles face ID / fingerprint -- SessionManager: Manages auth sessions -- TokenStore: Secure storage for tokens - -## Flow -1. User attempts login -2. BiometricAuthManager checks availability -3. If available, prompt for biometric -4. If successful, generate session token -5. SessionManager stores token - `.trim() -}) - -// Resource is now available in project scope -decopilot.readResource("project://mobile-app-rewrite/auth-architecture") -``` - -### Inline Tools - -Decopilot can define new tools within the virtual MCP: - -```typescript -// Defining an inline tool -decopilot.invokeTool("VIRTUAL_MCP_ADD_TOOL", { - name: "MOBILE_TEST_ALL_PLATFORMS", - description: "Run tests on iOS and Android simulators", - inputSchema: { - type: "object", - properties: { - testSuite: { - type: "string", - enum: ["unit", "integration", "e2e"] - } - } - }, - implementation: { - type: "composite", // Orchestrates other tools - steps: [ - { - tool: "RUN_TESTS", - input: { - platform: "ios", - suite: "{{testSuite}}" - } - }, - { - tool: "RUN_TESTS", - input: { - platform: "android", - suite: "{{testSuite}}" - } - } - ] - } -}) - -// Tool is now available in project scope -decopilot.invokeTool("MOBILE_TEST_ALL_PLATFORMS", { - testSuite: "integration" -}) -``` - -### Extensibility Pattern - -The dynamic features follow a consistent pattern: - -1. **Identify need**: Decopilot recognizes a recurring pattern or missing capability -2. **Create inline feature**: Add prompt, resource, or tool to virtual MCP -3. **Persist in scope**: Feature becomes part of the virtual MCP configuration -4. **Reuse**: Feature available for future operations in this scope - -```typescript -// Extensibility pattern example -const workflowPattern = { - // 1. Identify need - observation: "Creating mobile PRs requires same checklist every time", - - // 2. Create inline feature - action: { - tool: "VIRTUAL_MCP_ADD_PROMPT", - input: { - name: "mobile-pr-checklist", - template: "{{checklist}}" - } - }, - - // 3. Persist in scope - result: "Prompt added to project virtual MCP", - - // 4. Reuse - nextTime: "Use mobile-pr-checklist prompt for all mobile PRs" -} -``` - -### Editing Current Virtual MCP - -Decopilot always operates on the **current scope's virtual MCP**: - -```typescript -// Current scope determines which virtual MCP is edited -const editCurrentVirtualMCP = (scope: Scope) => { - // In project scope: edit project virtual MCP - if (scope.type === "project") { - editVirtualMCP(scope.virtualMCPId) // project-mobile-app-rewrite - } - - // In agent scope: edit agent virtual MCP - if (scope.type === "agent") { - editVirtualMCP(scope.virtualMCPId) // agent-security-reviewer-001 - } - - // In org scope: edit org virtual MCP - if (scope.type === "org") { - editVirtualMCP(scope.virtualMCPId) // org-acme-corp - } -} - -// Example: Add resource to current scope -// If in project scope: adds to project virtual MCP -// If in agent scope: adds to agent virtual MCP -decopilot.invokeTool("VIRTUAL_MCP_ADD_RESOURCE", { - uri: "{{scope}}://{{scopeId}}/new-resource", - name: "New Resource", - content: "..." -}) -``` - -## Tool Scope Sensitivity - -All decopilot tools are **scope-sensitive**—they operate on the current scope's virtual MCP. The same tool behaves differently depending on whether you're in org, project, or agent scope. - -### Scope-Sensitive Tool Behavior - -```typescript -// Tool behavior adapts to scope -const READ_RESOURCE_TOOL = { - name: "READ_RESOURCE", - description: "Read a resource from the current scope", - - handler: async (input: { uri: string }, ctx: MeshContext) => { - // Determine current scope - const scope = ctx.getCurrentScope() - - // Resolve resource URI based on scope - if (scope.type === "org") { - // Read from org virtual MCP - return readFromVirtualMCP("org-" + scope.orgId, input.uri) - } - - if (scope.type === "project") { - // Read from project virtual MCP (with org inheritance) - return readFromVirtualMCP("project-" + scope.projectId, input.uri) - } - - if (scope.type === "agent") { - // Read from agent virtual MCP (with project/org inheritance) - return readFromVirtualMCP("agent-" + scope.agentId, input.uri) - } - } -} -``` - -### Scope Resolution Examples - -```typescript -// Same tool, different scope = different behavior - -// In org scope (/:org/settings) -decopilot.readResource("org://acme-corp/security-policy") -// Reads from: org virtual MCP - -// In project scope (/:org/projects/mobile-app) -decopilot.readResource("project://mobile-app/architecture") -// Reads from: project virtual MCP - -// In agent scope (/:org/agents/security-reviewer) -decopilot.readResource("agent://security-reviewer/checklist") -// Reads from: agent virtual MCP -``` - -### Tool Scope Filtering - -Tools are filtered based on scope: - -```typescript -// Tool availability per scope -const toolFilter = (scope: Scope) => { - const allTools = getAllTools() - - return allTools.filter(tool => { - // Org scope: org-level tools only - if (scope.type === "org") { - return tool.scopeLevel === "org" - } - - // Project scope: project + org tools - if (scope.type === "project") { - return ["project", "org"].includes(tool.scopeLevel) - } - - // Agent scope: agent + project + org tools - if (scope.type === "agent") { - return ["agent", "project", "org"].includes(tool.scopeLevel) - } - }) -} - -// Example: List tools in project scope -const projectTools = toolFilter({ type: "project", projectId: "mobile-app" }) -// Returns: CREATE_PR, DEPLOY_STAGING, ORG_RESOURCE_CREATE -``` - -### Operating on Current Scope - -Tools that modify virtual MCPs always operate on the **current scope**: - -```typescript -// Adding a resource to current scope's virtual MCP -decopilot.invokeTool("ADD_RESOURCE", { - // No explicit scope needed - uses current scope - name: "New Documentation", - content: "# Documentation\n\n..." -}) - -// Scope resolution (internal) -const scope = getCurrentScope() -if (scope.type === "project") { - addToVirtualMCP("project-" + scope.projectId, resource) -} -``` - -### Cross-Scope Operations - -Some operations can cross scopes: - -```typescript -// Connecting external MCP to project (from org scope) -// You're in org scope: /:org/connections -decopilot.invokeTool("CONNECT_EXTERNAL_MCP", { - externalMCPUrl: "https://github-mcp.example.com", - targetScope: { - type: "project", - projectId: "mobile-app-rewrite" - } -}) - -// Creates connection and wires to project virtual MCP -``` - -### Scope Context Injection - -Every tool receives scope context: - -```typescript -// Tool definition with scope context -const DEPLOY_TOOL = defineTool({ - name: "DEPLOY_STAGING", - description: "Deploy to staging environment", - - handler: async (input, ctx: MeshContext) => { - // Scope context automatically injected - const scope = ctx.getCurrentScope() - - // Scope determines deployment config - if (scope.type === "project") { - const projectConfig = await ctx.storage.projects.get(scope.projectId) - const stagingUrl = projectConfig.stagingUrl - - return deploy(stagingUrl, input) - } - - throw new Error("DEPLOY_STAGING requires project scope") - } -}) -``` - -## Architecture Diagrams - -### Diagram 1: Decopilot → Virtual MCP vs External MCP - -This diagram illustrates the fundamental architectural constraint: decopilot operates on (editable) virtual MCPs and consumes (read-only) external MCPs. - -```mermaid -graph TB - subgraph "Decopilot Operations" - A[Decopilot] - end - - subgraph "Virtual MCPs (Editable)" - B[Org Virtual MCP] - C[Project Virtual MCP] - D[Agent Virtual MCP] - end - - subgraph "External MCPs (Read-Only)" - E[GitHub MCP Server] - F[Figma MCP Server] - G[Database MCP Server] - end - - A -->|Operates on
Can edit| B - A -->|Operates on
Can edit| C - A -->|Operates on
Can edit| D - - A -.->|Invokes tools
Read-only| E - A -.->|Invokes tools
Read-only| F - A -.->|Invokes tools
Read-only| G - - C -->|Connects to| E - C -->|Connects to| F - C -->|Connects to| G - - style A fill:#ffe1e1 - style B fill:#e1f5ff - style C fill:#e1f5ff - style D fill:#e1f5ff - style E fill:#e1e1e1 - style F fill:#e1e1e1 - style G fill:#e1e1e1 -``` - -### Diagram 2: Routes → Scopes → Virtual MCPs - -This diagram shows how routes automatically determine scope, which determines the virtual MCP decopilot operates on. - -```mermaid -graph LR - subgraph "Routes" - A1[/:org/settings] - A2[/:org/connections] - B1[/:org/projects/:id] - B2[/:org/projects/:id/settings] - C1[/:org/agents/:id] - C2[/:org/agents/:id/config] - end - - subgraph "Scopes" - A[Org Scope] - B[Project Scope] - C[Agent Scope] - end - - subgraph "Virtual MCPs" - D[Org Virtual MCP
org-acme-corp] - E[Project Virtual MCP
project-mobile-app] - F[Agent Virtual MCP
agent-security-reviewer] - end - - A1 --> A - A2 --> A - B1 --> B - B2 --> B - C1 --> C - C2 --> C - - A --> D - B --> E - C --> F - - D --> G[Org-wide
Tools/Resources/Prompts] - E --> H[Project-specific
Tools/Resources/Connected MCPs] - F --> I[Agent-bounded
Tools/Resources/Task Prompts] - - style A fill:#e1f5ff - style B fill:#fff4e1 - style C fill:#ffe1e1 - style D fill:#e1f5ff - style E fill:#fff4e1 - style F fill:#ffe1e1 -``` - -### Diagram 3: Org/Project/Agent as Virtual MCPs - -This diagram illustrates the virtual MCP hierarchy and how capabilities flow from org to project to agent. - -```mermaid -graph TB - subgraph "Org Virtual MCP" - A[Organization
org-acme-corp] - A1[Org Tools] - A2[Org Resources] - A3[Org Prompts] - A4[Connection Registry] - end - - subgraph "Project Virtual MCP" - B[Project
project-mobile-app] - B1[Project Tools] - B2[Project Resources] - B3[Connected MCPs] - B4[Project Prompts] - end - - subgraph "Agent Virtual MCP" - C[Agent
agent-security-reviewer] - C1[Bounded Tools] - C2[Agent Resources] - C3[Task Prompts] - end - - A --> A1 - A --> A2 - A --> A3 - A --> A4 - - B --> B1 - B --> B2 - B --> B3 - B --> B4 - - C --> C1 - C --> C2 - C --> C3 - - A -.->|Inherits| B - B -.->|Inherits| C - - A4 -.->|Provides connections to| B3 - - style A fill:#e1f5ff - style B fill:#fff4e1 - style C fill:#ffe1e1 -``` - -### Diagram 4: Task-Based Agent Spawning - -This diagram shows the async execution model where decopilot spawns agents on tasks with isolated contexts. - -```mermaid -sequenceDiagram - participant U as User - participant D as Decopilot
(Main Loop) - participant R as Agent Registry - participant A as Security Agent
(Child Task) - participant M as Cheap Model
(Completion Detection) - - U->>D: Request: "Review auth code for security" - - D->>D: Determine task requires specialized agent - D->>R: Query agents with "security-review" capability - R-->>D: Return: security-reviewer-001 - - D->>A: Spawn agent on child task - Note over A: Isolated context
Task ID: task-001
Type: child - - par Agent executes async - A->>A: Invoke SECURITY_SCAN - A->>A: Invoke CVE_LOOKUP - A->>A: Generate findings - and Main loop continues - D->>D: Continue with other work - end - - A->>M: Check if task complete - M-->>A: YES - findings generated - - A-->>D: Return result:
"Found 2 vulnerabilities" - - D->>D: Integrate findings into main context - D->>U: Present agent findings - - Note over D,A: Task-001 status: successful -``` - ---- - -## Key Takeaways - -**Virtual MCP constraint**: Decopilot only works with virtual MCPs because it needs editability. External MCPs are read-only; virtual MCPs are the editable foundation. - -**Everything is a virtual MCP**: Organizations, projects, and agents are all virtual MCPs. This consistency enables a unified architecture. - -**Scope determines behavior**: Routes automatically set scope, which determines the virtual MCP decopilot operates on. Same tools, different behavior per scope. - -**Task-based async execution**: Agents spawn on tasks with isolated contexts, enabling parallel work without context pollution. - -**Dynamic capabilities**: Decopilot can add tools, create resources, and update prompts as it works—reshaping the environment rather than just consuming it. - -**Clear separation**: External MCPs provide stable tools. Virtual MCPs provide dynamic aggregation and editability. Decopilot operates on virtual MCPs and invokes tools from external MCPs. - -Understanding this architecture is essential to using decopilot effectively—it's not just a chatbot with API access, it's a system that dynamically configures and operates on virtual MCP infrastructure. - ---- - -**Ready to dive deeper?** Explore [Scopes](/en/mcp-mesh/decopilot/scopes) for scope-based routing details, or learn about [Virtual MCPs](/en/mcp-mesh/virtual-mcps) to understand the foundation layer. For practical implementation, see [Projects](/en/mcp-mesh/projects) and explore how to configure project-level virtual MCPs. From b65d011397061ba918383de0cd32b7cf5ea59dee Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 14:28:55 -0300 Subject: [PATCH 29/51] docs(nav): restructure documentation navigation and ordering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update sidebar to reflect new documentation structure - Reorder MCP Mesh pages: Quickstart → Overview → Core Concepts - Add special sorting for api-reference section - Update navigation utilities and i18n keys Co-Authored-By: Claude Sonnet 4.5 --- .../client/src/components/ui/Sidebar.astro | 98 ++++++++++++++----- .../docs/client/src/components/ui/Sidebar.tsx | 67 +++++++------ apps/docs/client/src/i18n/ui.ts | 2 + apps/docs/client/src/utils/navigation.ts | 34 +++---- 4 files changed, 131 insertions(+), 70 deletions(-) diff --git a/apps/docs/client/src/components/ui/Sidebar.astro b/apps/docs/client/src/components/ui/Sidebar.astro index 15f4faeb96..e89bd119d7 100644 --- a/apps/docs/client/src/components/ui/Sidebar.astro +++ b/apps/docs/client/src/components/ui/Sidebar.astro @@ -51,6 +51,14 @@ function buildTree(docs: any[]): TreeNode[] { // Sort the tree for consistent ordering const sortTree = (nodes: TreeNode[]): TreeNode[] => { const sorted = nodes.sort((a, b) => { + // Special case: api-reference should come after folders + if (a.name === "api-reference" && b.type === "folder") { + return 1; // api-reference comes after folders + } + if (b.name === "api-reference" && a.type === "folder") { + return -1; // folders come before api-reference + } + // First sort by type: files before folders if (a.type !== b.type) { return a.type === "file" ? -1 : 1; @@ -58,22 +66,18 @@ function buildTree(docs: any[]): TreeNode[] { // For files only - custom ordering if (a.type === "file" && b.type === "file") { - // Force introduction to be first - if (a.name.includes("introduction")) return -1; - if (b.name.includes("introduction")) return 1; - // Get parent folder to determine which order to use const parentPath = a.path[a.path.length - 2]; // Custom order for decocms top-level pages if (parentPath === "mcp-mesh") { // NOTE: doc IDs do not include ".mdx" (e.g. "overview", not "overview.mdx") - // Order follows: Getting Started → Core Concepts → Working with MCP → Monitoring → Decopilot → Security → Operations → Reference + // Order follows: Quickstart → Overview → Core Concepts → Working with MCP → Monitoring → User Management → Reference const mcpMeshOrder = [ - // Getting Started + // Quickstart & Overview "quickstart", - // Core Concepts "overview", + // Core Concepts "concepts", // Working with MCP "connections", @@ -82,10 +86,9 @@ function buildTree(docs: any[]): TreeNode[] { "agents", // Monitoring & Observability "monitoring", - // Security & Access Control - "authentication", - "authorization-and-roles", + // User Management "api-keys", + "user-management", // Reference "api-reference", ]; @@ -148,10 +151,54 @@ function buildTree(docs: any[]): TreeNode[] { if (bIndex !== -1) return 1; } - // Custom order for decocms deploy docs + // Custom order for self-hosting section + if (parentPath === "self-hosting") { + const selfHostingOrder = ["quickstart", "authentication"]; + const aIndex = selfHostingOrder.indexOf(a.name); + const bIndex = selfHostingOrder.indexOf(b.name); + if (aIndex !== -1 && bIndex !== -1) { + return aIndex - bIndex; + } + if (aIndex !== -1) return -1; + if (bIndex !== -1) return 1; + } + + // Custom order for api-reference section + if (parentPath === "api-reference") { + const apiRefOrder = ["built-in-tools"]; + const aIndex = apiRefOrder.indexOf(a.name); + const bIndex = apiRefOrder.indexOf(b.name); + if (aIndex !== -1 && bIndex !== -1) { + return aIndex - bIndex; + } + if (aIndex !== -1) return -1; + if (bIndex !== -1) return 1; + } + + // Custom order for built-in-tools section + if (parentPath === "built-in-tools") { + const builtInToolsOrder = [ + "tool-search", + "tool-enable", + "agent-search", + "subtask-run", + "user-ask", + "resource-read", + "prompt-read", + ]; + const aIndex = builtInToolsOrder.indexOf(a.name); + const bIndex = builtInToolsOrder.indexOf(b.name); + if (aIndex !== -1 && bIndex !== -1) { + return aIndex - bIndex; + } + if (aIndex !== -1) return -1; + if (bIndex !== -1) return 1; + } + + // Custom order for deploy docs (now under self-hosting) const rootPath = a.path[0]; if (rootPath === "mcp-mesh" && parentPath === "deploy") { - const deployOrder = ["local-docker-compose", "kubernetes-helm-chart"]; + const deployOrder = ["docker-compose", "kubernetes"]; const aIndex = deployOrder.indexOf(a.name); const bIndex = deployOrder.indexOf(b.name); if (aIndex !== -1 && bIndex !== -1) { @@ -169,9 +216,10 @@ function buildTree(docs: any[]): TreeNode[] { "mcp-mesh": 0, // decocms docs (main product) "getting-started": 1, // Getting Started (after intro) decopilot: 2, // Decopilot (elevated section within mcp-mesh) - deploy: 3, // Deploy section - "no-code-guides": 4, // Legacy admin guides - "full-code-guides": 5, // Legacy admin guides + "self-hosting": 3, // Self-hosting section + deploy: 4, // Deploy section (under self-hosting) + "no-code-guides": 5, // Legacy admin guides + "full-code-guides": 6, // Legacy admin guides }; const aOrder = folderOrder[a.name] ?? Number.POSITIVE_INFINITY; @@ -224,15 +272,21 @@ function groupLegacyAdminSections(nodes: TreeNode[]): TreeNode[] { } : null; - // Make "Introduction" the primary entry point, then product docs. - const introduction = files.find((f) => f.name === "introduction"); - const otherFiles = files.filter((f) => f.name !== "introduction"); - + // Flatten mcp-mesh folder - bring its children to the top level + // mcp-mesh children will be shown at the top level const next: TreeNode[] = []; - if (introduction) next.push(introduction); - if (mcpMesh) next.push(mcpMesh); - next.push(...otherFiles); + + // Add all mcp-mesh children directly at top level (order controlled by mcpMeshOrder array) + if (mcpMesh && mcpMesh.children.length > 0) { + next.push(...mcpMesh.children); + } + + // Add any other top-level files + next.push(...files); + + // Add legacy admin section at the end if (legacyFolder) next.push(legacyFolder); + return next; } diff --git a/apps/docs/client/src/components/ui/Sidebar.tsx b/apps/docs/client/src/components/ui/Sidebar.tsx index 399865e408..203b3d0d90 100644 --- a/apps/docs/client/src/components/ui/Sidebar.tsx +++ b/apps/docs/client/src/components/ui/Sidebar.tsx @@ -118,15 +118,17 @@ function TreeItem({ ? `/${locale}/${docPath ?? node.path.join("/")}` : null; + // A node should be collapsible if it has children, regardless of whether it's a file or folder + const isCollapsible = node.hasChildren; + const isFolder = node.type === "folder"; + return (
  • {/* Indentation spacer for nested items */} @@ -135,15 +137,15 @@ function TreeItem({ )} {/* Icon */} - {node.type === "folder" ? ( + {isFolder || (isCollapsible && !node.doc?.data?.icon) ? ( onToggle(node.id)} > - {translations[`sidebar.section.${node.name}`] || node.name} + {node.doc?.data?.title || + translations[`sidebar.section.${node.name}`] || + node.name} - {node.hasChildren && ( - - )} + ) : ( { - if (node.depth === 0 && node.type === "file") return "root-files"; - return "root-folders"; - }; - return (
    + + ) : ( + + {/* Indentation spacer for nested items */} + {node.depth > 0 && ( +
    • ); } @@ -275,50 +303,71 @@ function TreeList({ } export default function Sidebar({ tree, locale, translations }: SidebarProps) { - const [treeState, setTreeState] = useState>(new Map()); - - useEffect(() => { - // Load saved state from localStorage - const savedState = JSON.parse( - localStorage.getItem("sidebar-tree-state") || "{}", - ); + // Initialize with default state (same on server and client for hydration match) + const [treeState, setTreeState] = useState>(() => { const initialState = new Map(); - // If the current page is inside a folder, ensure its ancestor folders are expanded - // so the active item is visible (even if the default is collapsed). - const currentPath = globalThis.location.pathname; - const relativePath = currentPath.replace(`/${locale}/`, ""); - const parts = relativePath.split("/").filter(Boolean); - const expandedAncestors = new Set(); - for (let i = 1; i <= parts.length - 1; i++) { - expandedAncestors.add(parts.slice(0, i).join("/")); - } + // Default: most sections expanded, some collapsed + const collapsedByDefault = new Set([ + "admin-decocms-com/getting-started", + "admin-decocms-com/no-code-guides", + "admin-decocms-com/full-code-guides", + ]); - // Initialize tree state - default to expanded (with a few collapsed-by-default sections) tree.forEach((node) => { - // Initialize state for any node that has children (files or folders) if (node.hasChildren) { - const saved = savedState[node.id]; - // Default: show "Legacy Admin" open, but keep its sections closed (as a compact TOC). + initialState.set(node.id, !collapsedByDefault.has(node.id)); + } + }); + + return initialState; + }); + + // After hydration, apply localStorage state and expand ancestors of current page + useEffect(() => { + try { + if (typeof window !== "undefined" && window.localStorage) { + const savedState = JSON.parse( + window.localStorage.getItem("sidebar-tree-state") || "{}", + ); + + // Get current path to expand ancestors + const currentPath = window.location.pathname; + const relativePath = currentPath.replace(`/${locale}/`, ""); + const parts = relativePath.split("/").filter(Boolean); + const expandedAncestors = new Set(); + for (let i = 1; i <= parts.length - 1; i++) { + expandedAncestors.add(parts.slice(0, i).join("/")); + } + + // Build new state with saved values and expanded ancestors + const newState = new Map(); const collapsedByDefault = new Set([ "admin-decocms-com/getting-started", "admin-decocms-com/no-code-guides", "admin-decocms-com/full-code-guides", ]); - const defaultExpanded = collapsedByDefault.has(node.id) ? false : true; - - const shouldExpand = - typeof saved === "boolean" ? saved : defaultExpanded; - initialState.set( - node.id, - expandedAncestors.has(node.id) ? true : shouldExpand, - ); + tree.forEach((node) => { + if (node.hasChildren) { + const saved = savedState[node.id]; + const defaultExpanded = !collapsedByDefault.has(node.id); + const shouldExpand = + typeof saved === "boolean" ? saved : defaultExpanded; + + newState.set( + node.id, + expandedAncestors.has(node.id) ? true : shouldExpand, + ); + } + }); + + setTreeState(newState); } - }); - - setTreeState(initialState); - }, [tree]); + } catch (error) { + console.error("Failed to load sidebar state:", error); + } + }, [tree, locale]); const updateFolderVisibility = (folderId: string, isExpanded: boolean) => { setTreeState((prev) => { @@ -327,13 +376,23 @@ export default function Sidebar({ tree, locale, translations }: SidebarProps) { return newState; }); - // Save state to localStorage - const stateToSave: Record = {}; - treeState.forEach((value, key) => { - stateToSave[key] = value; - }); - stateToSave[folderId] = isExpanded; - localStorage.setItem("sidebar-tree-state", JSON.stringify(stateToSave)); + // Save state to localStorage (client-side only) + try { + if (typeof window !== "undefined" && window.localStorage) { + const stateToSave: Record = {}; + treeState.forEach((value, key) => { + stateToSave[key] = value; + }); + stateToSave[folderId] = isExpanded; + window.localStorage.setItem( + "sidebar-tree-state", + JSON.stringify(stateToSave), + ); + } + } catch (error) { + // Ignore localStorage errors + console.error("Failed to save sidebar state to localStorage:", error); + } }; const handleFolderToggle = (folderId: string) => { From 1b73bcd13c25d8e85792731cdd073bc088a629e4 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 15:31:26 -0300 Subject: [PATCH 43/51] fix(docs): add React keys to hydrated components in DocsLayout Added key props to LanguageSelector and ThemeToggle components during client-side hydration to prevent React warnings and ensure proper reconciliation. Co-Authored-By: Claude Sonnet 4.5 --- apps/docs/client/src/layouts/DocsLayout.astro | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/apps/docs/client/src/layouts/DocsLayout.astro b/apps/docs/client/src/layouts/DocsLayout.astro index e2bf34c17b..0b4a6bfaac 100644 --- a/apps/docs/client/src/layouts/DocsLayout.astro +++ b/apps/docs/client/src/layouts/DocsLayout.astro @@ -353,12 +353,13 @@ const editUrl = doc root.render( React.createElement("div", { className: "flex items-center gap-2" }, [ React.createElement(LanguageSelector, { + key: "language-selector", locale: document.querySelector("nav")?.getAttribute("data-locale") || "en", className: "w-32", }), - React.createElement(ThemeToggle), + React.createElement(ThemeToggle, { key: "theme-toggle" }), ]) ); } From 0a319228fe58f055b4e321b7ca32f6c17e2a6861 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 15:58:05 -0300 Subject: [PATCH 44/51] docs: change landing page redirect to quickstart Update the documentation landing page to redirect users to /en/mcp-mesh/quickstart instead of /en/introduction. This provides a better first experience by immediately guiding users to the quickstart guide. Co-Authored-By: Claude Sonnet 4.5 --- apps/docs/client/src/pages/[locale]/[...slug].astro | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/docs/client/src/pages/[locale]/[...slug].astro b/apps/docs/client/src/pages/[locale]/[...slug].astro index f94bada716..a54db2418f 100644 --- a/apps/docs/client/src/pages/[locale]/[...slug].astro +++ b/apps/docs/client/src/pages/[locale]/[...slug].astro @@ -43,9 +43,9 @@ if (slug === "getting-started/context-engineers") { return Astro.redirect(`/${lang}/getting-started/developers`); } -// Redirect to introduction if no document is found (i.e., when visiting /en) +// Redirect to quickstart if no document is found (i.e., when visiting /en) if (!doc) { - return Astro.redirect(`/${lang}/introduction`); + return Astro.redirect(`/${lang}/mcp-mesh/quickstart`); } --- From 2f186dec957ea586fef1f351aa924b437363d6ec Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 16:09:02 -0300 Subject: [PATCH 45/51] wip quickstart --- apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx index a5a3c7f2b9..0a4918dc3a 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx @@ -12,7 +12,7 @@ The fastest way to experience deco CMS is through our managed service at **mesh- ### Step 1: Sign Up -Navigate to [mesh-admin.deco CMS.com](https://mesh-admin.deco CMS.com) and create your account using: +Navigate to [mesh-admin.decocms.com](https://mesh-admin.decocms.com) and create your account using: - Email and password - GitHub OAuth - Google OAuth From 126215e174a88336eba2fc24b1d4a6029c052411 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 16:19:50 -0300 Subject: [PATCH 46/51] docs(examples): update documentation examples to focus on e-commerce use cases Replace generic DevOps/tech examples (GitHub, deployments, Slack notifications) with concrete e-commerce scenarios (Shopify orders, inventory management, fulfillment operations, payment processing) across all documentation. Changes: - MCP Mesh docs: Updated agents, projects, and virtual MCPs with order fulfillment, inventory, and multi-brand store examples - Code guides: Replaced generic tool examples (email, weather, notifications) with e-commerce tools (order confirmation, inventory check, payment processing) - Quickstart: Added more e-commerce specific example queries Co-Authored-By: Claude Sonnet 4.5 --- .../en/full-code-guides/building-tools.mdx | 166 ++++++++++++------ .../en/full-code-guides/building-views.mdx | 15 ++ .../client/src/content/en/mcp-mesh/agents.mdx | 16 +- .../src/content/en/mcp-mesh/concepts.mdx | 4 +- .../src/content/en/mcp-mesh/projects.mdx | 12 +- .../src/content/en/mcp-mesh/quickstart.mdx | 5 +- .../src/content/en/mcp-mesh/virtual-mcps.mdx | 32 ++-- .../en/no-code-guides/creating-tools.mdx | 49 +++--- 8 files changed, 185 insertions(+), 114 deletions(-) diff --git a/apps/docs/client/src/content/en/full-code-guides/building-tools.mdx b/apps/docs/client/src/content/en/full-code-guides/building-tools.mdx index baf8253b43..5899b77d1d 100644 --- a/apps/docs/client/src/content/en/full-code-guides/building-tools.mdx +++ b/apps/docs/client/src/content/en/full-code-guides/building-tools.mdx @@ -28,31 +28,38 @@ Every tool requires four components: import { createTool } from "@deco/workers-runtime"; import { z } from "zod"; -const createEmailTool = (env: Env) => +const createOrderConfirmationTool = (env: Env) => createTool({ - id: "EMAIL_SEND", - description: "Send an email via Gmail. Use for notifications and communications.", + id: "ORDER_CONFIRMATION_SEND", + description: "Send order confirmation email to customer. Use after successful order placement.", inputSchema: z.object({ - to: z.string().email(), - subject: z.string(), - body: z.string(), + customerEmail: z.string().email(), + orderNumber: z.string(), + orderTotal: z.number().positive(), + items: z.array(z.object({ + name: z.string(), + quantity: z.number(), + price: z.number(), + })), }), - outputSchema: z.object({ + outputSchema: z.object({ success: z.boolean(), messageId: z.string().optional(), + sentAt: z.string(), }), execute: async ({ context }) => { - const response = await env["gmail"].SEND_EMAIL({ - to: context.to, - subject: context.subject, - body: context.body, + const response = await env["sendgrid"].SEND_EMAIL({ + to: context.customerEmail, + subject: `Order Confirmation - #${context.orderNumber}`, + body: `Thank you for your order! Total: $${context.orderTotal}`, }); - return { + return { success: true, messageId: response.id, + sentAt: new Date().toISOString(), }; }, - }); + }); ``` **Key points:** @@ -65,32 +72,44 @@ const createEmailTool = (env: Env) => ### External API Calls ```typescript -const createWeatherTool = (env: Env) => +const createInventoryCheckTool = (env: Env) => createTool({ - id: "WEATHER_FETCH", - description: "Get current weather for a city using OpenWeather API", + id: "PRODUCT_INVENTORY_CHECK", + description: "Check product inventory levels across warehouses using inventory API", inputSchema: z.object({ - city: z.string().min(1), + sku: z.string().min(1), + warehouseIds: z.array(z.string()).optional(), }), outputSchema: z.object({ - temperature: z.number(), - condition: z.string(), - humidity: z.number().optional(), + sku: z.string(), + totalQuantity: z.number(), + locations: z.array(z.object({ + warehouseId: z.string(), + quantity: z.number(), + reserved: z.number(), + })), + lowStock: z.boolean(), }), execute: async ({ context }) => { const response = await fetch( - `https://api.openweathermap.org/data/2.5/weather?q=${context.city}&appid=${env.OPENWEATHER_API_KEY}` + `https://api.inventory-system.com/v1/products/${context.sku}/stock`, + { + headers: { "Authorization": `Bearer ${env.INVENTORY_API_KEY}` } + } ); - + if (!response.ok) { - throw new Error(`Weather API error: ${response.statusText}`); + throw new Error(`Inventory API error: ${response.statusText}`); } - + const data = await response.json(); + const totalQuantity = data.locations.reduce((sum, loc) => sum + loc.quantity, 0); + return { - temperature: data.main.temp, - condition: data.weather[0].description, - humidity: data.main.humidity, + sku: context.sku, + totalQuantity, + locations: data.locations, + lowStock: totalQuantity < 10, }; }, }); @@ -101,32 +120,41 @@ const createWeatherTool = (env: Env) => Call installed integrations through the environment: ```typescript -const createNotificationTool = (env: Env) => +const createOrderNotificationTool = (env: Env) => createTool({ - id: "SLACK_NOTIFY", - description: "Send a notification to a Slack channel", + id: "ORDER_NOTIFICATION_SEND", + description: "Send order status notification to fulfillment team via Slack", inputSchema: z.object({ - channel: z.string(), - message: z.string(), + orderNumber: z.string(), + status: z.enum(["pending", "processing", "shipped", "delivered"]), + customerName: z.string(), + totalAmount: z.number(), }), - outputSchema: z.object({ + outputSchema: z.object({ sent: z.boolean(), timestamp: z.string(), + channel: z.string(), }), execute: async ({ context }) => { + const message = `🛒 Order #${context.orderNumber} - ${context.status.toUpperCase()}\n` + + `Customer: ${context.customerName}\n` + + `Amount: $${context.totalAmount}`; + const result = await env["slack"].POST_MESSAGE({ - channel: context.channel, - text: context.message, + channel: "#order-fulfillment", + text: message, }); + return { sent: true, timestamp: result.ts, + channel: "#order-fulfillment", }; }, }); ``` -Install integrations from **Apps** in your workspace. Each integration's tools are available at `env["integration-id"]` where the ID is shown in the Apps section (e.g., `env["gmail"]`, `env["slack"]`). +Install integrations from **Apps** in your workspace. Each integration's tools are available at `env["integration-id"]` where the ID is shown in the Apps section (e.g., `env["shopify"]`, `env["slack"]`, `env["stripe"]`). ### Database Operations @@ -139,15 +167,23 @@ import { customers } from "./schema"; const createCustomerTool = (env: Env) => createTool({ id: "CUSTOMER_CREATE", - description: "Create a new customer in the database", + description: "Create a new customer in the ecommerce database with loyalty tier", inputSchema: z.object({ name: z.string().min(1), email: z.string().email(), - city: z.string(), - state: z.string().length(2), + phone: z.string().optional(), + shippingAddress: z.object({ + street: z.string(), + city: z.string(), + state: z.string().length(2), + zipCode: z.string(), + }), + loyaltyTier: z.enum(["bronze", "silver", "gold", "platinum"]).default("bronze"), }), - outputSchema: z.object({ + outputSchema: z.object({ id: z.number(), + email: z.string(), + loyaltyTier: z.string(), createdAt: z.date(), }), execute: async ({ context }) => { @@ -157,13 +193,16 @@ const createCustomerTool = (env: Env) => .values({ name: context.name, email: context.email, - city: context.city, - state: context.state, + phone: context.phone, + shippingAddress: JSON.stringify(context.shippingAddress), + loyaltyTier: context.loyaltyTier, }) .returning(); - return { + return { id: result.id, + email: result.email, + loyaltyTier: result.loyaltyTier, createdAt: result.createdAt, }; }, @@ -178,13 +217,17 @@ Add tools to `server/main.ts`: ```typescript import { withRuntime } from "@deco/workers-runtime"; -import { createEmailTool } from "./tools/email"; +import { createOrderConfirmationTool } from "./tools/notifications"; +import { createInventoryCheckTool } from "./tools/inventory"; import { createCustomerTool } from "./tools/customers"; +import { createOrderNotificationTool } from "./tools/fulfillment"; const { Workflow, ...runtime } = withRuntime({ tools: [ - createEmailTool, + createOrderConfirmationTool, + createInventoryCheckTool, createCustomerTool, + createOrderNotificationTool, // Add more tools here ], workflows: [], @@ -212,10 +255,13 @@ Start your dev server and test in two ways: // In your React component import { client } from "./lib/rpc"; -const result = await client.tools.EMAIL_SEND({ - to: "user@example.com", - subject: "Test", - body: "Hello!", +const result = await client.tools.ORDER_CONFIRMATION_SEND({ + customerEmail: "customer@example.com", + orderNumber: "ORD-12345", + orderTotal: 299.99, + items: [ + { name: "Wireless Headphones", quantity: 1, price: 299.99 } + ], }); ``` @@ -225,14 +271,14 @@ Tools are immediately available via typed RPC, no API layer needed. **Single Responsibility** ``` -✅ EMAIL_SEND, CUSTOMER_CREATE, INVOICE_GENERATE -❌ CUSTOMER_CREATE_AND_EMAIL_AND_NOTIFY +✅ ORDER_CONFIRMATION_SEND, CUSTOMER_CREATE, PRODUCT_INVENTORY_CHECK +❌ CUSTOMER_CREATE_AND_EMAIL_AND_SYNC_INVENTORY ``` **Descriptive Names** - Follow `RESOURCE_ACTION` pattern: ``` -✅ ORDER_TOTAL_CALCULATE, LEAD_QUALIFY -❌ calculateTotal, qualify_lead +✅ ORDER_TOTAL_CALCULATE, PRODUCT_PRICE_UPDATE, CART_ABANDONED_SEND +❌ calculateTotal, updatePrice, sendCart ``` **Strong Typing** - Zod schemas provide runtime validation and compile-time types: @@ -263,14 +309,18 @@ Group related tools in files: ``` server/tools/ ├── index.ts # Export all tools -├── customers.ts # CUSTOMER_CREATE, CUSTOMER_FETCH, etc. -├── emails.ts # EMAIL_SEND, EMAIL_VALIDATE -└── billing.ts # INVOICE_CREATE, PAYMENT_PROCESS +├── customers.ts # CUSTOMER_CREATE, CUSTOMER_FETCH, CUSTOMER_UPDATE +├── orders.ts # ORDER_CREATE, ORDER_UPDATE, ORDER_CANCEL +├── inventory.ts # PRODUCT_INVENTORY_CHECK, INVENTORY_UPDATE +├── notifications.ts # ORDER_CONFIRMATION_SEND, SHIPPING_NOTIFICATION_SEND +└── payments.ts # PAYMENT_PROCESS, REFUND_CREATE, TRANSACTION_VERIFY ``` Export from `index.ts`: ```typescript export { createCustomerTool, createCustomerFetchTool } from "./customers"; -export { createEmailTool } from "./emails"; -export { createInvoiceTool } from "./billing"; +export { createOrderTool, createOrderUpdateTool } from "./orders"; +export { createInventoryCheckTool } from "./inventory"; +export { createOrderConfirmationTool } from "./notifications"; +export { createPaymentTool } from "./payments"; ``` \ No newline at end of file diff --git a/apps/docs/client/src/content/en/full-code-guides/building-views.mdx b/apps/docs/client/src/content/en/full-code-guides/building-views.mdx index aee2bb6fc2..ffb5f6d4f5 100644 --- a/apps/docs/client/src/content/en/full-code-guides/building-views.mdx +++ b/apps/docs/client/src/content/en/full-code-guides/building-views.mdx @@ -269,6 +269,21 @@ const { data, isLoading } = useQuery({ queryKey: ["customers"], queryFn: () => client.tools.CUSTOMERS_LIST(), }); + +// Display customer list with loyalty tier and total orders +if (isLoading) return
    Loading customers...
    ; + +return ( +
    + {data?.customers.map(customer => ( +
    +

    {customer.name}

    +

    Loyalty: {customer.loyaltyTier}

    +

    Total Orders: {customer.totalOrders}

    +
    + ))} +
    +); ``` diff --git a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx index 52be688385..b7198e9f0a 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/agents.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/agents.mdx @@ -42,9 +42,9 @@ Agents follow the same pattern as standard agent skills (`SKILL.md` files), maki Since agents are [Virtual MCPs](/en/mcp-mesh/virtual-mcps), you can compose them from existing connections, define capabilities inline, or mix both approaches. -## Example: Production Deployment Agent +## Example: Order Fulfillment Agent -A deployment agent might aggregate GitHub tools for tagging and releases, Slack tools for notifications, and monitoring tools for health checks. The agent handles production deployments with a focused toolset—create tags, merge PRs, post deployment notifications, verify health—all within its single-purpose scope. +An order fulfillment agent might aggregate Shopify tools for order management, ShipStation tools for shipping label generation, and Slack tools for fulfillment team notifications. The agent handles order fulfillment with a focused toolset—fetch pending orders, check inventory, generate shipping labels, send tracking notifications—all within its single-purpose scope. ## Built-in Agents @@ -65,16 +65,16 @@ These agents operate at organization level and leverage Management MCP tools for **Single-purpose focus**: Each agent should do one thing well. Narrow scope improves clarity, reliability, and maintainability. **Clear description**: Write descriptions that help decopilot understand when to spawn the agent. Use `[Verb] + [Object] + [Context]` pattern: -- "Deploy applications to production environments" -- "Analyze test coverage for code quality" -- "Manage agent lifecycle in the organization" +- "Fulfill customer orders and generate shipping labels" +- "Analyze sales data for inventory optimization" +- "Process customer refunds and returns" **Detailed instructions**: Provide clear guidelines in the instructions field—just like you would in a `SKILL.md` file. Include constraints, workflow steps, and behavioral guidelines. -**Tool selection**: Choose tools that align with the agent's description. A research agent needs read-only tools; a deployment agent needs release and notification tools. Overly broad tool access dilutes focus. +**Tool selection**: Choose tools that align with the agent's description. A customer service agent needs order lookup and refund tools; an inventory agent needs stock checking and alert tools. Overly broad tool access dilutes focus. -**Good**: "Deployment Agent" (deploys to production) -**Too broad**: "DevOps Agent" (deploys, monitors, manages infrastructure, handles incidents...) +**Good**: "Order Fulfillment Agent" (processes and ships orders) +**Too broad**: "Ecommerce Operations Agent" (fulfillment, customer service, inventory, marketing, analytics...) ## Using Agents diff --git a/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx b/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx index ee89ad597a..f988796cec 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/concepts.mdx @@ -21,14 +21,14 @@ Both agents and projects are Virtual MCPs, but they serve different purposes in - **Broad scope** - Cover multiple workflows and capabilities within a work context - **Long-lived** - Evolve over time as work progresses - **Team collaboration** - Shared workspace for team members -- **Example** - "Mobile App Rewrite" project with design, development, and deployment tools +- **Example** - "Multi-Brand Store Migration" project with inventory sync, order management, and customer data migration tools - **When to use** - Organizing work by product line, client, team, or initiative **Agents** are organization-wide configurations that can be spawned in any context: - **Narrow scope** - Clear, focused objective with curated toolset - **Task-specific** - Designed for particular operations or workflows - **Fresh execution state** - Each spawn starts with clean context in tasks, subtasks, or projects -- **Example** - "Agent Management Agent" that only creates/edits/deletes agents +- **Example** - "Refund Processing Agent" that only handles customer refunds and return authorizations - **When to use** - Focused operations, built-in mesh management, or specialized workflows Both follow the same Virtual MCP architecture, but their design principles differ: projects organize capabilities for broad work contexts, while agents are reusable configurations that can be instantiated on-demand with fresh execution state. diff --git a/apps/docs/client/src/content/en/mcp-mesh/projects.mdx b/apps/docs/client/src/content/en/mcp-mesh/projects.mdx index 918e61c70f..97050a00d0 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/projects.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/projects.mdx @@ -36,9 +36,9 @@ Create a project, then configure it by remixing capabilities: Since projects are [Virtual MCPs](/en/mcp-mesh/virtual-mcps), you get full composability—remix external capabilities with custom definitions to build exactly what your team needs. -## Example: E-commerce Project +## Example: Multi-Brand Storefront Project -An e-commerce redesign project might aggregate Shopify tools for storefront management, analytics tools for conversion tracking, and brand guidelines as resources. AI agents working in this project deploy storefronts, analyze metrics, and follow brand standards—all within the project's isolated scope. +A multi-brand storefront project might aggregate Shopify tools for product catalog management, Stripe tools for payment processing, analytics tools for conversion tracking, and brand-specific guidelines as resources. AI agents working in this project manage product listings, process orders, analyze sales performance, and follow brand standards—all within the project's isolated scope. Each brand gets its own project with isolated credentials and brand-specific configuration. ## Scope Isolation @@ -52,10 +52,10 @@ Project A cannot access Project B's tools or credentials. Organization-level cap ## Use Cases -- **Client work** - One project per client with isolated tools and credentials -- **Product lines** - Separate mobile, web, and backend projects with distinct toolsets -- **Feature initiatives** - Temporary projects for major features with curated capabilities -- **Multi-tenancy** - Projects as tenant boundaries in SaaS applications +- **Multi-brand stores** - One project per brand with isolated product catalogs and credentials +- **Marketplace operations** - Separate vendor management, fulfillment, and customer service projects with distinct toolsets +- **Seasonal campaigns** - Temporary projects for holiday sales with curated marketing and inventory tools +- **B2B portals** - Projects as tenant boundaries for wholesale customer accounts with custom pricing and catalogs ## Why Use Projects? diff --git a/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx index 0a4918dc3a..c182a06475 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/quickstart.mdx @@ -46,8 +46,11 @@ Once you've connected at least one MCP server, you can start using the built-in 3. Try asking questions or requesting actions that use your connections: - "Show me today's orders from Shopify" - "What's my current inventory for product SKU-12345?" - - "List recent failed payment transactions" + - "List recent failed payment transactions from Stripe" - "Create a refund for order #1234" + - "Update the stock quantity for product 'Wireless Headphones' to 150 units" + - "Generate a sales report for the last 30 days" + - "Send abandoned cart reminders to customers from last week" The AI will automatically invoke the right tools from your connections to fulfill your requests. diff --git a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx index 706deab752..efe71420fa 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx @@ -33,12 +33,12 @@ A **connection** is how you wire up an external MCP server to deco CMS (see [Con 2. **Combine them** into a single virtual MCP package 3. **Your agent gets** aggregated access to all selected capabilities in one place -**Example**: A "deployment-ops" virtual MCP might remix: -- **GitHub connection**: PR management tools + repository documentation -- **Slack connection**: Messaging and notification tools -- **Database connection**: Migration and schema tools +**Example**: An "order-fulfillment-ops" virtual MCP might remix: +- **Shopify connection**: Order management tools + product catalog +- **ShipStation connection**: Shipping label generation and tracking tools +- **Slack connection**: Fulfillment team notification tools -Your AI agent uses this one virtual MCP to orchestrate across all three systems. +Your AI agent uses this one virtual MCP to orchestrate the entire order fulfillment process across all three systems. ### Extend with Inline Capabilities @@ -65,7 +65,7 @@ Inline tools are ideal for **feature gating**—wrapping connection tools with v Inline tools can coordinate multiple connections in a single operation. -**Example**: A deployment tool that runs tests (CI connection), merges a PR (GitHub connection), and notifies the team (Slack connection)—all in one coordinated workflow. +**Example**: An order fulfillment tool that checks inventory (warehouse connection), creates a shipping label (ShipStation connection), sends order confirmation (SendGrid connection), and notifies the fulfillment team (Slack connection)—all in one coordinated workflow. These patterns enable **authorization enforcement**, **input validation**, **audit logging** (see [Monitoring](/en/mcp-mesh/monitoring)), and **workflow orchestration** across your MCP infrastructure. @@ -73,11 +73,11 @@ These patterns enable **authorization enforcement**, **input validation**, **aud The real power comes from combining both approaches—remixing capabilities from connections and extending them with inline definitions. -**Example**: A "development-assistant" virtual MCP that combines: -- **GitHub connection tools**: PR management, issue tracking -- **GitHub connection resources**: Repository contributing guide -- **Inline prompts**: Custom PR description templates for your team -- **Inline resources**: Team coding standards and style guides +**Example**: A "customer-service-assistant" virtual MCP that combines: +- **Shopify connection tools**: Order lookup, refund processing +- **Shopify connection resources**: Product catalog and return policies +- **Inline prompts**: Custom customer communication templates +- **Inline resources**: Customer service guidelines and FAQ responses One virtual MCP, multiple sources (connections + inline definitions), unified agent experience. @@ -130,11 +130,11 @@ Virtual MCPs provide the **foundational capability** that powers specialized fea Virtual MCPs turn fragmented MCP connections into unified, reusable capability packages: **Real-world applications:** -- **Unified Deployment Ops**: Package GitHub (PRs, releases) + Slack (notifications) + database (migrations) into one deployment MCP -- **Custom Code Review**: Remix GitHub tools with inline security/performance prompts and team style guides -- **Development Assistant**: Combine GitHub + Jira tools with inline workflow prompts and project context -- **Team-wide MCP Sharing**: Share access to a Cloudflare MCP connection across your team while filtering out administrative operations—giving developers safe, scoped access to DNS management and Workers deployment without exposing account-level controls -- **Cross-system Orchestration**: Package CRM, analytics, and communication tools for end-to-end business processes +- **Order Fulfillment Operations**: Package Shopify (orders) + ShipStation (shipping) + Slack (notifications) into one fulfillment MCP +- **Customer Service Hub**: Remix Shopify tools with inline customer service prompts and return policy guidelines +- **Inventory Management**: Combine warehouse APIs + Shopify inventory tools with inline stock alert workflows +- **Multi-brand Store Management**: Share access to a Shopify MCP connection across your team while filtering brand-specific operations—giving managers scoped access to their brand's products and orders without exposing other brands +- **Ecommerce Analytics**: Package Shopify, Google Analytics, and Stripe tools for end-to-end sales and conversion tracking **Key benefits:** - **Selective remixing**: Choose exactly which tools, resources, and prompts to include from each connection diff --git a/apps/docs/client/src/content/en/no-code-guides/creating-tools.mdx b/apps/docs/client/src/content/en/no-code-guides/creating-tools.mdx index 24378a7ef9..2cf3c162cc 100644 --- a/apps/docs/client/src/content/en/no-code-guides/creating-tools.mdx +++ b/apps/docs/client/src/content/en/no-code-guides/creating-tools.mdx @@ -28,13 +28,13 @@ The easiest way to create tools is by describing what you need: **Example prompts:** ``` -I need a tool that checks if a domain is available for purchase +I need a tool that checks if a product is in stock across all warehouses -Create a tool to fetch weather data for a given city +Create a tool to calculate discounts based on customer loyalty tier -Help me build a tool that calculates shipping costs based on weight and destination +Help me build a tool that recommends products based on customer purchase history -I want to validate email addresses and check if the domain has MX records +I want to validate customer email addresses and send welcome discount codes ``` **What happens next:** @@ -45,11 +45,11 @@ I want to validate email addresses and check if the domain has MX records **Refine as you go:** ``` -Add validation to the email parameter +Add validation to ensure the customer has a valid loyalty account -Include a timeout parameter with default of 30 seconds +Include a minimum order total parameter with default of $50 -Change the output to also return the domain registrar +Change the output to also return the discount expiration date ``` This conversational approach means you start with a rough idea and iterate toward exactly what you need. @@ -69,13 +69,13 @@ When you create a tool (whether via deco chat or by clicking the code icon to wr Tools follow the `RESOURCE_ACTION` pattern with `UPPERCASE_WITH_UNDERSCORES`: **Examples:** -- `CUSTOMER_FETCH` - Fetch a customer record -- `EMAIL_SEND` - Send an email -- `INVOICE_CREATE` - Create an invoice +- `PRODUCT_INVENTORY_CHECK` - Check product inventory levels +- `ORDER_CONFIRMATION_SEND` - Send order confirmation email +- `CART_DISCOUNT_APPLY` - Apply discount to shopping cart ``` -Good: LEAD_QUALIFY, ORDER_TOTAL_CALCULATE -Bad: qualifyLead, calculate-order-total +Good: CUSTOMER_LOYALTY_UPDATE, PRODUCT_PRICE_CALCULATE +Bad: updateLoyalty, calculate-product-price ``` **Why this matters:** Agents use tool names to decide when to use them. Descriptive names = better decisions. @@ -84,10 +84,10 @@ Bad: qualifyLead, calculate-order-total Tells agents and workflows what the tool does and when to use it: ``` -Good: "Qualify a lead based on company size, industry, and budget. -Returns score 0-100 and tier (A/B/C)." +Good: "Check product inventory across all warehouses and calculate available stock. +Returns total quantity, location breakdown, and low stock alert status." -Bad: "Qualifies leads" +Bad: "Checks inventory" ``` The better the description, the better agents understand when to use it. @@ -136,7 +136,8 @@ deco CMS automatically generates a form based on your input schema. Fill in the **Via chat:** ``` -@YOUR_TOOL_NAME param1="value" param2=123 +@PRODUCT_INVENTORY_CHECK sku="SKU-12345" +@ORDER_CONFIRMATION_SEND customerEmail="customer@example.com" orderNumber="ORD-789" ``` Iterate until it works as expected. @@ -182,7 +183,8 @@ Once connected, any tools your custom app provides will automatically appear in Ask deco chat to make changes or edit TypeScript directly: ``` -Update CUSTOMER_FETCH to also return the customer's last order date +Update PRODUCT_INVENTORY_CHECK to also return the product's reorder threshold +Update ORDER_CONFIRMATION_SEND to include estimated delivery date ``` **Other actions:** @@ -197,9 +199,10 @@ Hover over any tool card and click **...** to: Organize related tools for easier discovery: **Examples:** -- **Customer Management** - `CUSTOMER_CREATE`, `CUSTOMER_FETCH`, `CUSTOMER_UPDATE`, `CUSTOMER_DELETE` -- **Email** - `EMAIL_SEND`, `EMAIL_VALIDATE`, `EMAIL_TEMPLATE_RENDER` -- **Billing** - `INVOICE_CREATE`, `PAYMENT_PROCESS`, `SUBSCRIPTION_UPDATE` +- **Customer Management** - `CUSTOMER_CREATE`, `CUSTOMER_FETCH`, `CUSTOMER_UPDATE`, `CUSTOMER_LOYALTY_UPDATE` +- **Order Processing** - `ORDER_CREATE`, `ORDER_UPDATE`, `ORDER_CANCEL`, `ORDER_REFUND` +- **Inventory** - `PRODUCT_INVENTORY_CHECK`, `INVENTORY_UPDATE`, `INVENTORY_ALERT_CREATE` +- **Notifications** - `ORDER_CONFIRMATION_SEND`, `SHIPPING_NOTIFICATION_SEND`, `CART_ABANDONED_SEND` ## Composition Principles @@ -207,10 +210,10 @@ Organize related tools for easier discovery: Don't build monolithic tools: ``` -❌ CUSTOMER_ONBOARD_AND_EMAIL_AND_SYNC +❌ ORDER_CREATE_AND_EMAIL_AND_UPDATE_INVENTORY_AND_NOTIFY -✅ CUSTOMER_CREATE → EMAIL_WELCOME_SEND → CRM_SYNC - (Three simple tools composed in a workflow) +✅ ORDER_CREATE → INVENTORY_UPDATE → ORDER_CONFIRMATION_SEND → ORDER_NOTIFICATION_SEND + (Four simple tools composed in a workflow) ``` ### Schemas Enable Automation From cf3bf3fe799e56177fc139d9f33b0418438339df Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 16:22:13 -0300 Subject: [PATCH 47/51] docs: add decopilot quickstart redesign plan Co-Authored-By: Claude Sonnet 4.5 --- ...026-02-10-decopilot-quickstart-redesign.md | 180 ++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 docs/plans/2026-02-10-decopilot-quickstart-redesign.md diff --git a/docs/plans/2026-02-10-decopilot-quickstart-redesign.md b/docs/plans/2026-02-10-decopilot-quickstart-redesign.md new file mode 100644 index 0000000000..f7ab67df36 --- /dev/null +++ b/docs/plans/2026-02-10-decopilot-quickstart-redesign.md @@ -0,0 +1,180 @@ +# Decopilot Quickstart Redesign - Design Document + +**Date:** 2026-02-10 +**Status:** Design Phase + +## Overview + +Redesign the decopilot quickstart guide to focus on practical usage for non-technical e-commerce teams (designers, content creators, project managers) rather than technical implementation details. Use progressive disclosure to introduce features naturally through real-world scenarios. + +## Target Audience + +- E-commerce team members with mixed backgrounds +- Roles: designers, content creators, project managers, merchandisers +- May not have programming experience +- Need to accomplish practical e-commerce tasks + +## Design Principles + +1. **Action-oriented** - Show what to ask for, not how it works internally +2. **Progressive complexity** - Start simple, gradually introduce advanced features +3. **Visual interactions** - Use ASCII art to show user/decopilot conversations +4. **Short sections** - Keep each section concise (150-200 words max) +5. **E-commerce context** - All examples relate to online retail operations + +## Content Structure + +### Section 1: Simple Requests + +**Purpose:** Show basic decopilot usage without any complexity + +**Examples:** +- Update product descriptions for a sale +- Check inventory levels +- Find products missing images + +**Key learning:** Just ask decopilot in natural language, get results back + +**Length:** ~150 words + 2-3 ASCII art examples + +--- + +### Section 2: Using Subtasks for Heavy Work + +**Purpose:** Introduce subtasks when work gets complex or generates lots of output + +**Examples:** +- Analyze stock ruptures across warehouses +- Research competitor pricing +- Audit product data quality + +**Key learning:** Use subtasks to keep main conversation clean, get back summaries + +**Length:** ~200 words + 1-2 ASCII art examples + +--- + +### Section 3: Working with Specialist Agents + +**Purpose:** Show how agents bring domain expertise to subtasks + +**Examples:** +- Inventory Specialist for demand forecasting +- Shipping Agent for logistics optimization +- Customer Service Agent for support strategy + +**Key learning:** Agents are specialists you can call on for focused tasks + +**Length:** ~200 words + 1-2 ASCII art examples + +--- + +### Section 4: Managing Context for Long Workflows + +**Purpose:** Introduce context management when working on multi-step projects + +**Examples:** +- Product launch preparation over multiple days +- When to use `/compact` command +- How subtasks help manage context + +**Key learning:** Keep conversations productive by managing context strategically + +**Length:** ~200 words + 1 ASCII art example + +--- + +### Section 5: Switching Scopes for Different Work + +**Purpose:** Show when to switch between organization/project/agent scopes + +**Examples:** +- Organization scope: Connect Shopify or set up integrations +- Project scope: Day-to-day feature development +- Agent scope: Specialized tasks with focused tools + +**Key learning:** Different scopes give you different capabilities + +**Length:** ~150 words + 1 ASCII art example + +--- + +### Closing: Putting It All Together + +**Purpose:** Quick recap and encourage exploration + +**Content:** +- Brief summary of progression +- Reminder to experiment +- Links to deeper documentation + +**Length:** ~100 words + +## ASCII Art Style + +Use simple box drawing and arrows to show conversation flow: + +``` +You → "Check inventory for SKU-123" + ↓ +Decopilot checks stock levels + ↓ +You ← "SKU-123: 47 units in stock + Last restock: Feb 8 + Reorder point: 20 units" +``` + +For multi-step or subtask flows: + +``` +You → "Run subtask: analyze stock ruptures" + ↓ +Subtask starts (isolated context) + ↓ +Analyzes 500 SKUs across 3 warehouses + ↓ +You ← Summary: "3 critical items need reorder: + - SKU-123: 8 units (reorder at 10) + - SKU-456: 5 units (reorder at 15) + - SKU-789: 2 units (reorder at 5)" +``` + +## Removed Content + +The following will be removed from the current quickstart: + +- All TypeScript code examples +- Internal implementation details (tool_enable, tool_search, etc.) +- Mermaid sequence diagrams showing tool calls +- Technical explanations of the agentic loop +- References to "defineTool()", "MeshContext", etc. + +These technical details remain in the Architecture and Tools documentation where they belong. + +## Links to Other Docs + +Each section will link to relevant deep-dive docs: + +- Section 2 → Tasks documentation +- Section 3 → Agents documentation +- Section 4 → Context documentation +- Section 5 → Scopes documentation + +## Success Criteria + +A successful redesign will: + +1. Be understandable by non-programmers +2. Show practical e-commerce use cases +3. Progressively introduce concepts +4. Use visual examples (ASCII art) +5. Keep sections short and scannable +6. Link to technical docs for those who want depth + +## Next Steps + +1. Write complete draft with all sections +2. Review ASCII art examples for clarity +3. Validate e-commerce examples are realistic +4. Ensure links to other docs are correct +5. Get user approval before implementation From 931e4edc4da36507ae0dd3963cb05f33bc105144 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 16:33:35 -0300 Subject: [PATCH 48/51] docs(quickstart): redesign decopilot quickstart for non-technical users MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete rewrite of the decopilot quickstart guide: - Progressive learning approach (simple → advanced) - Focus on practical e-commerce use cases - Removed technical implementation details - Added ASCII art conversation examples - Organized by progressive feature introduction: 1. Simple requests 2. Subtasks for heavy work 3. Specialist agents 4. Context management 5. Scope switching Target audience: e-commerce teams (designers, content creators, PMs) who need practical guidance without technical complexity. Co-Authored-By: Claude Sonnet 4.5 --- .../en/mcp-mesh/decopilot/quickstart.mdx | 871 ++++++++---------- 1 file changed, 367 insertions(+), 504 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx index c51c2f2a69..40c05852e4 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/quickstart.mdx @@ -1,605 +1,468 @@ --- title: Quick Start -description: Practical workflows showing decopilot's agentic loop in action +description: Learn how to work with decopilot through practical e-commerce examples icon: Rocket --- import Callout from "../../../../components/ui/Callout.astro"; -This guide shows practical decopilot workflows with the **agentic loop** in action. Each workflow demonstrates how decopilot gathers context from distributed MCP servers, takes coordinated actions, and verifies results—all while adapting based on scope. +This guide shows you how to use decopilot for common e-commerce tasks. We'll start simple and progressively introduce features like subtasks, agents, context management, and scopes as you need them. - -These workflows adapt based on scope (org/project/agent). Learn more in [Scopes](/en/mcp-mesh/decopilot/scopes). + +Each section builds on the previous one. Feel free to skip ahead if you're already familiar with basic concepts. ## Prerequisites Before starting, you'll need: -- **Access to a deco CMS organization**: With permission to create and modify projects -- **At least one project with connected MCP servers**: GitHub is recommended for these examples -- **Basic MCP familiarity**: Understanding of tools, resources, and the MCP protocol helps but isn't required +- **Access to a deco CMS organization** with at least one project +- **Connected integrations** like Shopify, GitHub, or other MCP servers (recommended but not required) +- **Basic familiarity** with your e-commerce platform -If you haven't set up MCP servers yet, see [Connections](/en/mcp-mesh/connections). +If you haven't set up integrations yet, see [Connections](/en/mcp-mesh/connections). -## Workflow 1: Creating a Pull Request +## 1. Simple Requests -This workflow shows the complete agentic loop with an external MCP server (GitHub). +Just ask decopilot for what you need in natural language. Behind the scenes, decopilot follows a three-step flow: -### The Request +1. **Search** - Discovers what tools are available for your request +2. **Enable** - Activates the specific tools it needs +3. **Execute** - Uses those tools to accomplish your task -You're working in a project and ready to create a pull request for your feature: +You don't need to tell decopilot which tools to use—it figures this out automatically based on what you ask for. + +### Example: Check Inventory ``` -User: "Create a PR for the authentication feature" +You → "Check inventory levels for products below 20 units" + ↓ +Decopilot searches for inventory tools + ↓ +Decopilot enables inventory tools + ↓ +Decopilot queries your inventory system + ↓ +You ← "Found 8 products with low stock: + • SKU-2847: 12 units (Wireless Headphones) + • SKU-1923: 8 units (Phone Case - Black) + • SKU-4156: 15 units (Laptop Stand) + • SKU-3891: 5 units (USB-C Cable 2m) + • SKU-5672: 18 units (Water Bottle) + • SKU-7234: 9 units (Desk Lamp) + • SKU-8901: 14 units (Keyboard - Mechanical) + • SKU-4523: 7 units (Mouse Pad - Large)" ``` -### Step 1: Gather Context - -Decopilot begins by gathering context from the GitHub MCP: - -```typescript -// Decopilot internally: -// 1. Check current branch state -const branch = await GIT_BRANCH_STATUS({ repo: "mobile-app" }) -// => { name: "feature/biometric-auth", ahead: 5, behind: 0 } +Decopilot automatically discovers and enables the tools it needs—you don't have to tell it which tools to use. -// 2. Review recent commits -const commits = await GIT_LOG({ repo: "mobile-app", limit: 5 }) -// => [ -// { sha: "abc123", message: "Add biometric scanner component" }, -// { sha: "def456", message: "Implement face recognition flow" }, -// ... -// ] +### Example: Update Product Descriptions -// 3. Check for uncommitted changes -const status = await GIT_STATUS({ repo: "mobile-app" }) -// => { modified: [], staged: [], untracked: [] } ``` - -**Learning point**: Decopilot queries the GitHub MCP to understand the current state before taking action. This ensures the PR creation is context-aware. - -### Step 2: Take Action - -With context gathered, decopilot searches for and enables the appropriate tool: - -```typescript -// 1. Search for GitHub tools related to PRs -const tools = await tools_search({ - search_term: "pull request github", - scope: "project" -}) -// => [ -// { name: "CREATE_PR", description: "Create a pull request on GitHub" }, -// { name: "UPDATE_PR", description: "Update existing pull request" }, -// ... -// ] - -// 2. Enable the CREATE_PR tool -await tool_enable({ tool_name: "CREATE_PR" }) - -// 3. Create PR with context-aware description -await CREATE_PR({ - repo: "mobile-app", - title: "Add biometric authentication", - body: `## Summary -- Implemented biometric scanner component -- Added face recognition flow -- Integrated with iOS/Android APIs - -## Testing -- Tested on iPhone 14 Pro with Face ID -- Tested on Pixel 7 with fingerprint scanner`, - base: "main", - head: "feature/biometric-auth" -}) +You → "Update descriptions for the summer collection + to emphasize breathable fabrics and UV protection" + ↓ +Decopilot searches for product management tools + ↓ +Decopilot enables needed tools + ↓ +Decopilot identifies summer collection products + ↓ +Decopilot updates 24 product descriptions + ↓ +You ← "Updated 24 products in Summer 2026 collection: + ✓ Added 'breathable fabric' mentions + ✓ Highlighted UPF 50+ sun protection + ✓ Emphasized lightweight materials + + Preview: example.com/products/summer-dress-azure" ``` -**Learning point**: The discover → enable → use pattern is fundamental to decopilot's tool workflow. Tools from external MCPs must be enabled before use. - -### Step 3: Verify Results +### Example: Find Missing Content -Decopilot confirms the PR was created successfully: - -```typescript -// Check PR creation result -// => { -// success: true, -// pr_number: 142, -// url: "https://github.com/org/mobile-app/pull/142" -// } - -// Report to user -"✓ Created PR #142: Add biometric authentication - View: https://github.com/org/mobile-app/pull/142" +``` +You → "Find products missing images or descriptions" + ↓ +Decopilot searches for content audit tools + ↓ +Decopilot enables tools and scans catalog + ↓ +You ← "Found 12 products with missing content: + + Missing images (5): + • SKU-8821: Ceramic Mug Set + • SKU-9234: Garden Tool Kit + • SKU-7755: Yoga Mat - Purple + • SKU-6543: Plant Hanger - Macrame + • SKU-8192: Candle - Lavender + + Missing descriptions (7): + • SKU-3421: Travel Backpack + • SKU-5667: Stainless Steel Thermos + • SKU-2198: Notebook - Dotted + • SKU-4456: Pen Set - Gel + • SKU-9981: Desk Organizer + • SKU-7722: Wall Clock - Wooden + • SKU-3388: Picture Frame - 8x10" ``` -**Learning point**: The agentic loop doesn't stop at execution—decopilot verifies success and reports meaningful results. - -### The Complete Loop - -```mermaid -sequenceDiagram - participant User - participant Decopilot - participant GitHub_MCP - - User->>Decopilot: "Create a PR for the auth feature" - - Note over Decopilot: GATHER CONTEXT - Decopilot->>GitHub_MCP: GIT_BRANCH_STATUS - GitHub_MCP-->>Decopilot: feature/biometric-auth (5 commits ahead) - Decopilot->>GitHub_MCP: GIT_LOG - GitHub_MCP-->>Decopilot: Recent commits - Decopilot->>GitHub_MCP: GIT_STATUS - GitHub_MCP-->>Decopilot: No uncommitted changes +**Key takeaway:** For straightforward tasks, just describe what you want. Decopilot automatically discovers and enables the right tools, then executes your request. - Note over Decopilot: TAKE ACTION - Decopilot->>Decopilot: tools_search("pull request") - Decopilot->>Decopilot: tool_enable("CREATE_PR") - Decopilot->>GitHub_MCP: CREATE_PR(...) - GitHub_MCP-->>Decopilot: PR #142 created +--- - Note over Decopilot: VERIFY RESULTS - Decopilot-->>User: ✓ Created PR #142 (link) -``` +## 2. Using Subtasks for Heavy Work -## Workflow 2: Spawning a Security Review Agent +When tasks involve analyzing lots of data or doing complex research, use **subtasks**. Subtasks run in isolated context and return just a summary—keeping your main conversation clean and focused. -This workflow demonstrates agent spawning for parallel work with isolated context. +### When to Use Subtasks -### The Request +- Analyzing data across many products or orders +- Research tasks (competitor pricing, trend analysis) +- Quality audits (checking data consistency, finding errors) +- Any work that generates verbose output you don't need to see in full -You're implementing a feature and want security review to happen in parallel: +### Example: Analyze Stock Ruptures ``` -User: "Add biometric authentication and run security review" +You → "Run a subtask to analyze potential stock ruptures + across all warehouses for the next 30 days" + ↓ +Subtask starts with fresh context + ↓ +Subtask searches for inventory & analytics tools + ↓ +Subtask enables needed tools + ↓ +Subtask analyzes: + • 547 SKUs across 3 warehouses + • Historical sales data + • Seasonal trends + • Supplier lead times + ↓ +You ← "Stock Rupture Analysis Complete + + CRITICAL (need immediate action): + • SKU-2847 Wireless Headphones + Current: 12 units | Projected shortage: Feb 18 + Recommendation: Order 200 units from Supplier A + + • SKU-7234 Desk Lamp + Current: 9 units | Projected shortage: Feb 15 + Recommendation: Order 150 units from Supplier B + + HIGH PRIORITY (order within 1 week): + • SKU-8901 Mechanical Keyboard - 14 units + • SKU-4156 Laptop Stand - 15 units + • SKU-1923 Phone Case Black - 8 units + + MODERATE (monitor closely): + • 8 additional SKUs flagged + + Full analysis saved to subtask history." ``` -### Main Loop: Implementation - -Decopilot begins implementation in the main context: - -```typescript -// Main decopilot loop -// 1. Plan implementation approach -const plan = await resource_read("project://mobile-app/architecture-decisions", { - lineStart: 0, - lineEnd: 0 -}) - -// 2. Check existing auth infrastructure -const authFiles = await tools_search({ - search_term: "authentication", - scope: "project" -}) - -// 3. Spawn security agent on parallel task -const agentTask = await agent_spawn({ - agent_id: "security-reviewer", - task: "Review biometric authentication implementation for security vulnerabilities", - context: { - files: ["src/auth/biometric.ts", "src/auth/face-recognition.ts"], - focus: "authentication security" - } -}) -// => { task_id: "task-abc123", status: "in_progress" } -``` +### Example: Research Competitor Pricing -**Learning point**: Agent spawning happens early in the workflow, allowing parallel execution while the main loop continues. - -### Spawned Agent: Security Review - -The spawned agent runs with **fresh context**, isolated from the main loop: - -```typescript -// Inside security-reviewer agent (isolated context) -// Agent has bounded tool access: security scanning, CVE lookup, file reading - -// 1. Gather context - read security checklist -const checklist = await resource_read("agent://security-reviewer/checklist", { - lineStart: 0, - lineEnd: 0 -}) - -// 2. Take action - scan authentication files -const scanResults = await SECURITY_SCAN({ - files: ["src/auth/biometric.ts", "src/auth/face-recognition.ts"], - rules: ["auth", "crypto", "input-validation"] -}) - -// 3. Check known vulnerabilities -const cveResults = await CVE_LOOKUP({ - dependencies: ["face-api.js", "biometric-sdk"] -}) - -// 4. Generate findings report -const findings = { - critical: [], - high: [ - "Biometric templates stored without encryption", - "Face recognition threshold too permissive (0.5)" - ], - medium: [ - "Missing rate limiting on auth attempts" - ], - info: [ - "Consider implementing liveness detection" - ] -} - -// Agent completes and returns findings -return { status: "completed", findings } ``` - -**Learning point**: The agent operates in an isolated context with only the tools it needs. This prevents token bloat and enables focused analysis. - -### Main Loop: Integration - -Back in the main loop, decopilot integrates the findings: - -```typescript -// Main loop continues -// 1. Complete implementation -await tool_enable({ tool_name: "CREATE_FILE" }) -await CREATE_FILE({ - path: "src/auth/biometric.ts", - content: "// Implementation..." -}) - -// 2. Check agent task status -const agentResult = await agent_task_status({ task_id: "task-abc123" }) -// => { status: "completed", findings: { ... } } - -// 3. Update implementation based on findings -await tool_enable({ tool_name: "UPDATE_FILE" }) -await UPDATE_FILE({ - path: "src/auth/biometric.ts", - changes: [ - "Encrypt biometric templates with AES-256", - "Increase face recognition threshold to 0.7", - "Add rate limiting middleware" - ] -}) - -// 4. Create resource documenting findings -await resource_create({ - uri: "project://mobile-app/security-findings-2024-02", - name: "Security Review: Biometric Auth", - content: JSON.stringify(agentResult.findings, null, 2) -}) +You → "Run a subtask: research competitor pricing + for our top 20 bestselling products" + ↓ +Subtask searches for web research & pricing tools + ↓ +Subtask enables tools and analyzes competitor sites + ↓ +You ← "Pricing Analysis Summary: + + OVERPRICED (consider reducing): + • Wireless Headphones: Our $79 vs avg $65 + • Laptop Stand: Our $45 vs avg $35 + + COMPETITIVE (maintain): + • Phone Cases: Our $18 vs avg $17 + • USB Cables: Our $12 vs avg $13 + + UNDERPRICED (opportunity to increase): + • Mechanical Keyboard: Our $89 vs avg $110 + • Desk Lamp: Our $32 vs avg $42 + + Full competitor breakdown in subtask history." ``` -**Learning point**: The main loop continues working while the agent runs, then integrates results when ready. This is efficient parallel execution. +**Key takeaway:** Use subtasks when you need analysis or research but only want to see the actionable summary. The full details are saved in task history if you need them later. -### The Complete Flow +Learn more: [Tasks & Subtasks](/en/mcp-mesh/decopilot/tasks-and-spawning) -```mermaid -graph TB - A[User Request] --> B[Main Loop: Plan Implementation] - B --> C[Spawn Security Agent] - B --> D[Continue Implementation] +--- - C --> E[Agent: Fresh Context] - E --> F[Agent: Scan Files] - F --> G[Agent: Check CVEs] - G --> H[Agent: Generate Findings] +## 3. Working with Specialist Agents - D --> I[Main: Complete Implementation] - H --> J[Main: Integrate Findings] - I --> J - J --> K[Main: Update Code] - K --> L[Main: Document Results] -``` +**Agents** are specialists with focused expertise in specific domains. When you need specialized analysis or domain knowledge, use an agent—they run in subtasks with tools and instructions tailored to their area. -## Workflow 3: Multi-Server Orchestration +### Available Agent Types -This workflow shows coordination across multiple MCP servers in a single operation. +Common agents for e-commerce teams: +- **Inventory Specialist** - Demand forecasting, stock optimization, supplier coordination +- **Shipping & Logistics** - Route optimization, carrier selection, delivery scheduling +- **Customer Service** - Support strategy, communication planning, issue resolution +- **Content Specialist** - SEO optimization, copy refinement, brand consistency +- **Pricing Analyst** - Market analysis, competitive positioning, promotion strategy -### The Request - -You need to set up a feature branch across multiple services: +### Example: Demand Forecasting ``` -User: "Create feature branch, export Figma assets, and notify the team" +You → "Use the Inventory Specialist to forecast + demand for winter collection launch" + ↓ +Decopilot searches for agents + ↓ +Decopilot → "Found 2 agents: + • Inventory Specialist (recommended) + • Supply Chain Analyst + + Which would you prefer?" + ↓ +You → "Inventory Specialist" + ↓ +Agent spawns in subtask with specialized scope + ↓ +Agent searches for forecasting & inventory tools + ↓ +Agent enables domain-specific tools + ↓ +Agent analyzes with specialized expertise + ↓ +You ← "Winter Collection Demand Forecast + + HIGH DEMAND (stock heavily): + • Wool Scarves: 850-1100 units + • Insulated Boots: 650-800 units + • Fleece Jackets: 920-1200 units + + MODERATE DEMAND: + • Winter Gloves: 400-550 units + • Thermal Leggings: 350-480 units + + STRATEGY RECOMMENDATIONS: + ✓ Order 70% of forecasted volume upfront + ✓ Schedule second shipment for mid-season + ✓ Monitor sell-through weekly + ✓ Plan flash sales if inventory exceeds 40% after Week 4 + + Detailed forecast model in agent task history." ``` -### The Agentic Loop - -Decopilot orchestrates across three MCP servers: - -```typescript -// GATHER CONTEXT - -// 1. Check GitHub repository state -const repo = await GIT_BRANCH_STATUS({ repo: "mobile-app" }) -// => { name: "main", clean: true } - -// 2. Check Figma for latest designs -const figmaFile = await FIGMA_GET_FILE({ file_id: "mobile-app-designs" }) -// => { last_modified: "2024-02-08", version: "1.42" } - -// 3. Check Slack channel for previous notifications -const history = await SLACK_GET_HISTORY({ - channel: "engineering", - limit: 10 -}) -// => [...recent messages] - -// TAKE ACTION - -// 1. GitHub MCP - Create feature branch -await tool_enable({ tool_name: "CREATE_BRANCH" }) -const branch = await CREATE_BRANCH({ - repo: "mobile-app", - name: "feature/new-onboarding", - base: "main" -}) -// => { success: true, branch: "feature/new-onboarding" } - -// 2. Figma MCP - Export design assets -await tool_enable({ tool_name: "EXPORT_ASSETS" }) -const assets = await EXPORT_ASSETS({ - file_id: "mobile-app-designs", - node_ids: ["onboarding-flow", "welcome-screen"], - format: "svg", - scale: 2 -}) -// => { -// success: true, -// files: [ -// { name: "onboarding-flow.svg", url: "..." }, -// { name: "welcome-screen.svg", url: "..." } -// ] -// } - -// 3. Slack MCP - Notify team -await tool_enable({ tool_name: "SEND_MESSAGE" }) -const notification = await SEND_MESSAGE({ - channel: "engineering", - text: `🚀 Started new onboarding feature -Branch: feature/new-onboarding -Figma assets: ${assets.files.length} files exported -Design version: 1.42` -}) -// => { success: true, timestamp: "1707398400" } - -// VERIFY RESULTS - -// Confirm all operations succeeded -const results = { - github: branch.success, // ✓ - figma: assets.success, // ✓ - slack: notification.success // ✓ -} - -// Report to user -"✓ Feature setup complete: - • Branch created: feature/new-onboarding - • Exported 2 Figma assets - • Team notified in #engineering" +### Example: Shipping Optimization + +``` +You → "Use Shipping Agent to optimize delivery + routes for holiday orders" + ↓ +Agent spawns with logistics & shipping scope + ↓ +Agent searches for routing & carrier tools + ↓ +Agent enables specialized logistics tools + ↓ +Agent analyzes delivery optimization + ↓ +You ← "Holiday Shipping Strategy + + ROUTE OPTIMIZATION: + • West Coast: Use Carrier A (2-day) - saves $3.20/order + • East Coast: Use Carrier B (priority) - saves $1.80/order + • Midwest: Split between A & B based on weight + + COST SAVINGS: $8,400/month projected + + CARRIER RECOMMENDATIONS: + ✓ Negotiate volume discount with Carrier A (15%) + ✓ Set up weekend pickups with Carrier B + ✓ Reserve backup capacity with Carrier C for peak days + + Implementation plan in agent history." ``` -**Learning point**: Decopilot coordinates multiple MCP servers in a single workflow. Each server is called through the MCP protocol (HTTP for remote, stdio for local), with decopilot orchestrating the sequence. +**Key takeaway:** Agents bring specialized knowledge to complex tasks. They analyze with domain expertise and return strategic recommendations. -### Distributed Architecture in Action +Learn more: [Agents](/en/mcp-mesh/agents) -```mermaid -graph LR - Decopilot --> GitHub[GitHub MCP
    HTTP] - Decopilot --> Figma[Figma MCP
    HTTP] - Decopilot --> Slack[Slack MCP
    HTTP] +--- - GitHub --> Branch[Create Branch] - Figma --> Assets[Export Assets] - Slack --> Notify[Send Message] -``` +## 4. Managing Context for Long Workflows -**Learning point**: This is the distributed MCP architecture in action—web-native coordination across multiple services through standardized protocol. +When working on complex projects over multiple days, **context** matters. Your conversation history uses working memory—keeping it clean helps decopilot stay focused and productive. -## Workflow 4: Dynamic Tool Creation +### The 40/80 Rule -This workflow demonstrates decopilot's ability to edit virtual MCPs by creating tools on the fly. +- **Below 40%** - Plenty of room, work freely +- **40-80%** - Context filling up, consider compacting +- **Above 80%** - Automatic compactification triggers -### The Request +### When to Compact -You need a custom tool for a project-specific operation: +Use the `/compact` command to summarize your conversation before: +- Starting a major new project phase +- Beginning complex multi-step work +- Switching between different focus areas + +### Example: Product Launch Preparation ``` -User: "We need a tool to run the mobile test suite on all platforms" +Day 1: +You → "Let's plan the Spring Collection launch" + ↓ +[Discussion of strategy, timeline, SKUs...] + ↓ +Context: 25% full + ↓ + ↓ +Day 2: +You → "Run /compact" + ↓ +Decopilot summarizes previous work + ↓ +Context: 15% full (compacted) + ↓ +You → "Now create launch announcement content" + ↓ +[Fresh context for new phase...] ``` -### The Agentic Loop - -Decopilot operates on the project's virtual MCP to create an inline tool: - -```typescript -// GATHER CONTEXT - -// 1. Check existing test infrastructure -const testTools = await tools_search({ - search_term: "test", - scope: "project" -}) -// => [ -// { name: "RUN_TESTS", description: "Run test suite for a platform" }, -// { name: "TEST_RESULTS", description: "Get test results" } -// ] - -// 2. Read project testing documentation -const testDocs = await resource_read("project://mobile-app/testing-guide", { - lineStart: 0, - lineEnd: 0 -}) - -// TAKE ACTION - -// 1. Create inline tool in project virtual MCP -await tool_create({ - name: "RUN_MOBILE_TESTS_ALL_PLATFORMS", - description: "Run complete mobile test suite on iOS and Android", - inputSchema: { - type: "object", - properties: { - suite: { - type: "string", - enum: ["unit", "integration", "e2e", "all"], - description: "Test suite to run" - } - } - }, - implementation: { - type: "workflow", - steps: [ - { - tool: "RUN_TESTS", - input: { platform: "ios", suite: "{{input.suite}}" } - }, - { - tool: "RUN_TESTS", - input: { platform: "android", suite: "{{input.suite}}" } - } - ] - } -}) - -// 2. Enable the newly created tool -await tool_enable({ tool_name: "RUN_MOBILE_TESTS_ALL_PLATFORMS" }) - -// 3. Use it immediately -const results = await RUN_MOBILE_TESTS_ALL_PLATFORMS({ - suite: "integration" -}) -// => { -// ios: { passed: 142, failed: 0, skipped: 3 }, -// android: { passed: 138, failed: 2, skipped: 7 } -// } - -// VERIFY RESULTS - -// Check test outcomes -const summary = { - ios: results.ios.failed === 0 ? "✓ Pass" : "✗ Fail", - android: results.android.failed === 0 ? "✓ Pass" : "✗ Fail" -} - -// Report to user -"✓ Created RUN_MOBILE_TESTS_ALL_PLATFORMS tool - Results: - • iOS: ✓ Pass (142/145 tests) - • Android: ✗ Fail (138/147 tests, 2 failures)" -``` +### Using Subtasks to Manage Context -**Learning point**: Decopilot can create tools in virtual MCPs and use them immediately. This is only possible because projects are virtual MCPs—editable and configurable. +Remember: Subtasks keep your main conversation lean. When you spawn a subtask for analysis, only the summary comes back—not the detailed work. -### Virtual MCP Editability +``` +You → "Run subtask: audit product data quality + across entire catalog" + ↓ +Subtask analyzes 1,200 products +(generates 15,000 tokens of detailed findings) + ↓ +You ← "Quality Audit Summary (450 tokens) + + CRITICAL ISSUES: 23 products + HIGH PRIORITY: 87 products + MEDIUM PRIORITY: 156 products + PASSED: 934 products + + [Summary of top issues...]" +``` -```mermaid -graph TB - A[User Request] --> B[Gather: Check Existing Tools] - B --> C[Take Action: Create Inline Tool] - C --> D[Virtual MCP: Add Tool Definition] - D --> E[Enable Tool] - E --> F[Use Tool Immediately] - F --> G[Verify: Check Results] +The subtask used 15,000 tokens of context—but your main conversation only sees 450 tokens. This keeps your working memory focused on what matters. - style D fill:#e1f5ff -``` +**Key takeaway:** Use `/compact` before major work phases, and use subtasks to keep detailed work isolated. This maintains conversation quality and productivity. -**Learning point**: The virtual MCP is the editable layer. Decopilot operates on it to add tools, resources, and configuration—something impossible with external MCP servers. +Learn more: [Context Management](/en/mcp-mesh/decopilot/context) -## Tips for Effective Use +--- -### 1. Leverage Scopes Appropriately +## 5. Switching Scopes for Different Work -**Org scope** for organization-wide setup: -- Connect external MCP servers (GitHub org, Slack workspace) -- Create shared resources (security policies, coding standards) -- Define org-level prompt templates +**Scopes** determine what tools and resources are available. Switch scopes based on what you're working on. -**Project scope** for feature development: -- Use project-specific tools and resources -- Create inline tools for project operations -- Coordinate work across connected MCPs +### Three Scope Types -**Agent scope** for focused tasks: -- Delegate to specialized agents (security, testing, research) -- Benefit from fresh context and bounded tool access +**Organization Scope** +- Setting up integrations (Shopify, GitHub, Slack) +- Managing team access and permissions +- Organization-wide configurations -### 2. Spawn Agents Strategically +**Project Scope** +- Day-to-day feature work +- Product management +- Content updates and campaigns -**Good candidates for agent spawning**: -- Security reviews (parallel to implementation) -- Research tasks (exploring architecture, investigating bugs) -- Testing workflows (comprehensive test runs) -- Code quality checks (linting, formatting, documentation) +**Agent Scope** +- Specialized tasks with focused tools +- Domain expertise (inventory, shipping, etc.) +- Isolated analysis work -**Keep in main loop**: -- Feature implementation (needs full context) -- User interactions (requires responsiveness) -- Sequential workflows (where order matters) +### How to Switch Scopes -### 3. Work with Virtual MCPs +Use the **agent selector** at the bottom-left of the chat: +- No agent selected = Organization or Project scope (depends on current view) +- Agent selected = Agent scope -**Create resources** for documentation: -```typescript -await resource_create({ - uri: "project://mobile-app/architecture-decisions", - name: "Architecture Decisions", - content: "# ADRs\n\n..." -}) +### Example: Multi-Scope Workflow -// Read back the resource -await resource_read("project://mobile-app/architecture-decisions", { - lineStart: 0, - lineEnd: 0 -}) ``` - -**Create inline tools** for project operations: -```typescript -await tool_create({ - name: "DEPLOY_STAGING", - description: "Deploy to staging environment", - // ... -}) +Organization Scope (no agent): +You → "Connect our Shopify store to decopilot" + ↓ +Decopilot searches for connection tools + ↓ +Decopilot enables OAuth tools + ↓ +Decopilot guides through OAuth setup + ↓ +You ← "✓ Shopify connected successfully + Store: mystore.myshopify.com + Products: 1,247 available" + ↓ + ↓ +Switch to Project Scope (navigate to project): +You → "Update all summer products with new descriptions" + ↓ +Decopilot searches project-specific tools + ↓ +Decopilot enables product management tools + ↓ +Decopilot updates products + ↓ +You ← "✓ Updated 24 products in Summer 2026 collection" + ↓ + ↓ +Switch to Agent Scope (select Inventory Specialist): +You → "Analyze demand for these summer products" + ↓ +Agent searches specialized inventory tools + ↓ +Agent enables forecasting tools + ↓ +Agent analyzes demand + ↓ +You ← "Demand Forecast: [specialist analysis...]" ``` -**Update prompts** based on workflow patterns: -```typescript -await prompt_update({ - name: "code-review", - template: "Review this code for:\n- Security\n- Performance\n..." -}) -``` +**Key takeaway:** Switch scopes based on your task. Organization for setup, project for daily work, agents for specialized analysis. -### 4. Monitor Task Status +Learn more: [Scopes](/en/mcp-mesh/decopilot/scopes) -When spawning agents, check status: -```typescript -const status = await agent_task_status({ task_id: "task-abc123" }) -// => { status: "in_progress" | "completed" | "failed" } -``` +--- -Integrate results when ready: -```typescript -if (status.status === "completed") { - // Use agent findings -} -``` +## Putting It All Together + +You've learned the core decopilot workflow: -## Next Steps +1. **Simple requests** - Just ask for what you need +2. **Subtasks** - Isolate complex work, get back summaries +3. **Agents** - Bring in specialists for domain expertise +4. **Context** - Use `/compact` and subtasks to stay focused +5. **Scopes** - Switch contexts for different types of work -**[Scopes](/en/mcp-mesh/decopilot/scopes)**: Understand how org/project/agent scopes determine behavior and tool availability. Essential for effective decopilot use. +### Quick Reference -**[Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning)**: Learn advanced patterns for agent spawning, including fan-out/fan-in, conditional spawning, and agent selection. +**When to use what:** +- Basic task → Just ask decopilot +- Complex analysis → Run a subtask +- Need expertise → Use a specialist agent +- Long project → Compact regularly, use subtasks +- Setup work → Organization scope +- Daily work → Project scope +- Specialized task → Agent scope -**[Tools](/en/mcp-mesh/decopilot/tools)**: Explore the comprehensive toolset, discover patterns, and troubleshoot common issues. +### Start Experimenting -**[Context](/en/mcp-mesh/decopilot/context)**: Optimize token usage through strategic agent spawning and context filtering. +The best way to learn is to try. Start with simple requests, then progressively use subtasks and agents as your needs grow more complex. -**[Architecture](/en/mcp-mesh/decopilot/architecture)**: Deep-dive into decopilot's technical implementation and distributed MCP coordination. +**Next steps:** +- [Tools](/en/mcp-mesh/decopilot/tools) - See what decopilot can do +- [Tasks](/en/mcp-mesh/decopilot/tasks-and-spawning) - Deep dive into subtasks +- [Context](/en/mcp-mesh/decopilot/context) - Optimize your workflow +- [Agents](/en/mcp-mesh/agents) - Learn about specialists +- [Architecture](/en/mcp-mesh/decopilot/architecture) - Technical details --- -You've seen the agentic loop in action across four practical workflows. Decopilot brings proven agentic patterns to web-based development through distributed MCP architecture—gather context, take coordinated actions, and verify results, all while adapting to scope. This is the foundation for state-of-the-art agentic workflows in deco CMS. +Ready to dive in? Open decopilot in your deco CMS organization and start with a simple request. The agentic harness will guide you from there. From 06716ef2fb2c4be2acabe6f64db787c994450452 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 16:33:39 -0300 Subject: [PATCH 49/51] docs(decopilot): update examples to use e-commerce scenarios Update decopilot documentation examples: - overview.mdx: Replace GitHub/Figma/Slack with Shopify/inventory/customer service - tools.mdx: Update scope tools examples to use e-commerce integrations - virtual-mcps.mdx: Change examples from GitHub connections to Shopify/ShipStation Examples now focus on order fulfillment, inventory management, and customer service workflows instead of software development tasks. Co-Authored-By: Claude Sonnet 4.5 --- .../en/mcp-mesh/decopilot/overview.mdx | 8 ++++---- .../content/en/mcp-mesh/decopilot/tools.mdx | 12 +++++------ .../src/content/en/mcp-mesh/virtual-mcps.mdx | 20 +++++++++---------- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx index b70cea051b..2562d91499 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/overview.mdx @@ -12,7 +12,7 @@ import Callout from "../../../../components/ui/Callout.astro"; ## What is decopilot? -**decopilot** is an agentic AI assistant that orchestrates work across your entire stack—from GitHub and Figma to Google Sheets, email, Slack, and custom services. Unlike traditional AI assistants confined to code editors, decopilot operates through the Model Context Protocol, giving it reach into the productive applications where real work happens. +**decopilot** is an agentic AI assistant that orchestrates work across your entire stack—from Shopify and inventory systems to email, customer service platforms, and custom services. Unlike traditional AI assistants confined to code editors, decopilot operates through the Model Context Protocol, giving it reach into the productive applications where real work happens. You interact through a **chat interface**. Start a conversation, and decopilot works autonomously in the background. Continue with other tasks—when decopilot needs your input, you'll receive a notification. This human-in-the-loop design keeps you in control while letting AI handle coordination across multiple services. @@ -26,14 +26,14 @@ Start with the [Quick Start](/en/mcp-mesh/decopilot/quickstart) guide to see dec Decopilot follows the same proven agentic loop pattern as [Claude Code](https://code.claude.com/docs/en/how-claude-code-works#the-agentic-loop): **gather context → take action → verify results**. This cycle runs continuously as you work, with decopilot adapting based on what it learns. -The key difference is where this loop operates. While Claude Code works with local filesystems and terminal commands, decopilot orchestrates **distributed MCP servers** over HTTP. Instead of reading local files, decopilot queries GitHub, Figma, Slack, databases, and your custom MCP servers—all through standardized MCP protocol. +The key difference is where this loop operates. While Claude Code works with local filesystems and terminal commands, decopilot orchestrates **distributed MCP servers** over HTTP. Instead of reading local files, decopilot queries Shopify, inventory systems, customer service platforms, databases, and your custom MCP servers—all through standardized MCP protocol. Each phase uses MCP tools: - **Gather context**: Read from connected MCP servers to understand current state - **Take action**: Execute tools across multiple services in a coordinated workflow - **Verify results**: Check outcomes, spawn specialized agents for review, adapt approach -The distributed nature means decopilot can orchestrate complex workflows spanning multiple services in a single loop—creating branches in GitHub, exporting assets from Figma, and notifying teams in Slack, all while operating on editable virtual MCPs. +The distributed nature means decopilot can orchestrate complex workflows spanning multiple services in a single loop—processing orders in Shopify, managing inventory across warehouses, and sending customer notifications, all while operating on editable virtual MCPs. ## Models @@ -99,7 +99,7 @@ Decopilot comes with built-in tools that enable meta-level operations: - **`resource_read` / `resource_edit`**: Manage project documentation and resources - **`prompt_read` / `prompt_edit`**: Create reusable prompt templates -These built-in tools are always available and provide the foundation for working with virtual MCPs. Beyond these, you discover and enable tools from your connected MCP servers (GitHub, Figma, Slack, etc.) as needed. +These built-in tools are always available and provide the foundation for working with virtual MCPs. Beyond these, you discover and enable tools from your connected MCP servers (Shopify, inventory systems, customer service platforms, etc.) as needed. See [Tools](/en/mcp-mesh/decopilot/tools) for complete specifications, usage patterns, and examples of coordinating tools across multiple services. diff --git a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx index c26be66be3..3ca310f369 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/decopilot/tools.mdx @@ -35,13 +35,13 @@ All built-in tools are available across all scopes. Availability varies between ### Scope Tools -Scope tools come from the current scope—domain-specific capabilities like GitHub, Slack, or deployment tools. These are discovered via `tool_search` and enabled via `tool_enable`. +Scope tools come from the current scope—domain-specific capabilities like Shopify, inventory systems, or shipping tools. These are discovered via `tool_search` and enabled via `tool_enable`. -**Example**: A project with GitHub and Slack connections might expose: -- `CREATE_PR` - Create a pull request -- `CREATE_BRANCH` - Create a git branch -- `SEND_MESSAGE` - Send a Slack message -- `LIST_ISSUES` - List GitHub issues +**Example**: A project with Shopify and ShipStation connections might expose: +- `GET_ORDERS` - Fetch customer orders +- `UPDATE_INVENTORY` - Update product stock levels +- `CREATE_SHIPPING_LABEL` - Generate shipping labels +- `GET_PRODUCTS` - List product catalog Scope tool availability in tasks vs subtasks depends on the tool's configuration. diff --git a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx index efe71420fa..b6fa334cb2 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/virtual-mcps.mdx @@ -13,7 +13,7 @@ In deco CMS, a **Virtual MCP** is a reusable package of capabilities—[tools, r Instead of giving your AI agent access to everything from every connection, you **compose virtual MCPs** that expose exactly what's needed for each use case. You can: - **Remix connections**: Select specific tools and context from each connection -- **Combine multiple sources**: Package GitHub + Slack + databases into one unified MCP +- **Combine multiple sources**: Package Shopify + inventory systems + databases into one unified MCP - **Add custom logic**: Extend with inline tools, prompts, and resources - **Update dynamically**: Change what's included without reconfiguring your agents @@ -36,7 +36,7 @@ A **connection** is how you wire up an external MCP server to deco CMS (see [Con **Example**: An "order-fulfillment-ops" virtual MCP might remix: - **Shopify connection**: Order management tools + product catalog - **ShipStation connection**: Shipping label generation and tracking tools -- **Slack connection**: Fulfillment team notification tools +- **Email provider connection**: Order confirmation and shipping notification tools Your AI agent uses this one virtual MCP to orchestrate the entire order fulfillment process across all three systems. @@ -65,7 +65,7 @@ Inline tools are ideal for **feature gating**—wrapping connection tools with v Inline tools can coordinate multiple connections in a single operation. -**Example**: An order fulfillment tool that checks inventory (warehouse connection), creates a shipping label (ShipStation connection), sends order confirmation (SendGrid connection), and notifies the fulfillment team (Slack connection)—all in one coordinated workflow. +**Example**: An order fulfillment tool that checks inventory (warehouse connection), creates a shipping label (ShipStation connection), sends order confirmation (SendGrid connection), and updates order status (Shopify connection)—all in one coordinated workflow. These patterns enable **authorization enforcement**, **input validation**, **audit logging** (see [Monitoring](/en/mcp-mesh/monitoring)), and **workflow orchestration** across your MCP infrastructure. @@ -92,9 +92,9 @@ Tools and prompts use the format: `connection_id::CAPABILITY_NAME` - **Namespace separator**: `::` (double colon) between connection ID and capability name - **64-character limit**: The entire namespaced name cannot exceed 64 characters -**Example**: Two GitHub connections can both expose a `CREATE_PR` tool: -- `github_personal_456::CREATE_PR` (personal account) -- `github_work_789::CREATE_PR` (work account) +**Example**: Two Shopify connections can both expose a `GET_ORDERS` tool: +- `shopify_store_a_456::GET_ORDERS` (Store A account) +- `shopify_store_b_789::GET_ORDERS` (Store B account) This ensures capabilities remain distinct even when multiple connections expose tools with the same name. @@ -102,9 +102,9 @@ This ensures capabilities remain distinct even when multiple connections expose Resources use URI-based namespacing, **except for well-known protocols**. -**Custom protocols** (like `repo://`, `team://`) get namespaced with the connection ID and URL-encoded: -- Original: `repo://my-org/my-repo/README.md` -- Namespaced: `github_conn_123://repo%3A%2F%2Fmy-org%2Fmy-repo%2FREADME.md` +**Custom protocols** (like `store://`, `inventory://`) get namespaced with the connection ID and URL-encoded: +- Original: `store://my-brand/products/catalog.json` +- Namespaced: `shopify_conn_123://store%3A%2F%2Fmy-brand%2Fproducts%2Fcatalog.json` **Well-known protocols** (like `http://`, `https://`, `ws://`) are **NOT namespaced** and remain unchanged. @@ -130,7 +130,7 @@ Virtual MCPs provide the **foundational capability** that powers specialized fea Virtual MCPs turn fragmented MCP connections into unified, reusable capability packages: **Real-world applications:** -- **Order Fulfillment Operations**: Package Shopify (orders) + ShipStation (shipping) + Slack (notifications) into one fulfillment MCP +- **Order Fulfillment Operations**: Package Shopify (orders) + ShipStation (shipping) + email provider (notifications) into one fulfillment MCP - **Customer Service Hub**: Remix Shopify tools with inline customer service prompts and return policy guidelines - **Inventory Management**: Combine warehouse APIs + Shopify inventory tools with inline stock alert workflows - **Multi-brand Store Management**: Share access to a Shopify MCP connection across your team while filtering brand-specific operations—giving managers scoped access to their brand's products and orders without exposing other brands From 983d40261a4aa66ac4c259dcbea91b0fb78918fc Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 16:33:43 -0300 Subject: [PATCH 50/51] docs(api-reference): update built-in tools examples to e-commerce context Update examples in built-in tools documentation: - subtask-run.mdx: Change from GitHub/Slack to inventory/orders/shipping - tool-enable.mdx: Replace GitHub/deployment with Shopify/inventory/shipping - tool-search.mdx: Update from GitHub/deploy to order/inventory searches Maintains technical accuracy while making examples more relevant to e-commerce teams using MCP Mesh. Co-Authored-By: Claude Sonnet 4.5 --- .../built-in-tools/subtask-run.mdx | 6 +++--- .../built-in-tools/tool-enable.mdx | 18 +++++++++--------- .../built-in-tools/tool-search.mdx | 8 ++++---- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/subtask-run.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/subtask-run.mdx index e1fcb1ac82..1c5441d78c 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/subtask-run.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/subtask-run.mdx @@ -69,9 +69,9 @@ subtask_run("Run integration tests") Spawn multiple subtasks for independent work that can run in parallel: ```typescript -subtask_run("Fetch GitHub issues") -subtask_run("Fetch Slack messages") -subtask_run("Check deployment status") +subtask_run("Analyze inventory levels across all warehouses") +subtask_run("Fetch pending customer orders from Shopify") +subtask_run("Check shipping carrier delivery status") ``` ### Specialized Execution diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-enable.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-enable.mdx index 415f45039e..13770b56bc 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-enable.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-enable.mdx @@ -39,27 +39,27 @@ Success status and enabled confirmation. ## Example Usage ```typescript -// Enable a GitHub tool -tool_enable("CREATE_PR") +// Enable a Shopify tool +tool_enable("GET_ORDERS") -// Enable a Slack tool -tool_enable("SEND_MESSAGE") +// Enable an inventory tool +tool_enable("UPDATE_STOCK_LEVELS") -// Enable a deployment tool -tool_enable("DEPLOY_TO_PRODUCTION") +// Enable a shipping tool +tool_enable("CREATE_SHIPPING_LABEL") ``` ## Workflow Pattern ```typescript // 1. Discover available tools -const tools = tool_search("github") +const tools = tool_search("order") // 2. Enable specific tool -tool_enable("CREATE_PR") +tool_enable("GET_ORDERS") // 3. Use the enabled tool -CREATE_PR({ title: "Fix bug", branch: "main" }) +GET_ORDERS({ status: "pending", limit: 50 }) ``` ## Related diff --git a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-search.mdx b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-search.mdx index 00f24bb602..0af671a299 100644 --- a/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-search.mdx +++ b/apps/docs/client/src/content/en/mcp-mesh/api-reference/built-in-tools/tool-search.mdx @@ -44,11 +44,11 @@ Array of tool definitions with: // Search for all tools tool_search() -// Search for GitHub-related tools -tool_search("github") +// Search for order-related tools +tool_search("order") -// Search for deployment tools -tool_search("deploy") +// Search for inventory tools +tool_search("inventory") ``` ## Related From 6cc5355aa07cf1bbfcb7c9b95b9c6be760945408 Mon Sep 17 00:00:00 2001 From: gimenes Date: Tue, 10 Feb 2026 16:33:45 -0300 Subject: [PATCH 51/51] docs: remove completed quickstart redesign plan Remove the design plan file now that the quickstart redesign has been implemented. The plan served its purpose in guiding the restructuring of the documentation. Co-Authored-By: Claude Sonnet 4.5 --- ...026-02-10-decopilot-quickstart-redesign.md | 180 ------------------ 1 file changed, 180 deletions(-) delete mode 100644 docs/plans/2026-02-10-decopilot-quickstart-redesign.md diff --git a/docs/plans/2026-02-10-decopilot-quickstart-redesign.md b/docs/plans/2026-02-10-decopilot-quickstart-redesign.md deleted file mode 100644 index f7ab67df36..0000000000 --- a/docs/plans/2026-02-10-decopilot-quickstart-redesign.md +++ /dev/null @@ -1,180 +0,0 @@ -# Decopilot Quickstart Redesign - Design Document - -**Date:** 2026-02-10 -**Status:** Design Phase - -## Overview - -Redesign the decopilot quickstart guide to focus on practical usage for non-technical e-commerce teams (designers, content creators, project managers) rather than technical implementation details. Use progressive disclosure to introduce features naturally through real-world scenarios. - -## Target Audience - -- E-commerce team members with mixed backgrounds -- Roles: designers, content creators, project managers, merchandisers -- May not have programming experience -- Need to accomplish practical e-commerce tasks - -## Design Principles - -1. **Action-oriented** - Show what to ask for, not how it works internally -2. **Progressive complexity** - Start simple, gradually introduce advanced features -3. **Visual interactions** - Use ASCII art to show user/decopilot conversations -4. **Short sections** - Keep each section concise (150-200 words max) -5. **E-commerce context** - All examples relate to online retail operations - -## Content Structure - -### Section 1: Simple Requests - -**Purpose:** Show basic decopilot usage without any complexity - -**Examples:** -- Update product descriptions for a sale -- Check inventory levels -- Find products missing images - -**Key learning:** Just ask decopilot in natural language, get results back - -**Length:** ~150 words + 2-3 ASCII art examples - ---- - -### Section 2: Using Subtasks for Heavy Work - -**Purpose:** Introduce subtasks when work gets complex or generates lots of output - -**Examples:** -- Analyze stock ruptures across warehouses -- Research competitor pricing -- Audit product data quality - -**Key learning:** Use subtasks to keep main conversation clean, get back summaries - -**Length:** ~200 words + 1-2 ASCII art examples - ---- - -### Section 3: Working with Specialist Agents - -**Purpose:** Show how agents bring domain expertise to subtasks - -**Examples:** -- Inventory Specialist for demand forecasting -- Shipping Agent for logistics optimization -- Customer Service Agent for support strategy - -**Key learning:** Agents are specialists you can call on for focused tasks - -**Length:** ~200 words + 1-2 ASCII art examples - ---- - -### Section 4: Managing Context for Long Workflows - -**Purpose:** Introduce context management when working on multi-step projects - -**Examples:** -- Product launch preparation over multiple days -- When to use `/compact` command -- How subtasks help manage context - -**Key learning:** Keep conversations productive by managing context strategically - -**Length:** ~200 words + 1 ASCII art example - ---- - -### Section 5: Switching Scopes for Different Work - -**Purpose:** Show when to switch between organization/project/agent scopes - -**Examples:** -- Organization scope: Connect Shopify or set up integrations -- Project scope: Day-to-day feature development -- Agent scope: Specialized tasks with focused tools - -**Key learning:** Different scopes give you different capabilities - -**Length:** ~150 words + 1 ASCII art example - ---- - -### Closing: Putting It All Together - -**Purpose:** Quick recap and encourage exploration - -**Content:** -- Brief summary of progression -- Reminder to experiment -- Links to deeper documentation - -**Length:** ~100 words - -## ASCII Art Style - -Use simple box drawing and arrows to show conversation flow: - -``` -You → "Check inventory for SKU-123" - ↓ -Decopilot checks stock levels - ↓ -You ← "SKU-123: 47 units in stock - Last restock: Feb 8 - Reorder point: 20 units" -``` - -For multi-step or subtask flows: - -``` -You → "Run subtask: analyze stock ruptures" - ↓ -Subtask starts (isolated context) - ↓ -Analyzes 500 SKUs across 3 warehouses - ↓ -You ← Summary: "3 critical items need reorder: - - SKU-123: 8 units (reorder at 10) - - SKU-456: 5 units (reorder at 15) - - SKU-789: 2 units (reorder at 5)" -``` - -## Removed Content - -The following will be removed from the current quickstart: - -- All TypeScript code examples -- Internal implementation details (tool_enable, tool_search, etc.) -- Mermaid sequence diagrams showing tool calls -- Technical explanations of the agentic loop -- References to "defineTool()", "MeshContext", etc. - -These technical details remain in the Architecture and Tools documentation where they belong. - -## Links to Other Docs - -Each section will link to relevant deep-dive docs: - -- Section 2 → Tasks documentation -- Section 3 → Agents documentation -- Section 4 → Context documentation -- Section 5 → Scopes documentation - -## Success Criteria - -A successful redesign will: - -1. Be understandable by non-programmers -2. Show practical e-commerce use cases -3. Progressively introduce concepts -4. Use visual examples (ASCII art) -5. Keep sections short and scannable -6. Link to technical docs for those who want depth - -## Next Steps - -1. Write complete draft with all sections -2. Review ASCII art examples for clarity -3. Validate e-commerce examples are realistic -4. Ensure links to other docs are correct -5. Get user approval before implementation