Merge pull request #17 from YuliiaKovalova/feature/v1.1.0-profiles-and-validate

feat: v1.1.0 — template_validate tool, tool profiles, improved descriptions

Author: YuliiaKovalova

AGENTS.md

@@ -0,0 +1,99 @@
+# AGENTS.md — AI Agent Instructions for dotnet-template-mcp
+
+## Project Overview
+
+MCP server wrapping the .NET Template Engine for AI-driven template discovery, inspection, and instantiation. Ships as a dotnet tool (`DotnetTemplateMCP`) on NuGet.
+
+## Build & Test
+
+```bash
+dotnet build
+dotnet test
+```
+
+- Targets **net10.0** (see `global.json` for SDK version).
+- Uses **Central Package Management** — all versions in `Directory.Packages.props`.
+- CI runs on **ubuntu-latest** and **windows-latest** (see `.github/workflows/ci.yml`).
+- When the MCP server is running locally (e.g., as a tool provider), `dotnet build` may fail with a file lock on `bin/Debug/net10.0/Microsoft.TemplateEngine.MCP.exe`. Use `-o <tempdir>` to build to an alternate output path.
+
+## Architecture
+
+### Tool Registration Pattern
+
+Each MCP tool is a `static async` method in a sealed class under `src/Microsoft.TemplateEngine.MCP/Tools/`:
+
+```csharp
+[McpServerToolType]
+internal sealed class MyTool
+{
+    [McpServerTool(Name = "tool_name")]
+    [Description("Description shown to AI agents — lead with the pain point, not the feature name.")]
+    public static async Task<string> MyMethodAsync(
+        TemplateEngineService engineService,    // DI-injected service
+        McpFeatureFlags featureFlags,           // DI-injected feature flags
+        [Description("...")] string param1,     // User-facing params with [Description]
+        CancellationToken cancellationToken = default)
+    {
+        // 1. Telemetry
+        using var activity = McpTelemetry.StartToolActivity("tool_name");
+        var sw = Stopwatch.StartNew();
+        try
+        {
+            // 2. Profile check (for non-lite tools)
+            if (!featureFlags.IsToolEnabled("tool_name"))
+            {
+                return ToolProfileResponse.DisabledMessage("tool_name", "Hint for the user.");
+            }
+
+            // 3. Tool logic
+            // ...
+        }
+        finally
+        {
+            McpTelemetry.RecordDuration("tool_name", sw.Elapsed.TotalMilliseconds);
+        }
+    }
+}
+```
+
+### Key Rules
+
+1. **DI parameters come first** — `TemplateEngineService`, `McpFeatureFlags`, `McpServer` (if elicitation is needed) are injected by the MCP framework. User-facing parameters follow, each with a `[Description]` attribute.
+
+2. **When you add or change a DI parameter on a tool method, you MUST update all test call sites.** Tests in `test/Microsoft.TemplateEngine.MCP.Tests/` call tool methods directly (not through DI), so they must pass all parameters explicitly. Example: `new McpFeatureFlags()` for the default (Full profile).
+
+3. **Tool profiles** — Tools are either "lite" (5 core tools always available) or "full" (all tools). Non-lite tools must include a `featureFlags.IsToolEnabled()` check at the start. The lite tools are: `template_from_intent`, `template_instantiate`, `template_inspect`, `template_search`, `template_dry_run`.
+
+4. **Telemetry** — Every tool must call `McpTelemetry.StartToolActivity()` and `McpTelemetry.RecordDuration()`. Use `McpTelemetry.RecordError()` for failures.
+
+5. **Return format** — Tools return JSON strings via `JsonSerializer.Serialize(new { ... }, new JsonSerializerOptions { WriteIndented = true })`. Errors use `{ error, hint }` shape.
+
+6. **File header** — Every `.cs` file starts with:
+   ```csharp
+   // Licensed to the .NET Foundation under one or more agreements.
+   // The .NET Foundation licenses this file to you under the MIT license.
+   ```
+
+## PR Workflow
+
+1. **Always create PRs on a feature branch**, not directly to `main`.
+2. **After pushing, monitor the CI run** — check GitHub Actions status. If build or tests fail, fix and push again before considering the PR ready.
+3. **Version bumps** require updating three files: `Microsoft.TemplateEngine.MCP.csproj` (`<Version>`), `server.json` (both `version` fields), and `README.md` (install commands).
+
+## Testing
+
+- Unit tests use **xUnit** + **FakeItEasy** for mocking.
+- `TemplateEngineService` is mocked via `A.Fake<TemplateEngineService>()` in unit tests.
+- Integration tests (in `IntegrationTests.cs`, `EndToEndTests.cs`) use a real template engine instance.
+- Test naming: `MethodName_Scenario_ExpectedBehavior`.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/.../McpFeatureFlags.cs` | Environment-based feature flags (transport, profiles, elicitation) |
+| `src/.../Tools/ToolProfileResponse.cs` | Consistent "tool disabled" JSON responses |
+| `src/.../Host/TemplateEngineService.cs` | Core service wrapping the template engine |
+| `src/.../Telemetry/McpTelemetry.cs` | ActivitySource + Meter for observability |
+| `server.json` | MCP Registry manifest |
+| `.github/copilot-instructions.md` | Instructions for AI agents *using* this tool (not developing it) |

README.md

@@ -1,5 +1,7 @@
 # Microsoft.TemplateEngine.MCP
 
+<!-- mcp-name: io.github.YuliiaKovalova/dotnet-template-mcp -->
+
 An MCP server that lets AI agents work with `dotnet new` templates — search, inspect, preview, and create projects through natural conversation instead of memorizing CLI flags.
 
 Instead of this:
@@ -27,6 +29,8 @@ Your AI agent just says: *"I need a web API with authentication and controllers"
 | `template_create_from_existing` | Analyze a .csproj → generate a reusable template matching repo conventions |
 | `template_compose` | Execute a sequence of templates (project + items) in one workflow |
 | `template_suggest_parameters` | Suggest parameter values with rationale based on cross-parameter relationships |
+| `template_validate` | Validate a local template directory for authoring issues before publishing |
+| `solution_analyze` | Analyze a solution/workspace — project structure, frameworks, CPM status |
 
 📖 [Full tool reference →](docs/tool-reference.md)
 
@@ -35,13 +39,13 @@ Your AI agent just says: *"I need a web API with authentication and controllers"
 ### Zero-install with `dnx` (.NET 10+)
 
 ```bash
