dotnet-template-mcp: Instructions file for Codex

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

dotnet build
dotnet test

• Targets net8.0 and 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/DotnetTemplateMcp.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/DotnetTemplateMcp/Tools/:

[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);
        }
    }
}