@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/standards/integration/mcp/mcp-tools.md

@@ -5,32 +5,26 @@
 > **Keywords:** mcp, model-context-protocol, mcp-tools, context7, playwright, mcp-client
 > **Load When:** an MCP tool is used in any morph-spec phase
 
-**Verified against:** Claude Code MCP tooling — context7, Playwright; GitHub via `gh` CLI; Neon via `neonctl`. Last-verified: 2026-07-08.
+**Verified against:** Claude Code 2.1.282 MCP tooling — context7, Playwright (as plugin and as a project MCP server); GitHub via `gh` CLI; Neon via its MCP or `neonctl`. Last-verified: 2026-09-24.
 
 ---
 
 Reference for using Model Context Protocol (MCP) tools across morph-spec phases. Each phase benefits from different MCPs depending on what data is needed.
 
-## MCP Availability Detection
+## Tool Names Depend on Where the Server Is Configured
 
-Before using any MCP tool, check if it's available in the current session:
+The names below use the `.mcp.json` form, `mcp__<server>__<tool>`. The same server installed as a **plugin** is named `mcp__plugin_<plugin>_<server>__<tool>`: context7 from the plugin is `mcp__plugin_context7_context7__query-docs`, not `mcp__context7__query-docs`. Call the name that exists in your session. The tool part (`query-docs`, `browser_navigate`) is the same under both prefixes.
 
-```javascript
-// Pattern: Attempt the call — if the tool doesn't exist, Claude Code will report it
-// There is no "list MCPs" command; just try the most common operation
+In a morph persona the grant follows the same rule: the installer emits one `mcp__<name>` per spelling in the registry's `serverNames`, and a grant matches only its own spelling. If a tool you expect is missing, it may be deferred: load it with `ToolSearch` before calling it.
+
+## MCP Availability Detection
 
-// GitHub — o morph-spec NÃO usa MCP do GitHub: use o `gh` CLI via Bash
-// gh repo view --json name,defaultBranchRef,languages
+Before using any MCP tool, check if it's available in the current session. There is no "list MCPs" command: attempt the most common operation, and Claude Code reports a tool that doesn't exist. GitHub and Neon are not checked this way — o morph-spec NÃO usa MCP do GitHub nem do Neon: use o `gh` CLI (`gh repo view --json name,defaultBranchRef,languages`) e o `neonctl` + `psql` (`neonctl connection-string` dá a URL do banco) via Bash.
 
-// Context7 (library docs)
-await mcp__context7__resolve_library_id({ libraryName: "react" });
+```javascript
+await mcp__context7__resolve-library-id({ libraryName: "react" });
 
-// Playwright (browser automation)
 await mcp__playwright__browser_navigate({ url: "https://example.com" });
-
-// Neon — use `neonctl` CLI + `psql`
-// neonctl connection-string → get DB URL
-// psql <DB_URL> -c "SELECT ..."
 ```
 
 **Fallback rule:** If an MCP is not available, every phase has a manual alternative using Claude Code native tools (Read, Grep, Glob, Bash).
@@ -61,36 +55,31 @@ gh issue list --limit 10 --json title,labels
 | MCP | Use Case | Example |
 |-----|----------|---------|
 | **Playwright** | Navigate, screenshot, inspect live pages | `mcp__playwright__browser_navigate({ url })` |
-| **Context7** | Component library documentation | `mcp__context7__query_docs({ libraryId, query })` |
+| **Context7** | Component library documentation | `mcp__context7__query-docs({ libraryId, query })` |
+
+The screenshot is the visual reference; the snapshot is the accessibility tree (headings, buttons, inputs); the resize tests the mobile layout; Context7 brings the component docs for the UI spec.
 
 ```javascript
-// Screenshot existing app for design reference
 await mcp__playwright__browser_navigate({ url: "https://app.example.com/dashboard" });
 const screenshot = await mcp__playwright__browser_take_screenshot();
-// → Visual reference for UI/UX design
 
-// Inspect page structure via accessibility tree
 const snapshot = await mcp__playwright__browser_snapshot();
