docs: add getting started guide for building UCP servers

[damaz91]

Description

This PR adds a new "Getting Started" section to the UCP documentation site (in the "Specification" section), providing a step-by-step guide for developers to build core UCP endpoints (Create Checkout and Get Checkout) using either the Python SDK (FastAPI) or the Node.js/TypeScript SDK (Express).

Key features of this guide:

• Multi-language support with linked tabs for Python and Node.js.
• Generic mock payment handler setup.
• Step-by-step code snippets with detailed comments.
• Coverage of header validation (Idempotency-Key, UCP-Agent).
• Calculation of subtotal, tax, and total at both line item and order levels.
• Information on next steps, including linking to the Conformance repository.

Category (Required)

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
• Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
• Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
• SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
• Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
• Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

None.

Checklist

• I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

[ptiper]

Hi Federico,

Thanks for putting this together! Having a practical getting started guide for both Python and TypeScript is a great addition.

I tested the guide locally and have a few suggestions:

1. Placement in navigation: Overview vs Specification

Right now, the guide is located under docs/specification/getting-started.md.

The Specification section is strictly versioned with spec releases and intended for normative specifications. In contrast, the Overview section is where developers look for high-level intro and onboarding content.

Would it make sense to move this to docs/documentation/getting-started.md under Overview (alongside Core Concepts)? That keeps it easily discoverable for new developers and version-agnostic.

2. Full file code reference

Because the create_checkout endpoint logic is broken across Steps 2, 3, and 4, it is easy to make indentation or scoping mistakes when copying snippet-by-snippet.

Could we include an expandable tab or code block at the end with the full main.py (and server.ts) file so readers have a reference to verify against?

3. Developer experience refinements

• Default port: The examples use port 8000, which conflicts with the default port used by mkdocs serve / doc previews. Using 8080 (or 3000 for Node) prevents port collisions when testing the guide and running local docs at the same time.
• Package vs import name: A quick note that the Python package is installed as ucp-sdk on PyPI but imported as ucp_sdk in code.
• Missing header status codes: Note that omitting required headers returns HTTP 422 in Python vs HTTP 400 in Node.js.

Thanks again!

[damaz91]

Hi Federico,

Thanks for putting this together! Having a practical getting started guide for both Python and TypeScript is a great addition.

I tested the guide locally and have a few suggestions:

1. Placement in navigation: Overview vs Specification

Right now, the guide is located under docs/specification/getting-started.md.

The Specification section is strictly versioned with spec releases and intended for normative specifications. In contrast, the Overview section is where developers look for high-level intro and onboarding content.

Would it make sense to move this to docs/documentation/getting-started.md under Overview (alongside Core Concepts)? That keeps it easily discoverable for new developers and version-agnostic.

2. Full file code reference

Because the create_checkout endpoint logic is broken across Steps 2, 3, and 4, it is easy to make indentation or scoping mistakes when copying snippet-by-snippet.

Could we include an expandable tab or code block at the end with the full main.py (and server.ts) file so readers have a reference to verify against?

3. Developer experience refinements

• Default port: The examples use port 8000, which conflicts with the default port used by mkdocs serve / doc previews. Using 8080 (or 3000 for Node) prevents port collisions when testing the guide and running local docs at the same time.
• Package vs import name: A quick note that the Python package is installed as ucp-sdk on PyPI but imported as ucp_sdk in code.
• Missing header status codes: Note that omitting required headers returns HTTP 422 in Python vs HTTP 400 in Node.js.

Thanks again!

On 1., I thought about this. I feel like the "Getting Started" should be versioned (similarly to the Playground) as we might introduce breaking changes and/or add new SDK languages for future releases. I also think we might need to create similar pages for other verticals, and in that case those would live under "Specifications". Let me know if you disagree.

Addressed 2 and 3, PTAL - thanks!

[damaz91]

@ptiper comments addressed, PTAL

[ptiper]

Hi Federico,

I walked through the entire guide from scratch to test all steps locally. The Python walkthrough worked great!

For the Node.js walkthrough, I ran into two small issues when following the steps:

1. Type import for CheckoutResponse: In server.ts, CheckoutResponse is a TypeScript type rather than a runtime value export. Under ES modules, Node throws SyntaxError: The requested module '@ucp-js/sdk' does not provide an export named 'CheckoutResponse'. Changing the import to type CheckoutResponse in Step 1 and the full file reference fixes this:

import {
  CheckoutCreateRequestSchema,
  CheckoutResponseSchema,
  type CheckoutResponse
} from '@ucp-js/sdk';

2. Using tsx instead of ts-node: Running npm start with ts-node failed with TypeError: Cannot read properties of undefined (reading 'fileExists') due to TS 7 / ESM compatibility. Switching the dev dependency to tsx (npm install --save-dev typescript @types/express @types/node tsx) and updating the start script to "start": "tsx server.ts" runs cleanly out of the box.

Once those two tweaks are in, this should be ready to merge. Thanks!

[damaz91]

Done @ptiper !

[ptiper]

Hi Federico,

Quick update now that UCP 2026-08-25 is released:

• Python SDK 0.5.0 imports: ucp-sdk 0.5.0 is live on PyPI. AvailablePaymentInstrument, Link, and Total moved from shopping.types to common.types, so main.py needs updated import paths to avoid a startup ModuleNotFoundError.
• Version bump: Update protocol metadata version in both main.py and server.ts to 2026-08-25.
• Node.js SDK: We are currently reviewing js-sdk PR #61 to release @ucp-js/sdk@0.5.0. Once that lands on npm, the Node.js walkthrough will be fully aligned with Python on 2026-08-25.

Happy to push these tweaks directly to your branch while you are away if you'd like, let me know!

[proshoumma]

Hi @damaz91 👋🏼 , really nice addition. Would be super helpful for Businesses currently building towards UCP, and I think they'll be the main audience for it.

Two small suggestions:

1. When to check inventory: A common question we hear from merchants is when to actually check stock. The confusion comes from variant.availability.available in /catalog/[search|lookup] which is a catalog-time signal and it's optional, so it can drift from real inventory. Create-checkout is where they should be doing a real check. A one-line comment in the example would go a long way.
2. Capability negotiation: Business fetches the Platform's profile from the UCP-Agent header, runs the intersection algorithm, and echoes the active set back. Since the guide already validates UCP-Agent, a short note saying "negotiation is out of scope here; see Discovery" would stop people shipping empty capabilities object to production.

Happy to push these as a follow-up commit.