Azure TypeSpec Author

MCP Tools

Prerequisite: azure-sdk-mcp server must be running.

Constraints

• Always follow the full workflow — even seemingly simple changes (e.g. adding a default value) can require complex versioning decorator changes. Never skip steps.
• Mandatory for ALL .tsp edits — even a single ? change can be breaking.
• Minimal, scoped edits — only change what the request requires.
• Always validate — run every steps in validation after every edit.
• Always cite references — provide links that justify the approach.
• Follow the authoring plan exactly — code changes in Step 4 MUST follow the authoring plan generated in Step 3. Do not deviate by referring to existing code patterns in the TypeSpec project; the authoring plan is the single source of truth for what to change.

Workflow

Classify → Intake → Plan → Apply → Validate

Progress Checklist

Copy and update as you progress:

• Step 1: Analyzed project & classified as: ___
• Step 2: Collected intake inputs
• Step 3: Retrieved authoring plan
• Step 4: Applied changes
• Step 5: Validated with TypeSpec validation and tsp compile .

Step 1: Analyze & Classify

Follow analyze project & classify task.

Classify as exactly one:

State your classification explicitly before proceeding.

Step 2: Intake

Collect inputs needed for the change. Branch by task type:

• API Version Evolution → Follow API version evolution reference — Step 2.
• General Authoring → Follow intake guide.

Step 3: Retrieve Authoring Plan

Check your classification from Step 1, then branch:

• API Version Evolution → Follow API version evolution reference — Step 3. MUST NOT call azsdk_typespec_generate_authoring_plan.
• General Authoring → MUST invoke azure-sdk-mcp:azsdk_typespec_generate_authoring_plan with:

  Parameter	Value
  request	User request (verbatim)
  additionalInformation	All content gathered from Steps 1–2 (intake analysis, user answers, relevant .tsp code read from the project), including any case-specific Defaults noted in Step 2.2
  typeSpecProjectRootPath	TypeSpec project root path

  
  Do not proceed without an authoring plan from this tool.

Step 4: Apply Changes

Confirm uncertainties with the user, then make minimal .tsp edits.

• API Version Evolution → Apply the plan from Step 3.
• General Authoring → Apply the authoring plan from Step 3.

Step 5: Validate

See validation guide for sub-steps. You must run TypeSpec validation (5.1), tsp compile . (5.2), and example verification (5.3, API Version Evolution only).

Reference Files

Examples

• "Add a new preview API version 2026-01-01-preview for widget resource manager"
• "Bump to stable version 2026-01-01 for Microsoft.Widget"
• "Add an ARM resource named Asset with CRUD operations"
• "Add a new property to the Widget model"

Troubleshooting

• TypeSpec validation fails — display all errors, provide fix suggestions, re-run validation.
• API Version Evolution — use the versioning guide URLs in the version evolution reference; do not call the authoring plan tool.