-dnx -y DotnetTemplateMCP --version 1.0.0
+dnx -y DotnetTemplateMCP --version 1.1.0
 ```
 
 ### Global tool
 
 ```bash
-dotnet tool install --global DotnetTemplateMCP --version 1.0.0
+dotnet tool install --global DotnetTemplateMCP --version 1.1.0
 ```
 
 ### VS Code / GitHub Copilot
@@ -54,7 +58,7 @@ Add to `mcp.json`:
     "dotnet-templates": {
       "type": "stdio",
       "command": "dnx",
-      "args": ["-y", "DotnetTemplateMCP", "--version", "1.0.0"]
+      "args": ["-y", "DotnetTemplateMCP", "--version", "1.1.0"]
     }
   }
 }
@@ -163,6 +167,32 @@ Chain multiple templates in one call with `template_compose`:
 
 📖 [Architecture & smart behaviors →](docs/architecture.md)
 
+### Tool Profiles (Lite vs Full)
+
+By default, all 13 tools are available. If your agent works better with fewer tools, set the `MCP_TEMPLATE_TOOL_PROFILE` environment variable:
+
+| Profile | Tools | When to use |
+|---------|-------|-------------|
+| `full` (default) | All 13 tools | Full control — advanced workflows, composition, custom templates |
+| `lite` | 5 core tools | Simpler agents that just need to find and create projects |
+
+**Lite profile tools:** `template_from_intent`, `template_instantiate`, `template_inspect`, `template_search`, `template_dry_run`
+
+```json
+{
+  "servers": {
+    "dotnet-template-mcp": {
+      "command": "dotnet-template-mcp",
+      "env": {
+        "MCP_TEMPLATE_TOOL_PROFILE": "lite"
+      }
+    }
+  }
+}
+```
+
+Non-lite tools will return a helpful message explaining they're disabled and how to enable them.
+
 ## Documentation
 
 | Doc | What's in it |

docs/tool-reference.md

@@ -168,6 +168,27 @@ Example:
 
 ---
 
+## `template_validate`
+
+Validate a local template directory for authoring issues before publishing. Checks schema compliance, parameter definitions, constraints, post-actions, and common mistakes.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | Yes | Path to the template directory (containing `.template.config/template.json`), or direct path to `template.json` |
+
+**Validation checks:**
+- Required fields (`identity`, `name`, `shortName`)
+- Identity format and namespace conventions
+- Short name conflicts with dotnet CLI commands
+- Parameter issues: missing datatypes, empty choices, invalid defaults, prefix collisions
+- Computed/generated symbol completeness
+- Post-action and constraint configuration
+- Tag recommendations (language, type)
+
+Returns: `{ valid, errors, warnings, suggestions }`
+
+---
+
 ## `template_suggest_parameters`
 
 Given a template and partial parameter values, suggest reasonable defaults with rationale. Example: `EnableAot=true` → suggests `Framework=net9.0` with explanation.

server.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.YuliiaKovalova/dotnet-template-mcp",
+  "description": "Search, inspect, preview, and create .NET projects from dotnet new templates via AI agents.",
+  "version": "1.1.0",
+  "repository": {
+    "url": "https://github.com/YuliiaKovalova/dotnet-template-mcp",
+    "source": "github",
+    "id": "1159945491"
+  },
+  "packages": [
+    {
+      "registryType": "nuget",
+      "identifier": "DotnetTemplateMCP",
+      "version": "1.1.0",
+      "runtimeHint": "dnx",
+      "runtimeArguments": [
+        {
+          "type": "positional",
+          "description": "Auto-confirm package installation",
+          "isRequired": true,
+          "format": "string",
+          "value": "-y"
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

src/Microsoft.TemplateEngine.MCP/McpFeatureFlags.cs

@@ -33,6 +33,13 @@ internal sealed class McpFeatureFlags
     /// </summary>
     public const string ElicitationEnvVar = "MCP_TEMPLATE_ELICITATION";
 
+    /// <summary>
+    /// Environment variable to select the tool profile.
+    /// Values: "full" (default, all 13 tools), "lite" (5 core tools only).
+    /// Lite mode reduces tool count to minimize agent confusion and context overhead.
+    /// </summary>
+    public const string ToolProfileEnvVar = "MCP_TEMPLATE_TOOL_PROFILE";
+
     /// <summary>
     /// Whether intent resolution tools (template_from_intent, create_from_description) are enabled.
     /// </summary>
@@ -53,6 +60,16 @@ internal sealed class McpFeatureFlags
     /// </summary>
     public bool ElicitationEnabled { get; init; } = true;
 
+    /// <summary>
+    /// The active tool profile. Controls which tools are exposed to the MCP client.
+    /// </summary>
+    public ToolProfile Profile { get; init; } = ToolProfile.Full;
+
+    /// <summary>
+    /// Returns true if the given tool is enabled in the current profile.
+    /// </summary>
+    public bool IsToolEnabled(string toolName) => Profile == ToolProfile.Full || IsLiteProfileTool(toolName);
+
     /// <summary>
     /// Load feature flags from environment variables and command-line arguments.
     /// </summary>
@@ -64,6 +81,7 @@ public static McpFeatureFlags FromEnvironment(string[] args)
             Transport = GetTransportMode(args),
             HttpUrl = Environment.GetEnvironmentVariable(HttpUrlEnvVar) ?? "http://localhost:5005",
             ElicitationEnabled = IsEnabled(ElicitationEnvVar, defaultValue: true),
+            Profile = GetToolProfile(),
         };
     }
 
@@ -75,6 +93,28 @@ public static McpFeatureFlags FromEnvironment()
         return FromEnvironment([]);
     }
 
+    /// <summary>
+    /// Lite profile tools: the 5 most essential tools for typical AI agent workflows.
+    /// </summary>
+    private static bool IsLiteProfileTool(string toolName)
+        => toolName is "template_from_intent"
+            or "template_instantiate"
+            or "template_inspect"
+            or "template_search"
+            or "template_dry_run";
+
+    private static ToolProfile GetToolProfile()
+    {
+        var value = Environment.GetEnvironmentVariable(ToolProfileEnvVar);
+        if (!string.IsNullOrEmpty(value) &&
+            value.Equals("lite", StringComparison.OrdinalIgnoreCase))
+        {
+            return ToolProfile.Lite;
+        }
+
+        return ToolProfile.Full;
+    }
+
     private static TransportMode GetTransportMode(string[] args)
     {
         // Check command-line: --transport http
@@ -125,3 +165,15 @@ internal enum TransportMode
     /// <summary>HTTP transport with streamable HTTP support (for remote, cloud, and multi-tenant deployment).</summary>
     Http,
 }
+
+/// <summary>
+/// Tool profile modes controlling which tools are exposed to the MCP client.
+/// </summary>
+internal enum ToolProfile
+{
+    /// <summary>All 13 tools exposed (default).</summary>
+    Full,
+
+    /// <summary>5 core tools only: template_from_intent, template_instantiate, template_inspect, template_search, template_dry_run.</summary>
+    Lite,
+}

src/Microsoft.TemplateEngine.MCP/Microsoft.TemplateEngine.MCP.csproj

@@ -10,7 +10,7 @@
     <PackageId>DotnetTemplateMCP</PackageId>
     <ToolCommandName>template-engine-mcp</ToolCommandName>
     <IsPackable>true</IsPackable>
-    <Version>1.0.0</Version>
+    <Version>1.1.0</Version>
     <Authors>YuliiaKovalova</Authors>
     <PackageProjectUrl>https://github.com/YuliiaKovalova/dotnet-template-mcp</PackageProjectUrl>
     <RepositoryUrl>https://github.com/YuliiaKovalova/dotnet-template-mcp</RepositoryUrl>

src/Microsoft.TemplateEngine.MCP/Tools/CreateFromExistingTool.cs

@@ -20,6 +20,7 @@ internal sealed class CreateFromExistingTool
         "and content items. Solves the problem of 'dotnet new' creating generic projects that don't match repo conventions.")]
     public static async Task<string> CreateFromExistingAsync(
         TemplateEngineService engineService,
+        McpFeatureFlags featureFlags,
         [Description("Full path to the .csproj file to analyze and use as a template source")] string projectPath,
         [Description("Human-readable name for the generated template (e.g., 'Repo Unit Test Project')")] string templateName,
         [Description("Short name for the template (e.g., 'repo-unittest'). Used with 'dotnet new <shortname>'.")] string? shortName = null,
@@ -28,9 +29,15 @@ public static async Task<string> CreateFromExistingAsync(
         CancellationToken cancellationToken = default)
     {
         using var activity = McpTelemetry.StartToolActivity("template_create_from_existing");
+
         var sw = Stopwatch.StartNew();
         try
         {
+            if (!featureFlags.IsToolEnabled("template_create_from_existing"))
+            {
+                return ToolProfileResponse.DisabledMessage("template_create_from_existing", "Set MCP_TEMPLATE_TOOL_PROFILE=full to generate templates from existing projects.");
+            }
+
             // 1. Analyze the project
             ProjectAnalysis analysis;
             try

src/Microsoft.TemplateEngine.MCP/Tools/SolutionAnalyzeTool.cs

@@ -15,13 +15,19 @@ internal sealed class SolutionAnalyzeTool
     [McpServerTool(Name = "solution_analyze")]
     [Description("Analyze a solution or workspace directory. Returns project structure, target frameworks, CPM status, and NuGet configuration — essential context for template creation decisions.")]
     public static async Task<string> AnalyzeSolutionAsync(
+        McpFeatureFlags featureFlags,
         [Description("Path to a .sln/.slnx file or a directory to scan. Defaults to current directory.")] string? path = null,
         CancellationToken cancellationToken = default)
     {
         using var activity = McpTelemetry.StartToolActivity("solution_analyze");
         var sw = Stopwatch.StartNew();
         try
         {
+            if (!featureFlags.IsToolEnabled("solution_analyze"))
+            {
+                return ToolProfileResponse.DisabledMessage("solution_analyze", "Set MCP_TEMPLATE_TOOL_PROFILE=full to analyze solution structure.");
+            }
+
             string resolvedPath = path ?? Environment.CurrentDirectory;
 
             // Find .sln file

src/Microsoft.TemplateEngine.MCP/Tools/TemplateComposeTool.cs

@@ -16,13 +16,19 @@ internal sealed class TemplateComposeTool
     [Description("Execute a sequence of template operations (project + item templates) in order. For example, create a MAUI app then add specific pages/views. Each step can reference a different template. If a template is not installed, it will be auto-resolved from NuGet.")]
     public static async Task<string> ComposeTemplatesAsync(
         TemplateEngineService engineService,
+        McpFeatureFlags featureFlags,
         [Description("JSON array of steps. Each step: {\"templateName\": \"...\", \"name\": \"...\", \"outputPath\": \"...\", \"target\": \"relative/path\", \"parametersJson\": \"{...}\"}. The first step creates the project; subsequent steps add items. If 'target' is set on later steps, it's resolved relative to the first step's output.")] string stepsJson,
         CancellationToken cancellationToken = default)
     {
         using var activity = McpTelemetry.StartToolActivity("template_compose");
         var sw = Stopwatch.StartNew();
         try
         {
+            if (!featureFlags.IsToolEnabled("template_compose"))
+            {
+                return ToolProfileResponse.DisabledMessage("template_compose", "Use template_instantiate to create one project at a time.");
+            }
+
             List<ComposeStep>? steps;
             try
             {