azure-typespec-author

name	azure-typespec-author
license	MIT
metadata	{"version":"1.0.0"}
description	Authors and modifies Azure TypeSpec (.tsp) API specifications. USE FOR: any TypeSpec/tsp change — api versions (add, bump, preview, stable, promote), resources, operations, models, properties, decorators, visibility, constraints, breaking changes, LRO, suppressions, operationId, spread model. Covers ARM resource-manager and data-plane services. DO NOT USE FOR: SDK generation, releasing SDK packages, or single MCP tool calls. INVOKES: azure-sdk-mcp:azsdk_typespec_generate_authoring_plan, azure-sdk-mcp:azsdk_run_typespec_validation.
compatibility	azure-sdk-mcp server with azsdk_typespec_generate_authoring_plan and azsdk_run_typespec_validation tools

Azure TypeSpec Author

MCP Tools

Tool	Purpose
azure-sdk-mcp:azsdk_typespec_generate_authoring_plan	Generate grounded authoring plan (General Authoring only)
azure-sdk-mcp:azsdk_run_typespec_validation	Validate TypeSpec

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:

Task Type	When	azsdk_typespec_generate_authoring_plan
API Version Evolution	Adding a new preview or stable API version to an existing ARM service. (ARM only)	MUST NOT call
General Authoring	Any other .tsp change (resources, operations, models, properties, etc.)	MUST call

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

File	Purpose
analyze-project-and-classify-task.md	Step 1: project analysis + classification
api-version-evolution.md	Steps 2–4 for API Version Evolution tasks
general-authoring-intake.md	Step 2 for General Authoring tasks
agentic-search.md	Procedure for fetching external docs
validation.md	Step 5: validation sub-steps

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.