mcp-rest-tool-authoring

name	mcp-rest-tool-authoring
description	Maintain the reusable `Mithril.MasTools` source-generated tool-authoring model and its consumer-facing guidance. Use when a request asks to add, modify, scaffold, refactor, or document abstractions, generator behavior, host integration, metadata, validation, or auth conventions for tools exposed through REST, MCP, or CLI.

MCP REST CLI Tool Authoring

Overview

This repository owns the reusable Mithril.MasTools package family, not a concrete service with local tool handlers. Use this skill when changing the shared authoring model that consumer repositories follow: abstractions, generator behavior, host integration, validation, auth conventions, or the documentation that explains those patterns.

When provider contracts differ materially, prefer one handler and request DTO per contract shape in consumer repositories. Keep specialization at the transport boundary and normalize in the consumer service layer unless the business workflow itself also differs materially.

Workflow

1. Read references/repo-patterns.md before editing code. Read docs/specs/AGENT_ENDPOINT_METHODOLOGY.md too when provider contract shape or agent-facing tool choice matters.
2. Inspect the current package surfaces with rg before changing conventions:
   • Mithril.MasTools.Abstractions/
   • Mithril.MasTools.Generators/
   • Mithril.MasTools.AspNetCore/
   • Mithril.MasTools.AspNetCore.Security/
   • Mithril.MasTools.CliHost/
3. Decide whether the request needs:
   • shared contract changes in Mithril.MasTools.Abstractions
   • generator behavior changes in Mithril.MasTools.Generators
   • host integration changes in Mithril.MasTools.AspNetCore* or Mithril.MasTools.CliHost
   • documentation or skill updates that consumer repositories rely on
   • auth convention updates
4. Implement in this order when possible:
   • contract or metadata primitives
   • generator behavior
   • host integration changes
   • docs, skills, notes, and decision records
   • validation
5. Keep transport ownership clean:
   • consumers author handlers and DTOs
   • the generator owns emitted REST, MCP, CLI, and DI surfaces
   • host packages stay optional and generic
6. Validate with:
   • dotnet build Mithril.MasTools.slnx -c Release
   • pwsh -File scripts/pack-release-packages.ps1 -Version 0.1.0-local

DTO Rules

• Prefer DTO shapes that remain generator-safe across shared assemblies: either a public constructor matching public properties or a parameterless constructor with writable public properties.
• Use Mithril.MasTools.EmptyToolRequest for parameterless tools.
• Split DTOs by materially different provider contract shape instead of collecting provider-only optional fields in one generic request.
• Add DescriptionAttribute to every request property so MCP and Swagger/OpenAPI share the same parameter description source.
• Add validation coverage to every request property via ValidationAttribute, enum typing, or AllowAnyValueAttribute.
• For positional record requests, keep validation metadata on the constructor parameter ([param: Required], [param: Range], etc.) and transport/docs metadata on the property target when needed ([property: Description]).
• Enum request properties serialize and bind as enum names, not numeric ordinals; clients may vary casing on input but should still send the textual enum name.
• Enum request properties automatically surface their allowed textual values and any enum-member DescriptionAttribute text on both MCP and REST docs.
• Missing request-property descriptions trigger generator warning TOOL003.
• Missing request-property validation coverage triggers generator error TOOL004.
• Custom validation can be added through IToolRequestValidator<TRequest>; those validators are auto-registered by the generator when implemented in a consumer tool assembly.

Handler Rules

• Consumer handlers should live in a consumer tool assembly, not in this repository.
• Consumer handlers implement IToolHandler<TRequest, TResponse> and use [Tool], DescriptionAttribute, and auth attributes as the stable authoring contract.
• Handler DescriptionAttribute text should explain what the tool does and when to choose it; it now feeds CLI discovery and optional generated Agent Skills as well as REST/MCP docs.
• For CLI-exposed tools, prefer ToolExampleAttribute on the handler. Keep PayloadJson as the shared structured sample, and set CliArguments when you want to pin the exact canonical command shown by example <tool>.
• Missing handler descriptions trigger generator warning TOOL007.
• When this repository changes handler conventions, update the skill, package docs, notes, and decision records in the same phase.
• Keep one tool per file and one primary responsibility per handler in consumer guidance.

Auth Rules

• Public tools should use [AllowAnonymous] explicitly.
• API-key protected tools should use [Authorize(Policy = ToolAuthorizationPolicies.AuthenticatedTool)] when the consumer host opts into Mithril.MasTools.AspNetCore.Security.
• If auth conventions change, update package docs, notes, and decision artifacts together.

Validation Handoff

• Confirm generated transports compile by building the solution, not by editing generated files.
• Keep docs and skills aligned with actual package paths and public APIs.
• If the task introduces a durable tool-authoring convention, update the relevant note or decision entry.