Azure TypeSpec Author
MCP Prerequisites
Requires azure-sdk-mcp server with TypeSpec authoring and validation tools.
MCP Tools
| Tool | Purpose |
|---|---|
azsdk_typespec_generate_authoring_plan | Generate grounded authoring plan |
azsdk_run_typespec_validation | Validate TypeSpec compilation + lint |
Principles
- Mandatory for ALL
.tspedits — even a single?change can be breaking. - Minimal, scoped edits — only change what the request requires.
- Always validate — run
azsdk_run_typespec_validationafter every edit. - Always cite references — provide links that justify the approach.
Task Classification
Classify every request into exactly one of the two types below before proceeding.
- API Version Evolution = adding a brand-new API version string (e.g.
2025-06-01-preview) to the service. This is *only* about creating a new version entry and carrying over / excluding features. It is not about adding@added/@removeddecorators to individual properties or operations within an existing version — that falls under General Authoring. - General Authoring = everything else that modifies
.tspfiles.
| Type | Description | Examples |
|---|---|---|
| API Version Evolution (ARM only) | Adding a new preview or stable API version to an existing ARM service. Data-plane API version evolution is not fully supported yet. | "Add a new preview API version 2026-01-01-preview for widget resource manager" |
| General Authoring | Any other TypeSpec authoring task that modifies .tsp files | "Add an ARM resource named Asset with CRUD operations" |
Steps
All tasks follow a 5-step workflow. Steps 2–3 branch by task type; the rest are shared.
- Analyze Project — Follow the project analysis guide to collect project context and determine task type.
- Intake & Clarification
- *API Version Evolution:* determine the versioning scenario from Step 1, use agentic search in the document with the scenario URL below to collect information from user. Be sure to use a user-friendly way to collect required inputs from user. e.g., list the existing features (resources, operations, properties) from the latest version and then ask the user which to carry over or exclude, instead of asking for raw input. Latest Target URL to fetch preview preview https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/02-preview-after-preview/ preview stable https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/03-stable-after-preview/ stable preview https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/04-preview-after-stable/ stable stable https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/05-stable-after-stable/ - *General Authoring:* follow intake guide.
- Retrieve Solution
- *API Version Evolution:* search the downloaded guide content for implementation steps via agentic search and generate solution. No MCP tool call needed. - *General Authoring:* invoke azsdk_typespec_generate_authoring_plan MCP tool with the following parameters: 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) typeSpecProjectRootPath TypeSpec project root path Do not proceed without a grounded plan from this tool.
- Apply Changes — Confirm uncertainties with user, make minimal
.tspedits, prefer official templates from retrieved context. - Validate — Follow the validation guide.