@polymorphism-tech/morph-spec 8.29.0 → 8.31.0

package/framework/standards/ai-agents/mcp-tools.md

@@ -1,197 +1,197 @@
-# MCP Tools — Agent consuming MCP servers
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 2 (on-keyword)
-> **Keywords:** mcp, model context protocol, mcp client, consume mcp server, mcp tools, external tools
-> **Read by Claude in:** implement (quando um agente usa tools de um MCP server externo)
-
-**Verified against:** MAF 1.0 GA + ModelContextProtocol C# SDK. Last-verified: 2026-05-19.
-
----
-
-## O que é (no contexto de um agente MAF)
-
-MCP (Model Context Protocol) é um protocolo aberto que padroniza como um agente expõe e consome tools. Um agente MAF pode se conectar a qualquer **MCP server externo** (GitHub, filesystem, Postgres, ferramentas internas de outro projeto) e usar as tools desse servidor exatamente como se fossem tools nativas — o MAF trata tudo como `AITool`.
-
-Casos de uso típicos:
-
-- Agente de repositório que usa o GitHub MCP server para listar PRs e issues
-- Agente de dados que usa o PostgreSQL MCP server para rodar queries
-- Agente de documentação que usa o filesystem MCP server para ler arquivos locais
-- Agente corporativo que consome um MCP server interno de outro projeto
-
----
-
-## A API
-
-**Package:**
-
-```xml
-<PackageReference Include="ModelContextProtocol" Version="0.1.*" />
-```
-
-> O pacote `ModelContextProtocol` é o SDK C# oficial do protocolo. Versão 0.1.* (preview) — GA previsto; verifique no NuGet antes de travar versão.
-
-**Fluxo de consumo:**
-
-1. `McpClientFactory.CreateAsync(transport)` — conecta ao MCP server e retorna um client `IDisposable`
-2. `mcpClient.ListToolsAsync()` — descobre as tools disponíveis no servidor
-3. `mcpTools.Cast<AITool>()` — converte para `AITool` (interface do MAF / `Microsoft.Extensions.AI`)
-4. Passa as tools ao agente via `AsAIAgent(..., tools: [.. mcpTools.Cast<AITool>()])`
-
-**Transports suportados:**
-
-| Transport | Classe | Quando usar |
-|-----------|--------|------------|
-| stdio | `StdioClientTransport` | MCP server local (processo filho — `npx`, executável) |
-| HTTP (SSE) | `SseClientTransport` | MCP server remoto via HTTP/SSE |
-
-**Regra importante:** use `await using` no `mcpClient` — o dispose fecha o transporte corretamente.
-
----
-
-## Exemplo C#
-
-Agente que consome o GitHub MCP server e responde perguntas sobre repositórios:
-
-```csharp
-using ModelContextProtocol;
-using ModelContextProtocol.Client;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-// 1. Conectar ao MCP server (GitHub via npx)
-await using var mcpClient = await McpClientFactory.CreateAsync(
-    new StdioClientTransport(new()
-    {
-        Name = "GitHubServer",
-        Command = "npx",
-        Arguments = ["-y", "--verbose", "@modelcontextprotocol/server-github"],
-    }));
-
-// 2. Descobrir as tools do servidor
-var mcpTools = await mcpClient.ListToolsAsync();
-
-// 3. Criar o agente MAF com as MCP tools registradas
-// _modelRegistry vem de IModelRegistry (ai-agents-providers-model-registry)
-AIAgent agent = _modelRegistry.GetChatClient("text-default")
-    .AsAIAgent(
-        instructions: "You answer questions about GitHub repositories.",
-        tools: [.. mcpTools.Cast<AITool>()]);
-
-// 4. Usar o agente normalmente
-var response = await agent.RunAsync(
-    "Summarize the last 4 commits to microsoft/agent-framework");
-Console.WriteLine(response.Text);
-```
-
-**Variante com MCP server remoto (HTTP/SSE):**
-
-```csharp
-using ModelContextProtocol.Client;
-
-await using var mcpClient = await McpClientFactory.CreateAsync(
-    new SseClientTransport(new()
-    {
-        Name = "RemoteToolsServer",
-        Uri = new Uri("https://tools.example.com/mcp"),
-    }));
-
-var mcpTools = await mcpClient.ListToolsAsync();
-// Mesmo padrão para criar o agente...
-```
-
-**Múltiplos MCP servers:**
-
-```csharp
-// Conectar a dois servidores e combinar as tools
-await using var githubClient = await McpClientFactory.CreateAsync(
-    new StdioClientTransport(new()
-    {
-        Name = "GitHub",
-        Command = "npx",
-        Arguments = ["-y", "@modelcontextprotocol/server-github"],
-    }));
-
-await using var fsClient = await McpClientFactory.CreateAsync(
-    new StdioClientTransport(new()
-    {
-        Name = "Filesystem",
-        Command = "npx",
-        Arguments = ["-y", "@modelcontextprotocol/server-filesystem", "/repo"],
-    }));
-
-var allTools = (await githubClient.ListToolsAsync())
-    .Concat(await fsClient.ListToolsAsync())
-    .Cast<AITool>()
-    .ToArray();
-
-AIAgent agent = _modelRegistry.GetChatClient("text-default")
-    .AsAIAgent(
-        instructions: "You help navigate the codebase.",
-        tools: allTools);
-```
-
----
-
-## Popular MCP Servers
-
-| Server npm | Propósito |
-|-----------|-----------|
-| `@modelcontextprotocol/server-github` | Repos, issues, PRs do GitHub |
-| `@modelcontextprotocol/server-filesystem` | Operações no sistema de arquivos |
-| `@modelcontextprotocol/server-sqlite` | Acesso a banco de dados SQLite |
-| `@modelcontextprotocol/server-postgres` | Acesso a banco de dados PostgreSQL |
-
----
-
-## MCP server vs tool nativa
-
-| Cenário | Decisão | Motivo |
-|---------|---------|--------|
-| O servidor existe e é mantido por terceiros (GitHub, Postgres...) | Consumir MCP server | Reutilização imediata; sem esforço de manutenção |
-| A lógica é específica deste projeto (ex.: buscar pedido no banco) | Escrever tool nativa `[Description]` | Mais simples, sem overhead de protocolo, testável diretamente |
-| O servidor interno já existe e está publicado como MCP | Consumir MCP server | Evita duplicar lógica |
-| Precisa de controle total de retries, logging, validação | Tool nativa + middleware MAF | Middleware `ResilientToolMiddleware` dá controle fino |
-
-**Regra**: prefira MCP server quando o servidor já existe e é mantido por terceiros. Prefira tool nativa quando a lógica é do próprio projeto.
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Problema | Solução |
-|-------------|---------|---------|
-| Criar um MCP server próprio só para o agente do mesmo projeto chamar | Overhead desnecessário de protocolo e deploy | Escrever tool nativa com `[Description]` + `AIFunctionFactory.Create()` |
-| Não tratar indisponibilidade do MCP server | O MCP server pode estar offline ou lento; o agente quebra | Usar `ResilientToolMiddleware` para capturar `HttpRequestException` e `TimeoutException` (ver `ai-agents-production`) |
-| Não usar `await using` no `mcpClient` | Processo filho (npx) fica zumbi; leak de recursos | Sempre `await using var mcpClient = await McpClientFactory.CreateAsync(...)` |
-| Hardcodar o model diretamente (`new ChatClient("gpt-4o", key)`) | Viola provider-agnostic; difícil de trocar | Sempre `_modelRegistry.GetChatClient("alias")` (ver `ai-agents-providers-model-registry`) |
-
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] `ModelContextProtocol` presente no `.csproj`
-- [ ] `await using var mcpClient` — dispose correto do transporte
-- [ ] `McpClientFactory.CreateAsync(new StdioClientTransport(...))` com `Name`, `Command`, `Arguments`
-- [ ] `ListToolsAsync()` chamado antes de criar o agente
-- [ ] `mcpTools.Cast<AITool>()` para registrar no agente
-- [ ] Agente criado via `_modelRegistry.GetChatClient("alias").AsAIAgent(...)` — provider-agnostic
-- [ ] `ResilientToolMiddleware` ou equivalente registrado (o MCP server pode ficar indisponível)
-- [ ] Nenhum `Guid.NewGuid()` — usar `Guid.CreateVersion7()` se IDs são necessários
-
----
-
-## References
-
-- `ai-agents-setup` — pacotes base MAF, DI, quick start
-- `ai-agents-production` — panorama de MCP Integration, `ResilientToolMiddleware`, middleware pipeline
-- `ai-agents-mcp-server` — expor capacidades do próprio projeto como MCP server
-- `integration/mcp/mcp-tools.md` — MCPs no workflow do morph-spec (Playwright, Context7, Neon) — contexto complementar, escopo diferente
-- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
-- [Using MCP Tools — MAF docs](https://learn.microsoft.com/agent-framework/user-guide/model-context-protocol/using-mcp-tools)
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/mcp-tools.md v1.0 (2026-05-19)*
+# MCP Tools — Agent consuming MCP servers
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** mcp, model context protocol, mcp client, consume mcp server, mcp tools, external tools
+> **Read by Claude in:** implement (quando um agente usa tools de um MCP server externo)
+
+**Verified against:** MAF 1.0 GA + ModelContextProtocol C# SDK. Last-verified: 2026-05-19.
+
+---
+
+## O que é (no contexto de um agente MAF)
+
+MCP (Model Context Protocol) é um protocolo aberto que padroniza como um agente expõe e consome tools. Um agente MAF pode se conectar a qualquer **MCP server externo** (GitHub, filesystem, Postgres, ferramentas internas de outro projeto) e usar as tools desse servidor exatamente como se fossem tools nativas — o MAF trata tudo como `AITool`.
+
+Casos de uso típicos:
+
+- Agente de repositório que usa o GitHub MCP server para listar PRs e issues
+- Agente de dados que usa o PostgreSQL MCP server para rodar queries
+- Agente de documentação que usa o filesystem MCP server para ler arquivos locais
+- Agente corporativo que consome um MCP server interno de outro projeto
+
+---
+
+## A API
+
+**Package:**
+
+```xml
+<PackageReference Include="ModelContextProtocol" Version="0.1.*" />
+```
+
+> O pacote `ModelContextProtocol` é o SDK C# oficial do protocolo. Versão 0.1.* (preview) — GA previsto; verifique no NuGet antes de travar versão.
+
+**Fluxo de consumo:**
+
+1. `McpClientFactory.CreateAsync(transport)` — conecta ao MCP server e retorna um client `IDisposable`
+2. `mcpClient.ListToolsAsync()` — descobre as tools disponíveis no servidor
+3. `mcpTools.Cast<AITool>()` — converte para `AITool` (interface do MAF / `Microsoft.Extensions.AI`)
+4. Passa as tools ao agente via `AsAIAgent(..., tools: [.. mcpTools.Cast<AITool>()])`
+
+**Transports suportados:**
+
+| Transport | Classe | Quando usar |
+|-----------|--------|------------|
+| stdio | `StdioClientTransport` | MCP server local (processo filho — `npx`, executável) |
+| HTTP (SSE) | `SseClientTransport` | MCP server remoto via HTTP/SSE |
+
+**Regra importante:** use `await using` no `mcpClient` — o dispose fecha o transporte corretamente.
+
+---
+
+## Exemplo C#
+
+Agente que consome o GitHub MCP server e responde perguntas sobre repositórios:
+
+```csharp
+using ModelContextProtocol;
+using ModelContextProtocol.Client;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// 1. Conectar ao MCP server (GitHub via npx)
+await using var mcpClient = await McpClientFactory.CreateAsync(
+    new StdioClientTransport(new()
+    {
+        Name = "GitHubServer",
+        Command = "npx",
+        Arguments = ["-y", "--verbose", "@modelcontextprotocol/server-github"],
+    }));
+
+// 2. Descobrir as tools do servidor
+var mcpTools = await mcpClient.ListToolsAsync();
+
+// 3. Criar o agente MAF com as MCP tools registradas
+// _modelRegistry vem de IModelRegistry (ai-agents-providers-model-registry)
+AIAgent agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(
+        instructions: "You answer questions about GitHub repositories.",
+        tools: [.. mcpTools.Cast<AITool>()]);
+
+// 4. Usar o agente normalmente
+var response = await agent.RunAsync(
+    "Summarize the last 4 commits to microsoft/agent-framework");
+Console.WriteLine(response.Text);
+```
+
+**Variante com MCP server remoto (HTTP/SSE):**
+
+```csharp
+using ModelContextProtocol.Client;
+
+await using var mcpClient = await McpClientFactory.CreateAsync(
+    new SseClientTransport(new()
+    {
+        Name = "RemoteToolsServer",
+        Uri = new Uri("https://tools.example.com/mcp"),
+    }));
+
+var mcpTools = await mcpClient.ListToolsAsync();
+// Mesmo padrão para criar o agente...
+```
+
+**Múltiplos MCP servers:**
+
+```csharp
+// Conectar a dois servidores e combinar as tools
+await using var githubClient = await McpClientFactory.CreateAsync(
+    new StdioClientTransport(new()
+    {
+        Name = "GitHub",
+        Command = "npx",
+        Arguments = ["-y", "@modelcontextprotocol/server-github"],
+    }));
+
+await using var fsClient = await McpClientFactory.CreateAsync(
+    new StdioClientTransport(new()
+    {
+        Name = "Filesystem",
+        Command = "npx",
+        Arguments = ["-y", "@modelcontextprotocol/server-filesystem", "/repo"],
+    }));
+
+var allTools = (await githubClient.ListToolsAsync())
+    .Concat(await fsClient.ListToolsAsync())
+    .Cast<AITool>()
+    .ToArray();
+
+AIAgent agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(
+        instructions: "You help navigate the codebase.",
+        tools: allTools);
+```
+
+---
+
+## Popular MCP Servers
+
+| Server npm | Propósito |
+|-----------|-----------|
+| `@modelcontextprotocol/server-github` | Repos, issues, PRs do GitHub |
+| `@modelcontextprotocol/server-filesystem` | Operações no sistema de arquivos |
+| `@modelcontextprotocol/server-sqlite` | Acesso a banco de dados SQLite |
+| `@modelcontextprotocol/server-postgres` | Acesso a banco de dados PostgreSQL |
+
+---
+
+## MCP server vs tool nativa
+
+| Cenário | Decisão | Motivo |
+|---------|---------|--------|
+| O servidor existe e é mantido por terceiros (GitHub, Postgres...) | Consumir MCP server | Reutilização imediata; sem esforço de manutenção |
+| A lógica é específica deste projeto (ex.: buscar pedido no banco) | Escrever tool nativa `[Description]` | Mais simples, sem overhead de protocolo, testável diretamente |
+| O servidor interno já existe e está publicado como MCP | Consumir MCP server | Evita duplicar lógica |
+| Precisa de controle total de retries, logging, validação | Tool nativa + middleware MAF | Middleware `ResilientToolMiddleware` dá controle fino |
+
+**Regra**: prefira MCP server quando o servidor já existe e é mantido por terceiros. Prefira tool nativa quando a lógica é do próprio projeto.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema | Solução |
+|-------------|---------|---------|
+| Criar um MCP server próprio só para o agente do mesmo projeto chamar | Overhead desnecessário de protocolo e deploy | Escrever tool nativa com `[Description]` + `AIFunctionFactory.Create()` |
+| Não tratar indisponibilidade do MCP server | O MCP server pode estar offline ou lento; o agente quebra | Usar `ResilientToolMiddleware` para capturar `HttpRequestException` e `TimeoutException` (ver `ai-agents-production`) |
+| Não usar `await using` no `mcpClient` | Processo filho (npx) fica zumbi; leak de recursos | Sempre `await using var mcpClient = await McpClientFactory.CreateAsync(...)` |
+| Hardcodar o model diretamente (`new ChatClient("gpt-4o", key)`) | Viola provider-agnostic; difícil de trocar | Sempre `_modelRegistry.GetChatClient("alias")` (ver `ai-agents-providers-model-registry`) |
+
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `ModelContextProtocol` presente no `.csproj`
+- [ ] `await using var mcpClient` — dispose correto do transporte
+- [ ] `McpClientFactory.CreateAsync(new StdioClientTransport(...))` com `Name`, `Command`, `Arguments`
+- [ ] `ListToolsAsync()` chamado antes de criar o agente
+- [ ] `mcpTools.Cast<AITool>()` para registrar no agente
+- [ ] Agente criado via `_modelRegistry.GetChatClient("alias").AsAIAgent(...)` — provider-agnostic
+- [ ] `ResilientToolMiddleware` ou equivalente registrado (o MCP server pode ficar indisponível)
+- [ ] Nenhum `Guid.NewGuid()` — usar `Guid.CreateVersion7()` se IDs são necessários
+
+---
+
+## References
+
+- `ai-agents-setup` — pacotes base MAF, DI, quick start
+- `ai-agents-production` — panorama de MCP Integration, `ResilientToolMiddleware`, middleware pipeline
+- `ai-agents-mcp-server` — expor capacidades do próprio projeto como MCP server
+- `integration/mcp/mcp-tools.md` — MCPs no workflow do morph-spec (Playwright, Context7, Neon) — contexto complementar, escopo diferente
+- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
+- [Using MCP Tools — MAF docs](https://learn.microsoft.com/agent-framework/user-guide/model-context-protocol/using-mcp-tools)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/mcp-tools.md v1.0 (2026-05-19)*