| 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 | {"requires":"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: 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:
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.
