Extension SDK Core & MCP Framework — Critical Improvements

[jongio]

Extension SDK Core & MCP Framework — Critical Items

This work unit covers all P0 (Critical) proposals from the parent issue. These are the foundational framework improvements that eliminate the most boilerplate and benefit every extension author.

---

Extension SDK Base

P0-1: Extension Base Command Builder

Provide NewExtensionRootCommand() that auto-registers azd's global flags, sets up OpenTelemetry trace context, calls WithAccessToken(), and provides a structured ExtensionContext.

Current duplication (identical code in every extension):

• azd-exec/main.go L21-41, L189-194 — flag variables + registration
• azd-app/main.go L17-23, L83-87
• azd-copilot/main.go L22-37, L138-141
• azd-rest/root.go L19-35, L77-91

Identical trace context extraction in every extension:

• azd-exec/main.go L112-118
• azd-rest/root.go L65-71
• azd-copilot/main.go L80-86

P0-2: Global Flags Propagation via Environment Variables

Modify runner.go and middleware/extensions.go to export AZD_DEBUG, AZD_NO_PROMPT, AZD_CWD, AZD_ENVIRONMENT when spawning extensions.

Framework only passes 4 env vars today:

• azure-dev/cmd/middleware/extensions.go L127-139
• azure-dev/pkg/extensions/runner.go L50-71

P0-3: BaseServiceTargetProvider with No-Op Defaults

Add BaseServiceTargetProvider so extensions embed it and only override needed methods.

• azure-dev ServiceTargetProvider interface (6+ required methods)
• azd-app stub implementation L17-111 — mostly no-ops

P0-4: Standard Command Scaffolding (listen, metadata, version, mcp)

Provide NewListenCommand(), NewMetadataCommand(), NewVersionCommand(), NewMCPServeCommand().

Identical listen commands:

• azd-exec L13-30 · azd-rest L11-30 · azd-app L18-30 · azd-copilot L17-30

Identical metadata commands:

• azd-exec L14-29 · azd-rest L13-28 · azd-app L11-30 · azd-copilot L15-30

Identical version commands:

• azd-exec L11-12 · azd-rest L10-11 · azd-app L27-28 · azd-copilot L27-28

---

MCP Server Framework

P0-5: MCP Server Builder with Middleware

Wrap mark3labs/mcp-go with rate limiting, path validation, and security middleware applied automatically.

Rate limiter duplicated in every MCP extension:

• azd-exec/mcp_ratelimit.go L7 — var globalRateLimiter = azdextutil.NewRateLimiter(10, 1.0)
• azd-rest/mcp.go L24 — same pattern
• azd-app/mcp_ratelimit.go L63 — custom TokenBucket (doesn't even use shared impl)
• azd-core RateLimiter impl L9-56

Manual rate limit checks in every tool handler:

• azd-exec/mcp.go L115, L204, L267, L314 — if !globalRateLimiter.Allow() repeated 4 times

P0-6: Typed MCP Argument Parsing

Add ParseToolArgs(), RequireString(), OptionalBool(), OptionalInt().

Duplicate arg parsing helpers:

• azd-exec/mcp.go L360-376 — local getArgsMap() + getStringParam()
• azd-core/azdextutil/mcp.go L12-30 — shared GetArgsMap() + GetStringParam() (azd-exec doesn't use these)

P0-7: MCP Result Marshaling Helpers

Add MCPTextResult(), MCPJSONResult(), MCPErrorResult().

• azd-exec/mcp.go L385-408 — custom marshalExecResult() + marshalToolResult()

P0-8: MCP Security Middleware

Centralize SSRF protection, path validation, header redaction as pluggable middleware.

Hardcoded blocklists in azd-rest:

• azd-rest/mcp.go L34-66 — blockedHeaders, blockedHosts, blockedCIDRs
• azd-rest/mcp.go L84-134 — isBlockedIP(), isBlockedURL() with DNS + CIDR checking

Path validation in azd-core:

• azd-core/security/security.go L33, L175 — ValidatePath(), ValidatePathWithinBases()

---

Estimated Impact

• ~300-500 lines of boilerplate eliminated per extension
• All 8 P0 proposals addressed
• Every current and future extension benefits

[jongio]

Status Report: Extension SDK Core & MCP Framework — Critical Improvements

Executive Summary

The Extension SDK improvements initiative (#6853) has made significant progress. All P0 work is complete and merged, P1 core primitives are merged, and the remaining P1-P3 work has been consolidated into a single PR for streamlined review.

✅ Completed Work

PR	Issue	Scope	Status	Merged
#6856	#6855	P0: All 8 SDK helper proposals (environment, user config, credentials, HTTP client, project info, prompt, Azure ops, AI helpers)	Merged	Feb 26
#6954	#6944	P1 Core: Token provider, scope detector, resilient HTTP client, pagination	Merged	Mar 6
#6835	—	azdext.Run lifecycle improvements	Merged	—

Downstream adoption confirmed:

• azd-app extension (PR #145): Deleted 574 lines of custom rate limiter code, replaced with SDK primitives
• azd-core extension (PR Update Walk to WalkDir #22): Deprecated stopgap helpers in favor of SDK-provided ones

🚧 In Progress

The remaining 5 issues have been consolidated from 5 stacked draft PRs into a single PR for cleaner review:

Issue	Priority	Scope
#6945	P1	Key Vault resolver + config helpers
#6946	P2	Output + structured logging
#6947	P2	Security validation + SSRF guard
#6948	P3	Runtime utilities (shell, file, process, TUI, tool discovery)
#6949	—	Post-#6856 cleanup (context ownership, package boundaries)

Consolidated PR: #7025 (51 files, +9,900/-733, all in cli/azd/pkg/azdext/)

Why consolidated: Analysis showed 64% of commits in the stacked PRs were cross-cutting fixes that touched files across multiple issue scopes. Consolidating eliminates 3 merge/rebase cycles and gives reviewers a coherent single-pass review. PR #6954 was +3,498 lines and reviewed/merged smoothly — this is ~3× that but all in a single package with zero cross-package coupling.

📝 Open Items

Issue	Status	Owner
#6863	Documentation	@kristenwomack (milestone: On Deck)
#6853	Parent tracking issue	Remaining sub-proposals tracked there

Next Steps

1. Immediate: Consolidated PR up for review — requesting @wbreza, @rajeshkamal5050
2. After merge: Close issues Extension framework P1 integration helpers (P1-5..P1-6) #6945-Extension framework post-6856 cleanup (context ownership and package boundaries) #6949 automatically via PR
3. Documentation: Track Update extension framework docs #6863 progress with @kristenwomack
4. Future: Remaining P3+ proposals from Proposal: Extension Framework Improvements from Real-World Extension Development #6853 can be addressed in subsequent iterations