SDK v1.7.3

Highlights

UserId is now a subtype of PersonId, reflecting that workspace users are internal persons in Affinity's data model. Code that receives a UserId (e.g., Note.creator_id) can now pass it directly to any API accepting PersonId — no casting required.

Changes

• UserId now extends PersonId instead of IntId — isinstance(UserId(1), PersonId) is now True. This is an intentional runtime behavior change: workspace users are internal persons in Affinity's data model. Code that used isinstance to distinguish users from persons should use person.type == PersonType.INTERNAL instead.
• Simplified internal casts that previously converted UserId → int → PersonId

Documentation

• data-model.md: clarified that user IDs and person IDs share the same ID space

Quick Install

SDK only:

pip install affinity-sdk

SDK + CLI:

pipx install "affinity-sdk[cli]"

MCP Server for Claude Desktop (easiest - MCPB bundle):

1. Install CLI: pipx install "affinity-sdk[cli]"
2. (Optional) Pre-configure API key: xaffinity config setup-key
   • If skipped, Claude Desktop will prompt for your API key during install
3. Install xaffinity MCP in Claude Desktop (download and double-click)

Other MCP clients (Cursor, Windsurf, VS Code, etc.) require manual configuration - see MCP docs.

Full documentation | MCP Server docs