mirror of
https://github.com/rohitg00/ai-engineering-from-scratch.git
synced 2026-10-02 01:54:39 +08:00
Rohit Ghumare
9f06b4b740
* feat(mcpa): add MCPA program, track blueprint, and source ledger
Start the Model Context Protocol Associate certification prep, mirroring the
Claude certification system. Adds the program manifest, the mcpa-f track with
the five published domains and weights (Fundamentals 16, Architecture 14,
Interactions 26, Security 24, Use Cases 20) and exam mechanics, and a source
verification ledger that maps every exam fact to the official certification
page, the launch announcement, and the MCP 2026-07-28 specification with the
retrieval date. Objectives are original, derived from the published
sub-competency names and the specification.
* feat(mcpa): add the MCP fundamentals lesson and figure runtime
First MCPA cert lesson, mirroring the Claude certification lesson contract: a
concept-first explainer of the integration problem MCP solves, the four roles,
and the handshake, discovery, and invocation flow, with a stdlib JSON-RPC mock
(no SDK, no network), five-plus tests, a six-question quiz, a field-brief
artifact, and a registered host-client-server figure. Aligned to MCP 2026-07-28.
* feat(certifications): make cert audit + debias provider-aware
Discover providers via certifications/*/program.json and run the same
contract per provider instead of hardcoding certifications/claude.
- audit_certifications.py: PROVIDERS registry + use_provider(slug);
check_public_pages runs once, run_provider_audit(audit, slug) per
provider; LESSON_REF_PREFIX / PROVIDER_ENTITY / PROVIDER_AI_NATIVE_SURFACE
replace the former claude-only literals; AI-native-surface check gated
per provider.
- debias_certification_questions.py: glob certifications/*/lessons and
certifications/*/assessments.
- claude verdict unchanged: 33 lessons, 8 assessments, 295 questions, 0 issues.
- balance mcpa lesson 01 quiz answer positions and option lengths.
* feat(certifications): add MCPA cert README and generalize route-count regex
- certifications/mcpa/README.md: route table (MCPA, 10 lessons), blueprint
weights, AI-tutor onboarding, GitHub lesson index, non-affiliation notice;
states the official item count and passing score are not published and the
90-vs-120 minute source discrepancy.
- audit_certifications.py: widen the README route-count regex from CC-only to
any uppercase exam code so MCPA is parsed; claude codes still match and the
claude verdict stays 0 issues.
* feat(certifications): build MCPA track lessons, figures, and wiring
- Nine new lessons (00, 02-09) covering all five MCPA domains. Each ships a
concept-first doc, a standard-library MCP mock in code/main.py, a Python
test suite (88 lesson tests total, all passing), a six-question quiz, a
reusable output artifact, and a mechanism figure.
- site/figures-mcpa-certifications.js: register all ten lesson figures
(mcpa-00 through mcpa-09), each a themed inline-SVG diagram; render-checked.
- tracks/mcpa-f.json: wire the ten lessons to their domains and roles.
- prerequisites.json: linear lesson dependency chain over all ten lessons.
- audit_certifications.py: enforce the mcpa expectedFigures map.
* feat(certifications): add MCPA assessments and AI-native tutor surface
Completes the MCPA certification track. Full audit is green: 43 lessons,
10 assessments, 380 questions, 0 issues; the Claude verdict is unchanged
(33 lessons, 8 assessments, 295 questions).
- assessments/mcpa-f/diagnostic.json (25 questions) and mock-01.json (60
questions) with the blueprint domain mix (10/8/16/14/12); every question
maps to a declared domain objective and cites an existing lesson for
remediation. Declared in tracks/mcpa-f.json.
- debias pass balances answer positions across the ten lesson quizzes and
the two assessments.
- skills/mcpa-certification (SKILL.md + agents/openai.yaml) and its
.claude/skills mirror: an AI-native tutor for the MCPA route, mirroring
the Claude certification tutor.
- certifications/mcpa/GETTING_STARTED.md: the GitHub learner guide.
- curriculum.yml: run certification lab tests and demos for every provider,
not just Claude.
- README.md: MCPA onboarding section and quick-start row.
* feat(certifications): add MCP 2026-07-28 protocol brief and wire-shape checker
The MCPA exam is aligned to the 2026-07-28 revision, which made MCP
stateless (SEP-2575, SEP-2567): no initialize handshake, no sessions,
per-request _meta version and capabilities, mandatory server/discover,
Multi Round-Trip Requests instead of server-initiated requests (SEP-2322),
a required resultType, subscriptions/listen, cacheable list results
(SEP-2549), and a new error-code allocation policy.
- certifications/mcpa/research/mcp-2026-07-28-brief.md: the protocol
source of truth for every MCPA lesson and question, read from the
primary specification pages, schema.ts, the extension pages, and the
SEPs, with a table of exam traps where legacy-era beliefs are now wrong.
- scripts/check_mcpa_wire.py: imports each MCPA lesson's transcript() and
enforces the 2026-07-28 wire invariants (required _meta fields,
resultType, cache hints on the six cacheable operations, MRTR retry
rules, subscription ids on listen streams, header and body agreement,
the error-code allocation policy) and rejects legacy methods such as
initialize unless a lesson marks them as compatibility examples.
- scripts/test_check_mcpa_wire.py: 16 tests for the checker's rules.
* refactor(certifications): restructure the MCPA track for the stateless 2026-07-28 protocol
The first MCPA build taught the legacy initialize handshake as current,
answered unknown tools with -32601 and schema-invalid arguments with
-32602, and allocated custom errors in the legacy -32000..-32019 range.
MCP 2026-07-28 removed the handshake and sessions (SEP-2575, SEP-2567),
made input validation a tool execution error (SEP-1303), and partitioned
the server-error range into a legacy block and an MCP-reserved block.
- remove the nine lessons and two assessments built on the legacy model
- rewrite the 18 domain objectives against 2026-07-28: the stateless
core, discovery and capability negotiation, Multi Round-Trip Requests,
subscriptions, caching, extensions, and the deprecation lifecycle
- lay out a 34-lesson route across the five domains with a prerequisite
chain and the expected figure for each lesson
- link all 17 phase 13 MCP lessons as deep dives
* feat(mcpa): integration-problem lesson on the stateless core
- one client discovers and calls two unrelated servers using per-request
_meta (protocolVersion, clientCapabilities, clientInfo) and
server/discover with cache hints, with no handshake or session
- N times M versus N plus M integration arithmetic
- the two error channels: an unknown tool is a -32602 protocol error, a
missing argument is an isError tool execution error the model can fix
(SEP-1303)
- UnsupportedProtocolVersion -32022 carrying data.supported and
data.requested
- transcript() passes scripts/check_mcpa_wire.py; this lesson is the
structural exemplar for the rest of the track
* feat(mcpa): discovery and capability negotiation lesson
- server/discover as the only discovery call a server must implement:
DiscoverResult with supportedVersions, capabilities, instructions,
serverInfo, and CacheableResult hints (ttlMs, cacheScope)
- server capabilities are cached per server; client capabilities are
declared fresh on every request in _meta
- MissingRequiredClientCapability (-32021) with data.requiredCapabilities
when a tool needs elicitation the request did not declare
- UnsupportedProtocolVersion (-32022) then a retry with a supported
version and a new request id; era is message shape, not version string
- unknown tool (-32602) versus unknown method (-32601)
* feat(mcpa): stateless core lesson
- statelessness as a protocol invariant (SEP-2575): every request carries
its own version and capabilities, no initialize, no session
- two replicas behind a round-robin router serve interleaved requests
from one shared store, so any replica answers any request
- cross-request state through opaque server-minted handles (SEP-2567):
authorized per call, bounded lifetime, expiry and foreign-principal
use returned as isError tool execution errors
- list results identical across connections; a request without the
required _meta fields rejected with -32602
* feat(mcpa): hosts, clients, and servers topology lesson
- one client per server inside the host, with local stdio and remote
Streamable HTTP servers and trust following process and network
boundaries
- server features (tools, resources, prompts, completion) versus client
features (elicitation; sampling and roots deprecated) and the control
model: model-controlled tools, application-driven resources,
user-controlled prompts
- host aggregation across servers: tool-name collisions resolved by
server-id prefixing, serverInfo.name never used as a routing key
because it is self-reported and not unique
- capability-gated discovery: no tools/list against a server that did
not declare the tools capability
* feat(mcpa): exam strategy lesson for the 34-lesson route
- blueprint-weighted study allocation and weighted readiness (a heavy
domain moves the estimate more than a plain average)
- exam mechanics from the source ledger, including the 90-minute page
value versus the 120-minute launch announcement
- a reading strategy for legacy-era distractors: the initialize
handshake, sessions, and -32601 for an unknown tool
- the full 34-lesson route with its domain tags, validated so every
lesson and every domain is covered; the capstone spans all five
* feat(mcpa): tool schema and structured content lesson
- tool definition fields and naming rules (1 to 128 characters of
A-Za-z0-9_-., unique per server, aggregator prefixing)
- JSON Schema 2020-12 as the default dialect (SEP-1613), any 2020-12
keyword allowed (SEP-2106), and the recommended no-parameter schema
- network $ref never auto-dereferenced; the registration path refuses it
- outputSchema with structuredContent plus a serialized text mirror
- schema-invalid arguments returned as isError tool execution errors
(SEP-1303); -32602 kept for unknown tools and missing _meta, with the
legacy behavior shown only as a labeled counterexample
* feat(mcpa): JSON-RPC envelope and _meta lesson
- the four message shapes under MCP: requests with a non-null unique id,
results that must carry resultType, errors, and id-less notifications
that are never answered; no batching
- resultType semantics: complete, input_required, unknown values
invalid, absent treated as complete for earlier servers
- _meta key grammar (optional reverse-DNS prefix plus name) and the
reserved-prefix rule on the second label: io.modelcontextprotocol and
dev.mcp reserved, com.example.mcp not
- the reserved keys, including the OpenTelemetry traceparent, tracestate,
and baggage exception (SEP-414)
- a request missing protocolVersion or clientCapabilities rejected with
-32602, shown next to three labeled malformed messages
* feat(mcpa): reading server manifests lesson
- review a server/discover result, a tools/list page, and a registry
server.json before any tool is called
- tool annotation defaults applied when omitted (readOnlyHint false,
destructiveHint true and only meaningful when not read-only,
idempotentHint false, openWorldHint true), treated as untrusted hints
- x-mcp-header rules: HTTP token syntax, case-insensitive uniqueness, no
number types, never on secrets
- cacheScope as a sharing hint, not access control; instructions as
self-reported text that can try to steer the model
- reverse-DNS registry namespaces tied to verified owners
- a manifest linter that flags six defects in a careless server and none
in a clean one
* feat(mcpa): reading the specification lesson
- how the 2026-07-28 specification is organized and the floor every
implementation must support (base protocol, versioning, message
patterns) versus optional components
- RFC 2119 and RFC 8174 keyword strength, including the capitals rule
- schema.ts as the source of truth and schema.json as generated output
- revision states (Draft, Current, Final) versus feature states (Active,
Deprecated, Removed) under the lifecycle policy (SEP-2596): a 12-month
minimum window measured from the deprecating revision's release, and
the earliest removal on or after it
- JSON-RPC batching (added 2025-03-26, removed 2025-06-18) as the
reversal the lifecycle policy was written to prevent
- tracing changelog entries back to their SEPs
* feat(mcpa): resources primitive lesson
- resources/list, resources/read, and resources/templates/list with an
RFC 6570 template, text and base64 blob contents, and a directory read
returning several contents
- resource not found as -32602 with data.uri (SEP-2164), never -32002 and
never an empty contents array
- URI scheme choice: https only when the client can fetch directly;
file, git, or a custom scheme otherwise
- traversal-safe resolution of file URIs so a path containing ".." can
never escape the served root
- cache hints on every cacheable result, with a private cacheScope for
user-specific content
* feat(mcpa): prompts and argument completion lesson
- prompts as user-controlled templates: prompts/list with pagination and
cache hints, prompts/get substituting arguments into messages that can
carry resource links
- unknown prompt, missing required argument, and invalid cursor all
reported as -32602
- completion/complete for ref/prompt and ref/resource references, with
context.arguments narrowing later suggestions
- the 100-value cap with total and hasMore, exercised against a real
catalog larger than the cap
* feat(mcpa): error handling lesson
- protocol errors versus tool execution errors (SEP-1303): an unknown
tool stays -32602, invalid or missing arguments return isError results
the model can correct
- MCP-reserved codes with their data shapes: HeaderMismatch -32020,
MissingRequiredClientCapability -32021 (data.requiredCapabilities),
UnsupportedProtocolVersion -32022 (data.supported, data.requested)
- the 2026-07-28 allocation policy enforced in code: a guard refuses the
legacy -32000..-32019 block, retired -32002 and -32042, and undefined
reserved codes before any response is built
- HTTP status mapping only where the specification states one (400,
404, 202, 401, 403, 405); statuses the spec leaves open are marked so
* feat(mcpa): client registration and identity lesson
- registration priority: pre-registered credentials, Client ID Metadata
Documents when the authorization server advertises support,
deprecated Dynamic Client Registration, then asking the user
- CIMD validation: an HTTPS client_id with a path, exact client_id match,
required fields, and redirect URI checks (SEP-991)
- application_type native versus web for DCR clients
- credentials keyed by issuer and never reused across authorization
servers; re-registration when the authorization server changes
- per-client consent at a proxy to prevent the confused-deputy attack
- the OAuth Client Credentials and Enterprise-Managed Authorization
extensions for machine-to-machine and IdP-governed access
* feat(mcpa): deprecated client features lesson
- roots, sampling, and logging deprecated by SEP-2577 but still valid in
2026-07-28: roots/list and sampling/createMessage travel as MRTR
inputRequests, gated by declared client capabilities (-32021 when
missing)
- per-request io.modelcontextprotocol/logLevel with notifications/message
only on that request's own stream, and -32602 for an unknown level
- removed versus deprecated: logging/setLevel and
notifications/roots/list_changed are gone (SEP-2575), shown only as a
labeled legacy contrast
- earliest removal computed from the 12-month window, with migration
paths for each feature, DCR, includeContext, and HTTP+SSE
* feat(mcpa): multi round-trip requests and elicitation lesson
- MRTR replacing server-initiated requests (SEP-2322): an input_required
result with inputRequests and requestState, then a retry with a new id,
inputResponses, and the state echoed exactly
- requestState protected with an HMAC that binds the principal, a short
expiry, a digest of the originating request, and a single-use nonce
- tampering, expiry, cross-principal replay, and a retargeted retry all
rejected before any side effect
- form-mode elicitation with accept, decline, and cancel; URL mode for
out-of-band sensitive steps (SEP-1036); a client without the
elicitation capability refused with -32021
* feat(mcpa): risk and safety controls lesson
- a threat model mapped to the clause that mitigates each threat: tool
poisoning, prompt injection through results, rug pulls, tool
shadowing, confused deputy, token passthrough, requestState tampering,
SSRF through CIMD fetches and network $ref, DNS rebinding, malicious
icons, and supply-chain drift
- a gateway that pins tool definitions by hash and holds a changed
definition for review, quarantines descriptions carrying injected
instructions, refuses network $ref, blocks token passthrough, and
enforces a per-tool rate limit
- policy refusals returned as isError tool results, never as invented
codes in the reserved -32000..-32099 range
* feat(mcpa): tools primitive lesson
- tools/list with opaque cursors (an empty-string cursor still means more
pages), cache hints, and results identical across connections
- CallToolResult: content, structuredContent, and isError defaulting to
false
- every content block type (text, image, audio, resource_link, embedded
resource) with audience, priority, and lastModified annotations; an
embedded resource's annotations sit beside resource, per schema.ts
- tool annotation defaults (readOnlyHint false, destructiveHint true,
idempotentHint false, openWorldHint true) treated as untrusted hints
- listChanged through subscriptions/listen, from acknowledgment to
notifications/tools/list_changed to a fresh tools/list
* feat(mcpa): notifications, subscriptions, and cancellation lesson
- subscriptions/listen replacing resources/subscribe and the HTTP GET
stream: the notification filter, the acknowledgment as the first
message, and subscriptionId equal to the listen request id so several
subscriptions can be demultiplexed
- stream notifications (list_changed, resources/updated) versus
request-scoped progress and message notifications that never travel on
a listen stream
- progress tokens with strictly increasing progress
- cancellation per transport: closing the SSE stream on HTTP,
notifications/cancelled on stdio; the server sends that notification
only to tear down a listen stream; graceful closure and late-message
races
- a fresh subscriptions/listen after a stdio reconnect
* feat(mcpa): transports and HTTP header contract lesson
- stdio: newline-delimited framing with embedded newlines rejected,
stdout reserved for MCP messages, stderr for logs, cancellation by
notification, shutdown by closing stdin
- Streamable HTTP without sessions: one POST endpoint, JSON or
per-request SSE responses, 202 for notifications, 405 for GET and
DELETE, no resumability
- Origin validation with 403 and localhost binding against DNS rebinding
- the header contract (SEP-2243): MCP-Protocol-Version, Mcp-Method, and
Mcp-Name mirrored from the body, x-mcp-header parameters as
Mcp-Param-{Name}, and base64 sentinel encoding checked against the
specification's own worked examples
- a header-body mismatch rejected with 400 and HeaderMismatch -32020
* feat(mcpa): trust zones lesson
- five trust zones in one exchange: user and host, client, server,
upstream systems, and the model
- every untrusted input that reaches model context labeled and
quarantined: tool descriptions, annotations, icons, results, and
resource contents
- clientInfo and serverInfo treated as self-reported display data
- multi-server isolation: an instruction embedded in one server's result
cannot trigger a call on another server
- annotations from an untrusted server fall back to safe defaults;
icon URIs other than https or data rejected
- local server launch commands accepted only from the host's own
configuration (SEP-1024)
* docs(mcpa): record primary-source conflicts resolved during the lesson build
Seven places where specification pages, schema.ts, and SEP texts
disagree, each with the normative resolution: removed versus deprecated
roots and logging methods (SEP-2575 over SEP-2577's feature grouping),
embedded-resource annotation placement (schema.ts over the rendered
example), notification-POST headers, requestState rejection channel,
HTTP statuses for three JSON-RPC codes, server-side subscription
teardown, and tool-name format (published page over SEP-986's draft).
Points the specification leaves open are marked so assessments never
test them as a single rule.
* feat(mcpa): model interaction flow lesson
- the host loop from user request through model selection, tools/call,
and back into model context, driven by a deterministic scripted model
- tool execution errors (isError true) fed back to the model and
corrected on a new request id; protocol errors such as an unknown tool
(-32602) never retried blindly
- an input_required result gathered from a human through
elicitation/create and retried with a new id, inputResponses, and the
requestState echoed exactly
- a tool with no annotations treated as destructive under the
specification defaults: one call confirmed and sent, one denied and
never put on the wire
- deterministic tools/list ordering across identical calls
* feat(mcpa): cache freshness and cursor pagination lesson
- ttlMs and cacheScope on every cacheable result (SEP-2549): absent or
negative ttlMs clamps to 0, cacheScope has no default
- public entries shared across tokens behind a shared cache, private
entries never crossing identities, proven by server call counts
- input_required results and MRTR completions never cached
- opaque cursors, including an empty-string cursor that still means
another page, and invalid cursors rejected with -32602
- notifications/resources/list_changed on a subscriptions/listen stream
invalidating a cached list before its ttlMs runs out
- stable list ordering so client caches and model prompt caches see a
byte-identical catalog
* feat(mcpa): audit trail and trace propagation lesson
- W3C traceparent in _meta (SEP-414): version, trace id, parent id, and
flags validated as lowercase hex of exact length, all-zero ids
rejected, tracestate and baggage passed through untouched
- a three-hop call (client, server, upstream server) where each hop
mints a child span under the same trace id
- a hash-chained audit log recording the authenticated principal (never
self-reported clientInfo), method, tool, redacted arguments, result
channel, request id, and trace id
- tamper detection for both a naive edit and an edit that rewrites its
own hash, caught one entry later through prev_hash
- denied attempts (unknown tool, bad bearer token) logged as protocol
errors, not dropped
- deprecated logging replaced by stderr and OpenTelemetry, with the
per-request logLevel still producing notifications/message
* feat(mcpa): long-running work and the tasks extension lesson
- the tasks extension (SEP-2663) negotiated per request: the client
declares io.modelcontextprotocol/tasks in clientCapabilities and the
server advertises it in server/discover
- a tool that runs synchronously without the extension and returns
resultType task (CreateTaskResult) with it
- tasks/get polling through working, input_required, and completed,
with tasks/get itself always a complete result
- mid-flight input supplied with tasks/update and inputResponses;
cooperative cancellation with tasks/cancel
- -32602 for an unknown or expired taskId and -32021 naming the
extension for a client that never declared it
- what changed from the 2025-11-25 experimental tasks: no tasks/result,
no tasks/list, and no task parameter on tools/call
- choosing among a plain call, an MRTR round trip, and a task
* feat(mcpa): OAuth authorization lesson
- the three roles: the MCP server as resource server, the MCP client,
and the authorization server
- Protected Resource Metadata discovery (RFC 9728): the
WWW-Authenticate resource_metadata URL first, then the path-specific
and root well-known fallbacks
- authorization server metadata discovery order for path and root
issuers, with the issuer required to match
- PKCE S256 generated with the standard library, and the client
refusing to proceed when code_challenge_methods_supported is absent
- the RFC 8707 resource parameter carrying the canonical server URI on
both the authorization and token requests
- the RFC 9207 iss decision table, compared without normalization and
applied to error responses too
- bearer tokens in the Authorization header on every request, audience
validation, no token passthrough, and 401 versus 403 versus 400
* feat(mcpa): operational use-case selection lesson
- the control model as the first design question: model-controlled
tools, application-driven resources, user-controlled prompts, and the
skills extension for cataloged multi-step procedures
- local systems on stdio with credentials from the environment; remote
systems on Streamable HTTP with the interactive OAuth flow, the client
credentials extension for unattended callers, or enterprise-managed
authorization for a central identity provider
- the tasks extension for long jobs and MCP Apps for interactive views,
with a text fallback for hosts that do not declare the ui extension
- cacheScope chosen from data sensitivity, and a no-external-system case
where MCP is not the right fit
- a decision engine that turns a use-case profile into a primitive,
transport, auth path, and extension recommendation
* feat(mcpa): deployment roles and adoption lesson
- six deployment roles on top of the host, client, and server
architecture: server author, host and client developer, platform or
gateway operator, security and governance owner, registry publisher,
and end user
- a responsibility matrix built from a catalog of exact MUST and SHOULD
requirements with page citations, where the same requirement (Origin
validation) moves from the server author to the gateway operator as
the deployment shape changes
- gap reporting for a requirement no role owns
- stdio credentials supplied by the operator's environment and never
carried on the wire
- governance: Agentic AI Foundation stewardship, the maintainer
hierarchy and contributor ladder minimums, Working Groups versus
Interest Groups, the SEP status workflow, and the feature lifecycle
- SDK tiers (SEP-1730) as an adoption risk decision: conformance,
feature, triage, and critical-bug commitments per tier
* feat(mcpa): tool invocation lifecycle lesson
- eight checkpoints from discover and list through select, confirm,
call, validate, execute, and result, with select and confirm as
host-only steps that never touch the wire
- validate ends only in a protocol error (-32602 for an unknown tool);
schema violations, upstream failures, and business-rule failures in
execute become tool execution errors with isError true
- a genuine internal fault during execute surfaced as -32603
- notifications/progress bound to the request's progressToken with a
strictly increasing progress value, and a hard timeout that progress
does not extend
- transport-specific cancellation: closing the stream on Streamable HTTP,
notifications/cancelled on stdio, and no cancelled or timed-out
resultType
- reissuing after a broken stream with a new request id, guided by
idempotentHint as an untrusted hint and a server-minted handle
* feat(mcpa): protocol eras and compatibility lesson
- the revision timeline from 2024-11-05 to 2026-07-28 and the legacy,
modern, and dual-era terms
- the stdio probe for a dual-era client: server/discover first, a
DiscoverResult or a recognized modern error such as -32022 means
modern (retry with a supported version, never fall back), any other
error or a timeout means legacy
- the fallback never keyed on one specific error code
- the Streamable HTTP probe: reading a 400 body for a recognized modern
JSON-RPC error before assuming legacy
- era cached per server process on stdio or per origin on HTTP, with a
re-probe when the cached assumption fails
- a modern-only server naming its supported versions when it rejects a
legacy initialize, and the legacy opening sequence shown only inside
wrapped legacy examples
* feat(mcpa): consent and least privilege lesson
- consent gathered through a multi round-trip request: a tools/call
returns input_required with an elicitation/create request, and the
retry carries a new id, inputResponses, and the signed requestState
- decline, cancel, and a rejected retry returned as tool execution
errors with isError true, never an invented consent error code
- consent scoped per tool and bound to the approved arguments, with
requestState signed, single-use, and rejected when a retry changes
the arguments
- annotation defaults (destructiveHint and openWorldHint true,
readOnlyHint false) deciding when to prompt, treated as untrusted
hints rather than enforcement
- step-up authorization: a 403 insufficient_scope challenge, a new token
requested for the union of granted and challenged scopes, and a retry
cap when the scope is never granted
- tools/list filtered by granted scopes and cached with cacheScope
private because it varies by authorization
* feat(mcpa): extensions framework lesson
- extension identifiers as {vendor-prefix}/{name}: the
io.modelcontextprotocol/ prefix for official extensions and a reversed
owned domain for third parties
- negotiation on every request: the client declares extensions in
clientCapabilities and the server advertises its own in server/discover,
with the settings object as the value
- an optional extension falling back to core behavior and a mandatory
one rejected with -32021 naming it in data.requiredCapabilities
- extensions disabled by default and opt-in; a breaking change needs a
new identifier
- the SEP-2133 process, experimental-ext- repositories owned by a
Working Group or Interest Group, and the official roster: tasks, MCP
Apps, skills, and the two authorization extensions
- what changed from initialize-time declaration to per-request
negotiation
* feat(mcpa): registry, gateways, and SDK tiers lesson
- the MCP Registry as a preview metadata index for public servers:
server.json with packages (npm, pypi, nuget, cargo, oci, mcpb),
remotes (streamable-http, deprecated sse), or both
- reverse-DNS namespaces admitted only after GitHub, DNS, or HTTP
verification; spoofed namespaces and private servers rejected
- exact version strings (ranges prohibited), and the server.json schema
version kept separate from the protocol version
- aggregators and subregistries built on top of the registry
- gateways that route on the Mcp-Method and Mcp-Name headers, reject a
header and body mismatch with -32020 before any backend is touched,
partition private cache entries by caller, and never pass the
caller's token through to a backend
- SDK tiers (SEP-1730): conformance, feature, triage, and critical-bug
commitments, and relegation after four weeks of continuous failures
* docs(mcpa): pin MCP Apps metadata shapes in the protocol brief
The extension summary named _meta.ui.csp and _meta.ui.permissions
without their shape or location. Checked against the MCP Apps
specification (ext-apps 2026-01-26, draft agrees):
- a tool's _meta.ui carries resourceUri and visibility, which defaults
to model and app and gates what the agent lists and what an app may
call
- the UI resource's _meta.ui carries csp, an object of connectDomains,
resourceDomains, frameDomains, and baseUriDomains origin lists, and
permissions, an object of camera, microphone, geolocation, and
clipboardWrite flags
- the host builds CSP from declared domains only, may restrict further,
applies a restrictive default when csp is omitted, and may honor
permissions that apps must not assume
- the app's ui/initialize is unrelated to the removed core initialize
* feat(mcpa): capstone that reads one exchange end to end
One incident-console server driven through a single transcript that
exercises every domain:
- server/discover with cache hints after an unsupported version is
corrected from the -32022 data.supported list
- protocol version and client capabilities in _meta on every request
- a schema-invalid call returned with isError true and corrected
- a consent round trip with an HMAC-signed, principal-bound
requestState, a retry on a new id, and a tampered state rejected
- -32021 when the client never declared elicitation or the tasks
extension
- a long diagnostic run as a task, polled to completion, and a second
task cancelled
- request-scoped notifications/progress and the Mcp-Method and Mcp-Name
header contract
- a wrong-audience token rejected with 401 before any JSON-RPC body is
read
- one traceparent trace id carried through every hop, and a hash-chained
audit log that pinpoints a tampered entry
- a readiness checklist mapping every objective to what a candidate must
be able to do
* docs(mcpa): teach the tutor and guides the stateless 34-lesson route
- tutor skill (and its Claude Code mirror): the 2026-07-28 revision is
taught as current, with no initialize handshake, no sessions, and
per-request _meta plus server/discover; older revisions appear only as
what changed, and deprecated features as still working until removal
- the protocol brief and the wire-shape checker join the tutor's source
list, and the tutor runs the checker when a learner edits a transcript
- three full mocks with distinct emphasis, and a fresh mock for every
retake so a second score measures readiness rather than recall
- the capstone description now matches lesson 33's integrated exchange
- learner guide: 34-lesson route, 30-question diagnostic, three mocks,
the multi round-trip lesson as the worked example, and the wire
checker in the local verification suite
- root README: the MCPA summary describes the new route, and the skills
table and install list include mcpa-certification
* ci(certifications): gate MCPA transcripts on the 2026-07-28 wire shape
Runs the wire-shape checker's own tests and then the checker over every
MCPA lesson transcript, so a lesson that reintroduces the legacy
handshake, drops the per-request _meta fields, omits resultType, or
emits an undefined error code fails CI. Both scripts are added to the
workflow's path filters.
* feat(mcpa): MCP Apps interactive interfaces lesson
- the io.modelcontextprotocol/ui extension negotiated per request, with
a text-only fallback for hosts that never declare it
- a tool's _meta.ui carrying resourceUri and visibility: the agent's tool
list excludes tools without "model", and an app's tools/call is refused
for tools without "app", before any consent prompt
- the ui:// resource fetched with an ordinary resources/read and
recognized only by the text/html;profile=mcp-app mime type
- the resource's _meta.ui csp object (connectDomains, resourceDomains,
frameDomains, baseUriDomains) turned into a Content Security Policy
that starts from default-src 'none' and admits only declared domains,
with the specification's restrictive default when csp is omitted
- permissions flags (camera, microphone, geolocation, clipboardWrite)
honored at the host's discretion and never assumed by the app
- the sandboxed iframe, a sandbox proxy on its own origin for web hosts,
and the app's ui/ JSON-RPC dialect over postMessage, including a
ui/initialize unrelated to the removed core initialize
* feat(mcpa): register all 34 lesson figures and index the route
- site/figures-mcpa-certifications.js rebuilt from each lesson's figure
snippet: 34 mechanism figures (blueprint weights through the capstone
flow), each with its own CSS prefix and marker ids, all rendering an
SVG under a stub DOM; the ten figures of the legacy route are gone
- certifications/mcpa/README.md: the lesson index now lists all 34
lessons by title, the route diagram follows the new domains, and the
overview names the protocol brief, the wire-shape checker, the
30-question diagnostic, and the three mocks
* docs(mcpa): give each deprecated feature its own source and removal floor
The brief grouped all six deprecated features under SEP-2577 with one
2027-07-28 removal floor. The specification's deprecated registry
records them separately:
- Roots, Sampling, and Logging: SEP-2577, deprecated in 2026-07-28,
earliest removal on or after 2027-07-28
- Dynamic Client Registration: PR #2858, deprecated in 2026-07-28,
earliest removal on or after 2027-07-28
- includeContext "thisServer" and "allServers": SEP-2596, deprecated in
2025-11-25, removal follows Sampling
- HTTP+SSE: SEP-2596, deprecated in 2025-03-26, earliest removal three
months after SEP-2596 reaches Final
Lesson 15 already teaches the registry's values; this brings the brief
in line so later questions do not inherit the grouped floor.
* docs(mcpa): state the x-mcp-header limits with their RFC 2119 strength
The brief said x-mcp-header was "never for secrets" and that clients
drop invalid tools. The tools page is more precise:
- only integer, string, and boolean parameters that are statically
reachable from the schema root can be mirrored; number is excluded
- server developers SHOULD NOT mark sensitive parameters (passwords,
API keys, tokens, PII), because header values are visible to
intermediaries; this is a SHOULD NOT, not a prohibition
- HTTP clients MUST reject a tool whose x-mcp-header values violate the
constraints by excluding it from their tools/list result
* docs(mcpa): teach what a revision date means and how hosts load skills
Two facts the assessments test were not taught by any lesson:
- lesson 01 and the brief: a revision identifier is a YYYY-MM-DD date
marking the last backwards incompatible change, so a Current revision
can take compatible fixes without being renamed (Draft, Current,
Final)
- lesson 30 and the brief: reading a skill's SKILL.md through
resources/read only retrieves text; skill content is untrusted input
tagged with its origin, explicit user policy decides whether a skill
is loaded, hosts should let users inspect a skill first, may not let
it trigger host-side execution without per-skill approval, and ignore
permission-widening frontmatter such as allowed-tools unless the user
approved it (SEP-2640)
* docs(mcpa): teach the x-mcp-header mirroring limits in the transports lesson
The transports lesson introduced x-mcp-header mirroring and the base64
sentinel but not its limits, which the assessments test:
- only integer, string, and boolean parameters statically reachable
from the schema root can be mirrored, never number
- a Streamable HTTP client must exclude a tool whose x-mcp-header
values break those constraints from its tools/list result
- server developers should not mark sensitive parameters such as API
keys or tokens, because header values are visible to intermediaries
* fix(site): refresh the figure manifest cache key for the rebuilt MCPA figures
lesson.html pins figure-manifest.js with a content hash. Rebuilding
site/figures-mcpa-certifications.js with the 34 new figures changed the
generated manifest, so the pinned key moves from 0980822a99ac to
339ef88a8714; test_build_artifacts.js checks that the committed page
matches the manifest the build produces.
* docs(i18n): regenerate the translated READMEs with the MCPA sections
The English README gained the MCPA route row, the MCPA section, the
mcpa-certification skill row, and the updated install list, but the
twelve i18n/<lang>/README.md files were never regenerated, so
build_readme_i18n.py --check failed. Regenerated with the script; the
new blocks have no hand-authored translations yet and fall back to
English as the generator documents, and no existing translation was
dropped.
* feat(mcpa): diagnostic and three full-length mocks on the 2026-07-28 protocol
Four original assessments declared on the mcpa-f track, 210 questions,
every key checked against the protocol brief and the specification
pages it cites:
- diagnostic (30 questions, 30 minutes): one concept per item across
all 18 objectives, for placing a learner by domain
- mock 1 (60 questions, 90 minutes): operational scenarios, such as
scaling a stateful tool behind a load balancer, one-click local
server consent, registry preview planning, and DCR application_type
- mock 2 (60 questions, 90 minutes): wire-level messages, such as
missing _meta fields, -32021 and -32022 error data, progress
monotonicity, HTTP cancellation by closing the stream, all-zero
traceparent ids, and MCP Apps mime types
- mock 3 (60 questions, 90 minutes): design and security trade-offs,
such as where state lives, requestState protection, token audience,
skill loading consent, and SDK tier risk
Each mock follows the blueprint split (10/8/16/14/12 across the five
domains), uses every objective, and references all 34 lessons. Items
that repeated another file's scenario were rewritten to test a
different fact, and answer positions are balanced by
debias_certification_questions.py.
* chore(mcpa): balance answer positions across the 34 lesson quizzes
Applies debias_certification_questions.py to the MCPA lesson quizzes so
correct answers follow the per-file balanced position cycle the CI
check enforces. Only option order changes; every question, option, and
explanation is unchanged, and no Claude certification file is touched.
* fix(mcpa): answer unknown methods with -32601 in four lesson servers
The dispatchers in lessons 04, 11, 12, and 14 fell through to -32602
(invalid params) for a JSON-RPC method they do not implement. An
unknown method is -32601 (method not found); -32602 is reserved for an
unknown tool, missing _meta, and other invalid parameters. Every other
lesson dispatcher already used -32601, so a learner reading these four
servers top to bottom would have learned the wrong code.
Also adds a test for lesson 03's validate_error_shape, the one shape
validator its tests never exercised.
* fix(mcpa): align three labs with what their lessons say they show
- lesson 30: the text pointed learners at the sixth exchange for the
malformed no-slash-here identifier, but it is the seventh
- lesson 32: the demo printed "prefer remote" while calling
resolve_install_target with prefer="package"
- lesson 33: acknowledge_incident is listed by tools/list but a plain
tools/call answered "Unknown tool" (-32602); it now returns a tool
execution error saying the tool is served only over the authorized
HTTP endpoint, with a test
* fix(scripts): flag legacy and violation wrappers that do not wrap a message
check_mcpa_wire.py skipped every entry marked legacy or violation, and
when the wrapped message was not an object (a typo such as None or a
bare method string) the entry produced no finding at all, hiding an
authoring mistake. Such wrappers are now reported, matching how every
other malformed entry is handled, with a regression test for both
wrapper kinds.
* docs(mcpa): give every lab the source header the lesson contract requires
AGENTS.md asks each lesson's code/main.py to open with a 4 to 6 line
header citing its docs/en.md path and its spec or RFC sources. The MCPA
labs had a one-line docstring. Each header now names the lesson's full
docs/en.md path, what the lab does, and the specification pages, SEPs,
RFCs, or W3C documents it implements.
* fix(mcpa): require an explicit approval before consent-gated work runs
Two labs treated any elicitation answer with action "accept" as consent,
even when the form content said no:
- lesson 25: accepting the delete_file confirmation with approved false
still deleted the file; consent now needs action accept and a content
object whose approved field is exactly true, and a non-object answer
is handled safely
- lesson 20: accepting the vault read with proceed false still returned
the private note; the vault now needs proceed exactly true
Each fix has a test showing the refused path leaves no side effect.
* fix(mcpa): turn malformed wire input into refusals instead of exceptions
Six labs raised on attacker-controlled or malformed input instead of
answering it:
- lesson 05: a -32022 error with an empty supported list raised
IndexError; the probe now records a modern era with no confirmed
version and only caches a retry version after a successful discover
- lesson 09: an x-mcp-header value that is not a string crashed the
linter, and object or array properties were not flagged; only string,
integer, and boolean parameters may be mirrored
- lesson 14: a non-ASCII requestState raised during signature checks; it
is now rejected as malformed
- lesson 19: a base64 sentinel header with invalid base64 or UTF-8
raised; it now decodes to a mismatch and gets the HeaderMismatch reply
- lessons 27 and 33: a malformed traceparent raised ValueError; lesson
27 restarts the trace with a new root and lesson 33 continues without
a trace id
Each case has a regression test.
* fix(mcpa): close gaps in the labs' own security controls
- lesson 22: only the first CALL server.tool instruction in server
content was checked, so a harmless first instruction could hide a
cross-server one; every match is now quarantined and checked on relay
- lesson 26: the pinned tool descriptor left out annotations, so a
silent destructiveHint flip was not caught as a rug pull, although the
lesson's own threat matrix pins annotations; they are now part of the
hashed descriptor
- lesson 32: the gateway log stored the caller's raw bearer token as the
principal and printed it in the transcript; it now records a
non-reversible principal reference, and the backend answers an
unimplemented method with -32601 instead of -32602
Each fix has a test.
* fix(mcpa): expire idle baskets from their last activity
Lesson 04 tells learners a basket expires after five idle ticks, but
is_expired measured from creation, so an actively used basket still
expired. Baskets now record their last activity, adding an item
refreshes it, and a test shows an item added inside the window keeps
the basket alive.
* docs(mcpa): match run locations and rejection rules to the labs and spec
- lessons 09, 10, and 12 told learners to run python3 code/main.py from
the repository root, where that relative path does not exist; they
now say to run it from the lesson directory like the other labs
- the lesson 14 checklist said a protocol error is the wrong channel for
a tampered or expired requestState; the spec requires rejection but
does not prescribe the channel, so the checklist now names the lab's
choice, a tool execution error, and a fresh input_required result as
valid options
- the lesson 21 patterns sheet said a tools/call without the tasks
extension always gets -32021; per SEP-2663 the server returns an
ordinary result when it can finish within the request and -32021 only
when it cannot, and tasks/get, tasks/update, and tasks/cancel without
the declaration get -32021
* docs(mcpa): say the MCPA track is on GitHub only for now
The website build renders only the first certification program, so no
MCPA page is published there yet. GETTING_STARTED, both copies of the
tutor skill, and the README certification row pointed learners at
website routes that do not exist. They now send learners to the GitHub
lesson and assessment paths and say the website does not carry MCPA
yet. The translated READMEs are regenerated from the English one.
* fix(audit): stop treating the MCPA practice mock size as an exam fact
The official MCPA page does not publish an item count, and the fact
ledger records it as not published. The audit's MCPA-F exam facts listed
items 60, so check_track verified the practice mock size as if it were
official. The item count is removed from the verified facts; the track
keeps 60 as the curriculum's chosen mock length.
* fix(mcpa): refuse differently cased cross-server instructions in lesson 22
The embedded-instruction pattern matches CALL server.tool without regard
to letter case, but the relay check compared the captured names exactly,
so CALL Tickets.delete_all_tickets in untrusted server content still let
a relay to tickets.delete_all_tickets through as allowed. Quarantine and
relay checks now compare server and tool names case-insensitively, so a
case variant is refused, and a test covers the case-shifted instruction
and the same-server case.
* feat(site): render every certification program, not only the first
parseCertifications read only the first folder under certifications/, so
the website showed Claude alone: the catalog, track, assessment, and
lesson pages, the homepage spotlight, search, sitemap, and llms.txt never
saw MCPA. The build now loads every program, tags each track, lesson, and
assessment with its programId, derives each program's learner guide and
tutor skill paths, and fails on duplicate program, track, or assessment
ids across programs.
- the catalog renders one section per program with its own access
notice, GitHub tutor links, and track grid, and the no-JavaScript
discovery block follows the same structure
- track, assessment, and lesson pages show the disclaimer and scoring
notice of the track's own program instead of a hardcoded Anthropic one
- lesson data loading, the language picker, and the api lesson and
certification routes accept any certifications/<program>/lessons path
- the homepage spotlight shows both badges and names both providers, and
build.js keeps its track, lesson, and question counts in sync
- program.json gains shortName and accessNoticeTitle, and the MCPA badge
is marked square so it is not clipped to the Claude badge outline
- exam facts read "Not published" when a track marks its item count or
passing score unpublished, so the MCPA card no longer presents the
practice mock size as the official question count
- a track with four assessments lays them out two by two
- tests derive track counts from the data and cover a second program in
the lesson and certification routes
* docs(mcpa): send learners to the MCPA track now that the site renders it
The GitHub-only wording existed because the website could not show a
second program. With the multi-program build, GETTING_STARTED, both
copies of the tutor skill, and the README point to the MCPA track page
again, the certifications index lists both programs with their onboarding
guides, and the translated READMEs are regenerated.
* docs(i18n): translate the MCPA goal row in the Portuguese and Russian READMEs
The Portuguese and Russian READMEs translate every row of the "choose
what you want to build" table, but the new MCPA row had no entry in
readme_translations.py, so it rendered in English between translated
rows. Both languages now carry the row, with the onboarding guide and
the MCPA track links unchanged, and the translated READMEs are
regenerated.
* feat(site): add a Sponsor us page rendered from SPONSORS.md
SPONSORS.md promises a sponsor page on the curriculum site, but the site
had no sponsor page and no route to one. build.js now renders SPONSORS.md
into site/sponsors.html on every build, so the page cannot drift from the
file the maintainer edits.
- the renderer covers what SPONSORS.md uses: headings with GitHub-style
anchor ids, paragraphs, lists with wrapped items, aligned tables, bold,
inline code, and links, where repository files resolve to GitHub and
javascript: or parent-directory links render as plain labels
- raw HTML is limited to a, picture, source, and img with https-only
URLs; any other tag is escaped, and a closing tag is kept only when its
opening tag was kept
- the SerpApi logo follows the site's theme toggle instead of the
operating system color scheme
- "Sponsor us" joins the hamburger menu through header.js and the footer
of every page, and is added to the interface strings for translation
- /sponsors is served from sponsors.html with the same markdown
negotiation as the other public pages, and the page is listed in the
sitemap and llms.txt
- tests pin the rendered page to SPONSORS.md, the HTML allowlist, and
the menu and footer links
* fix(site): give the privacy, contact, and developer pages the shared header
The three trust pages shipped a stripped header with no header.js, no
search or theme controls, no site fonts, and an old stylesheet key. At
1400px and below the stylesheet renders the header nav as a dropdown
panel that header.js normally hides behind the menu button, so on these
pages the panel stayed open over the content.
They now use the same header markup as the other pages, load the site
fonts, the current stylesheet, and the shared theme, progress, header,
and search scripts, gain a skip link to main, and style their eyebrow
line. The shared asset test now covers all three pages so their cache
keys cannot fall behind again.
Certification Curricula
A credential should be evidence that you can do the work, not evidence that you memorized a question bank.
This section turns public certification blueprints into free, build-first study paths. Each path combines the existing AI Engineering from Scratch curriculum with certification-specific lessons, labs, diagnostics, and original mock exams.
Programs
| Program | Credentials | Start with an AI tutor | Website |
|---|---|---|---|
| Claude Certifications | All four Claude credentials published in the July 2026 exam guides | Claude onboarding | Claude tracks |
| MCPA Certification | Model Context Protocol Associate, aligned to the MCP 2026-07-28 specification | MCPA onboarding | MCPA track |
Each onboarding guide works with Claude Code, Codex, ChatGPT, Cursor, or another agent: the tutor skill picks a route, teaches one lesson at a time, runs the labs, and saves your progress in the repository.
Rules
- Public exam guides define coverage and weighting.
- Official product documentation defines current technical behavior.
- Every lesson and practice question is original.
- No exam dumps, confidential questions, pass guarantees, or answer-pattern tricks.
- Practice results are raw curriculum scores, not official scaled scores.
- Hands-on artifacts matter more than passive reading.