-// → Structured element tree (headings, buttons, inputs, etc.)
 
-// Test responsive layout
 await mcp__playwright__browser_resize({ width: 375, height: 812 });
 const mobileScreenshot = await mcp__playwright__browser_take_screenshot();
 
-// Get MudBlazor component docs for UI specs
-const libId = await mcp__context7__resolve_library_id({
+const libId = await mcp__context7__resolve-library-id({
   libraryName: "mudblazor",
   query: "data grid with sorting and filtering"
 });
-const docs = await mcp__context7__query_docs({
+const docs = await mcp__context7__query-docs({
   libraryId: libId,
   query: "DataGrid component props and events"
 });
-
-// Fallback: WebSearch for component documentation
-// WebFetch for specific component API pages
 ```
 
+Fallback: WebSearch for component documentation, WebFetch for specific component API pages.
+
 ### Gemini Image MCP — AI Image Generation
 
 > Available in: **UI/UX** (preview generation), **Implement** (production assets)
@@ -103,29 +92,27 @@ const docs = await mcp__context7__query_docs({
 | `list_images` | Browse image generation history | `mcp__gemini-image-mcp__list_images({ type: "all" })` |
 | `get_image_info` | Get metadata about a specific image | `mcp__gemini-image-mcp__get_image_info({ imageId })` |
 
+Read `design-system.md` first to get the project colors and aesthetic direction. Keep edits short and targeted, and iterate with `continue_editing` one change at a time.
+
 ```javascript
-// Generate a hero image using design system tokens
-// Read design-system.md first to get project colors and aesthetic direction
-const image = await mcp__gemini_image_mcp__generate_image({
+const image = await mcp__gemini-image-mcp__generate_image({
   prompt: "A floating tablet showing a modern dashboard interface on a dark charcoal background with copper and gold accent lighting. Premium luxury aesthetic, photorealistic, cinematic lighting with warm rim light.",
   aspectRatio: "16:9",
   outputPath: "public/images/my-feature/hero-mockup.png"
 });
 
-// Edit an existing image (keep edits short and targeted)
-await mcp__gemini_image_mcp__edit_image({
+await mcp__gemini-image-mcp__edit_image({
   imageSource: "public/images/my-feature/hero-mockup.png",
   prompt: "Make the lighting warmer and add a subtle copper glow around the tablet edges."
 });
 
-// Iterate with continue_editing (one change at a time)
-await mcp__gemini_image_mcp__continue_editing({
+await mcp__gemini-image-mcp__continue_editing({
   prompt: "More contrast in the shadows."
 });
-
-// Fallback: Manual image creation, stock photos, or placeholder divs
 ```
 
+Fallback: manual image creation, stock photos, or placeholder divs.
+
 **Use cases by phase:**
 
 | Phase | Use Case | Tool |
@@ -143,7 +130,7 @@ await mcp__gemini_image_mcp__continue_editing({
 | Tool | Use Case | Example |
 |------|----------|---------|
 | **Neon CLI (`neonctl`) / psql** | Database schema, tables, relationships, RLS | `psql <DB_URL> -c "SELECT ..."` |
-| **Context7** | Library docs for architecture decisions | `mcp__context7__query_docs()` |
+| **Context7** | Library docs for architecture decisions | `mcp__context7__query-docs()` |
 | **GitHub CLI (`gh`)** | Check existing code patterns, PRs | `gh search code` (Bash) |
 
 ```bash
@@ -183,26 +170,26 @@ psql $(neonctl connection-string) -c "SELECT tablename, policyname, cmd, qual FR
 
 | MCP | Use Case | Example |
 |-----|----------|---------|
-| **Context7** | Verify library capabilities, API limits | `mcp__context7__query_docs()` |
+| **Context7** | Verify library capabilities, API limits | `mcp__context7__query-docs()` |
 | **GitHub CLI (`gh`)** | Check issue discussions, known limitations | `gh search issues` (Bash) |
 
+The answer confirms a capability or identifies a limitation for the spec update:
+
 ```javascript
-// Verify if library supports a required feature
-const docs = await mcp__context7__query_docs({
+const docs = await mcp__context7__query-docs({
   libraryId: "/mudblazor/mudblazor",
   query: "DataGrid server-side pagination with virtual scrolling"
 });
-// → Confirms capability or identifies limitation for spec update
-
-// Fallback: WebSearch for library capabilities
 ```
 
+Fallback: WebSearch for library capabilities.
+
 ### Phase 6 (Tasks) — Planning & Organization
 
 | Tool | Use Case | Example |
 |------|----------|---------|
 | **GitHub CLI (`gh`)** | Create issues from tasks, link to milestone | `gh issue create` (Bash) |
-| **Context7** | Estimate complexity based on library docs | `mcp__context7__query_docs()` |
+| **Context7** | Estimate complexity based on library docs | `mcp__context7__query-docs()` |
 
 ```bash
 # Create GitHub issues from tasks.json (if team uses GitHub Projects)
@@ -218,7 +205,7 @@ gh issue create --title "T001: Create Entity Lead" \
 |------|----------|---------|
 | **Neon CLI (`neonctl`) / psql** | Run migrations, create RLS policies | `dotnet ef database update` |
 | **GitHub CLI (`gh`)** | Create PR, push branches | `gh pr create` (Bash) |
-| **Context7** | Look up API usage during coding | `mcp__context7__query_docs()` |
+| **Context7** | Look up API usage during coding | `mcp__context7__query-docs()` |
 | **Playwright** | Smoke test deployed features, verify UI | `mcp__playwright__browser_navigate()` |
 | **Vercel** | Deploy, check logs, manage env vars | `mcp__vercel__list_projects()` |
 | **Azure CLI** | Resource management, deployments | `az` commands |
@@ -240,35 +227,23 @@ psql $(neonctl connection-string) -c "SELECT column_name, data_type FROM informa
 psql $(neonctl connection-string) -c "SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
 ```
 
+Look up the API while coding, then smoke test the deployed feature: the snapshot shows whether the page renders, the console messages catch JavaScript errors and failed API calls, and the screenshot goes to `recap.md`. Vercel covers deployment status, logs and environment variables.
+
 ```javascript
-// Lookup API during implementation
-const docs = await mcp__context7__query_docs({
+const docs = await mcp__context7__query-docs({
   libraryId: "/dotnet/efcore",
   query: "owned entity types configuration"
 });
 
-// Smoke test deployed feature via browser
 await mcp__playwright__browser_navigate({ url: "https://localhost:5001/leads" });
 const snapshot = await mcp__playwright__browser_snapshot();
-// → Verify page renders correctly, check for errors
-
-// Check for console errors after deploy
 const logs = await mcp__playwright__browser_console_messages();
-// → Catch JavaScript errors, failed API calls
-
-// Screenshot for recap.md documentation
 const screenshot = await mcp__playwright__browser_take_screenshot();
 
-// === VERCEL (Deployment & Environment) ===
-
-// List projects
 const projects = await mcp__vercel__list_projects();
-
-// Check deployment status and logs
 const deployments = await mcp__vercel__get_deployments({ projectId: 'my-project' });
-const logs = await mcp__vercel__get_deployment_logs({ deploymentId: deployments[0].uid });
+const deploymentLogs = await mcp__vercel__get_deployment_logs({ deploymentId: deployments[0].uid });
 
-// Manage environment variables
 await mcp__vercel__manage_env_vars({
   projectId: 'my-project',
   action: 'set',
@@ -276,10 +251,10 @@ await mcp__vercel__manage_env_vars({
   value: process.env.DATABASE_URL,
   target: ['production', 'preview']
 });
-
-// PRs/issues: sempre `gh` CLI (Bash). Deployments fallback: vercel CLI
 ```
 
+PRs/issues: sempre `gh` CLI (Bash). Deployments fallback: `vercel` CLI.
+
 ---
 
 ## MCP vs Native Tools Decision
@@ -306,76 +281,33 @@ await mcp__vercel__manage_env_vars({
 
 ### Browser (Playwright): Page Automation & Analysis
 
-```javascript
-// === SETUP ===
-// Playwright MCP: npx @playwright/mcp@latest
-// Config in .claude/settings.json or claude_desktop_config.json:
-// { "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }
+Setup: `npx @playwright/mcp@latest`, configured in `.claude/settings.json` or `claude_desktop_config.json` as `{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }`.
 
-// === NAVIGATION & SNAPSHOT ===
+Prefer the accessibility snapshot to the screenshot: it is structured, LLM-friendly, and returns the element `ref`s that the interaction calls take. `browser_fill_form` replaces the field's existing value; `browser_handle_dialog` answers alert, confirm and prompt.
 
-// 1. Navigate to a page
+```javascript
 await mcp__playwright__browser_navigate({ url: "https://app.example.com/dashboard" });
-
-// 2. Take accessibility snapshot (preferred — structured, LLM-friendly)
 const snapshot = await mcp__playwright__browser_snapshot();
-// → Returns accessibility tree with element refs for interaction
-
-// 3. Take visual screenshot (requires --caps vision)
-const screenshot = await mcp__playwright__browser_take_screenshot();
-// → Returns PNG image of current page
-
-// === INTERACTION ===
+const screenshot = await mcp__playwright__browser_take_screenshot(); // requires --caps vision
 
-// 4. Click an element (use ref from snapshot)
 await mcp__playwright__browser_click({ element: "Submit button", ref: "s1e15" });
-
-// 5. Type into an input field
 await mcp__playwright__browser_type({ element: "Search input", ref: "s1e8", text: "query" });
-
-// 6. Fill a form field (replaces existing value)
 await mcp__playwright__browser_fill_form({ ref: "s1e8", value: "new value" });
-
-// 7. Select dropdown option
 await mcp__playwright__browser_select_option({ element: "Status", ref: "s1e12", values: ["active"] });
-
-// 8. Press keyboard key
 await mcp__playwright__browser_press_key({ key: "Enter" });
 
-// === TABS & NAVIGATION ===
-
-// 9. List open tabs
 const tabs = await mcp__playwright__browser_tabs();
-
-// 10. Navigate back
 await mcp__playwright__browser_navigate_back();
-
-// 11. Close current tab
 await mcp__playwright__browser_close();
 
-// === ADVANCED ===
-
-// 12. Evaluate JavaScript in page context
 const result = await mcp__playwright__browser_evaluate({
   expression: "document.querySelectorAll('.error').length"
 });
-
-// 13. Get console messages (debug)
 const logs = await mcp__playwright__browser_console_messages();
-
-// 14. Get network requests
 const requests = await mcp__playwright__browser_network_requests();
-
-// 15. Handle dialog (alert, confirm, prompt)
 await mcp__playwright__browser_handle_dialog({ accept: true });
-
-// 16. Resize viewport
-await mcp__playwright__browser_resize({ width: 375, height: 812 }); // iPhone viewport
-
-// 17. Save page as PDF (requires --caps pdf)
-await mcp__playwright__browser_pdf_save();
-
-// 18. Upload file
+await mcp__playwright__browser_resize({ width: 375, height: 812 });
+await mcp__playwright__browser_pdf_save(); // requires --caps pdf
 await mcp__playwright__browser_file_upload({ ref: "s1e20", paths: ["/path/to/file.png"] });
 ```
 
@@ -424,16 +356,15 @@ psql $(neonctl connection-string) -c "SELECT tc.table_name, kcu.column_name, ccu
 
 ### Context7: Library Research
 
+For any phase needing library documentation: resolve the library ID first, then query the specific documentation with it.
+
 ```javascript
-// Workflow for any phase needing library documentation
-// Step 1: Resolve library ID
-const lib = await mcp__context7__resolve_library_id({
+const lib = await mcp__context7__resolve-library-id({
   libraryName: "fluent-ui-blazor",
   query: "dialog component with form validation"
 });
 
-// Step 2: Query specific documentation
-const docs = await mcp__context7__query_docs({
+const docs = await mcp__context7__query-docs({
   libraryId: lib.id,
   query: "FluentDialog component usage with EditForm validation"
 });

package/framework/templates/code/dotnet/abstractions/result.cs

@@ -63,10 +63,8 @@ namespace {{pascalCase PROJECT_NAME}}.Abstractions
             ? _value!
             : throw new InvalidOperationException("The value of a failure result can not be accessed.");
 
-        // ✅ SUCCESS implicit conversion
         public static implicit operator Result<TValue>(TValue? value) => Create(value);
 
-        // ✅ ADD THIS (Failure implicit conversion)
         public static implicit operator Result<TValue>(Error error)
             => Failure<TValue>(error);
     }

package/framework/templates/code/dotnet/ai-agents/AgentBootstrap.cs.template

@@ -1,39 +1,26 @@
-// TEMPLATE: AgentBootstrap.cs
-// PURPOSE: Extension method to register ModelRegistry + a default agent in DI.
-// READS STANDARDS: ai-agents-setup, ai-agents-providers-model-registry
-// PLACEHOLDERS:
-//   {{PROJECT_NAMESPACE}}     — root namespace of the project
-//   {{DEFAULT_AGENT_NAME}}    — first agent name (e.g., "DefaultAssistant")
-//   {{DEFAULT_INSTRUCTIONS}}  — system prompt for default agent (1 line)
-// LAST-VERIFIED: 2026-05-19 (MAF 1.0 GA)
-
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.DependencyInjection;
-
-namespace {{PROJECT_NAMESPACE}}.AI;
-
-public static class AgentBootstrap
-{
-    /// <summary>
-    /// Register ModelRegistry (singleton) and the default agent.
-    /// Additional agents register themselves via builder.AddAIAgent("Name", ...).
-    /// </summary>
-    public static WebApplicationBuilder AddMafAgents(this WebApplicationBuilder builder)
-    {
-        // Single source of truth for model selection
-        builder.Services.AddSingleton<ModelRegistry>();
-
-        // Default agent — uses the default alias from model-registry.json
-        builder.Services.AddKeyedSingleton<AIAgent>("{{DEFAULT_AGENT_NAME}}", (sp, _) =>
-        {
-            var registry = sp.GetRequiredService<ModelRegistry>();
-            var chatClient = registry.GetChatClient(registry.DefaultAlias);
-            return chatClient.AsAIAgent(
-                instructions: "{{DEFAULT_INSTRUCTIONS}}",
-                name: "{{DEFAULT_AGENT_NAME}}");
-        });
-
-        return builder;
-    }
-}
+// READS STANDARDS: ai-agents-setup, ai-agents-providers-model-registry
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+public static class AgentBootstrap
+{
+    public static WebApplicationBuilder AddMafAgents(this WebApplicationBuilder builder)
+    {
+        builder.Services.AddSingleton<ModelRegistry>();
+
+        builder.Services.AddKeyedSingleton<AIAgent>("{{DEFAULT_AGENT_NAME}}", (sp, _) =>
+        {
+            var registry = sp.GetRequiredService<ModelRegistry>();
+            var chatClient = registry.GetChatClient(registry.DefaultAlias);
+            return chatClient.AsAIAgent(
+                instructions: "{{DEFAULT_INSTRUCTIONS}}",
+                name: "{{DEFAULT_AGENT_NAME}}");
+        });
+
+        return builder;
+    }
+}

package/framework/templates/code/dotnet/ai-agents/EmbeddingService.cs.template

@@ -1,68 +1,28 @@
-// TEMPLATE: EmbeddingService.cs
-// PURPOSE: Generates embeddings for RAG indexing and query, via IEmbeddingGenerator.
-// READS STANDARD: ai-agents-rag-custom-pgvector
-// PLACEHOLDERS:
-//   {{PROJECT_NAMESPACE}}  — root namespace of the project (e.g., MyProject)
-// LAST-VERIFIED: 2026-05-19
-//
-// IMPORTANT — IEmbeddingGenerator registration (in Program.cs of the project):
-//   The project must register IEmbeddingGenerator<string, Embedding<float>> in DI.
-//   Example for OpenAI text-embedding-3-small (the canonical "embeddings" alias):
-//
-//   builder.Services.AddSingleton<IEmbeddingGenerator<string, Embedding<float>>>(sp =>
-//   {
-//       var cfg = sp.GetRequiredService<IConfiguration>();
-//       return new OpenAIClient(cfg["OpenAI:ApiKey"]!)
-//           .GetEmbeddingClient("text-embedding-3-small")
-//           .AsIEmbeddingGenerator();
-//   });
-//
-//   For other providers (Google, Anthropic, Ollama) adapt the client construction —
-//   see ai-agents-providers-model-registry §providers for verified SDKs.
-
-using Microsoft.Extensions.AI;
-
-namespace {{PROJECT_NAMESPACE}}.AI;
-
-/// <summary>
-/// Generates text embeddings for RAG indexing and query.
-/// Wraps <see cref="IEmbeddingGenerator{TInput,TEmbedding}"/> so the rest of the project
-/// does not take a direct dependency on the underlying provider SDK.
-/// </summary>
-public sealed class EmbeddingService(IEmbeddingGenerator<string, Embedding<float>> generator)
-{
-    /// <summary>
-    /// Generates an embedding vector for a single text (used at query time).
-    /// </summary>
-    /// <param name="text">The text to embed.</param>
-    /// <param name="ct">Cancellation token.</param>
-    /// <returns>The embedding vector as <see cref="ReadOnlyMemory{T}"/> of float.</returns>
-    public async Task<ReadOnlyMemory<float>> EmbedAsync(
-        string text,
-        CancellationToken ct = default)
-    {
-        // GenerateAsync is the verified API: returns GeneratedEmbeddings<Embedding<float>>.
-        // Each Embedding<float>.Vector is a ReadOnlyMemory<float>.
-        // Source: Microsoft Learn — microsoft-extensions-ai (verified 2026-05-19).
-        GeneratedEmbeddings<Embedding<float>> result =
-            await generator.GenerateAsync([text], cancellationToken: ct);
-
-        return result[0].Vector;
-    }
-
-    /// <summary>
-    /// Generates embedding vectors for a batch of texts (used during document indexing).
-    /// </summary>
-    /// <param name="texts">The texts to embed.</param>
-    /// <param name="ct">Cancellation token.</param>
-    /// <returns>Embedding vectors in the same order as the input texts.</returns>
-    public async Task<IReadOnlyList<ReadOnlyMemory<float>>> EmbedBatchAsync(
-        IReadOnlyList<string> texts,
-        CancellationToken ct = default)
-    {
-        GeneratedEmbeddings<Embedding<float>> result =
-            await generator.GenerateAsync(texts, cancellationToken: ct);
-
-        return [.. result.Select(e => e.Vector)];
-    }
-}
+// READS STANDARD: ai-agents-rag-custom-pgvector
+
+using Microsoft.Extensions.AI;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+public sealed class EmbeddingService(IEmbeddingGenerator<string, Embedding<float>> generator)
+{
+    public async Task<ReadOnlyMemory<float>> EmbedAsync(
+        string text,
+        CancellationToken ct = default)
+    {
+        GeneratedEmbeddings<Embedding<float>> result =
+            await generator.GenerateAsync([text], cancellationToken: ct);
+
+        return result[0].Vector;
+    }
+
+    public async Task<IReadOnlyList<ReadOnlyMemory<float>>> EmbedBatchAsync(
+        IReadOnlyList<string> texts,
+        CancellationToken ct = default)
+    {
+        GeneratedEmbeddings<Embedding<float>> result =
+            await generator.GenerateAsync(texts, cancellationToken: ct);
+
+        return [.. result.Select(e => e.Vector)];
+    }
+}