Using UC-BoK with AI Agents¶

UC-BoK exposes its full knowledge graph as a Model Context Protocol (MCP) server — a standard interface that lets AI agents query the platform directly as a tool, without copy-pasting content into a chat.

With 28 tools covering 12 catalog layers, any MCP-compatible agent becomes a Unified Commerce expert:

get_ontology_summary()       → orient yourself: 46 BOs, 25 capabilities, 107 events …
trace_capability("bopis")    → full vertical slice: services → APIs → events → maturity
run_assessment("my-retailer")→ UCMI score, band, domain breakdown, prioritised gaps
get_pattern("bopis")         → Click & Collect capability prerequisites with minimum levels
search_catalog("inventory")  → cross-catalog search: BOs, caps, events, services, APIs …

Live Endpoint¶

https://uc-bok.rufy.lab.retexcloud.io/mcp

No authentication required for the MCP endpoint.

Available Tools¶

Orientation¶

Tool	Description
`get_ontology_summary()`	Full knowledge graph summary: domains, catalog counts, classifications, UCMI bands, all tool names

Domains¶

Tool	Description
`get_domain(id)`	Domain detail with its BOs, capabilities, events, and services

Business Objects¶

Tool	Description
`get_business_object(id)`	Full record: attributes, lifecycle, relationships, domain events
`list_business_objects(domain?, classification?)`	List 46 BOs filtered by domain or classification

Capabilities¶

Tool	Description
`get_capability(id)`	Full record: outcome, domain, services list
`list_capabilities(domain?, classification?)`	List 25 capabilities filtered by domain or classification
`get_capability_maturity(capability_id)`	UCMI maturity levels 0–4, assessment questions, dependencies

Processes¶

Tool	Description
`get_process(id)`	Full record: capabilities, objects, services, applications, outcome
`list_processes(classification?)`	List 15 processes with outcomes and capability references

Events¶

Tool	Description
`list_events(domain?, classification?)`	List 107 domain events filtered by domain or event classification
`get_events_for_capability(capability_id)`	All events emitted by a capability

Services¶

Tool	Description
`get_service(id)`	Full service record: domain, object, events emitted
`list_services(domain?, capability?)`	List 104 business services filtered by domain or capability

APIs¶

Tool	Description
`get_api(id)`	Full API spec: HTTP method, path, auth, request/response objects, events
`list_apis(domain?, application?)`	List 24 canonical APIs filtered by domain or application

Applications¶

Tool	Description
`get_application(id)`	Application record: classification, implements, domains served
`list_applications(classification?)`	List 13 applications (OMS, POS, CRM, WMS…) by classification

Patterns¶

Tool	Description
`get_pattern(id)`	Pattern detail: capability prerequisites with minimum UCMI levels
`list_patterns(classification?)`	List 7 Unified Commerce patterns (BOPIS, SFS, Endless Aisle…)

Reference Architectures¶

Tool	Description
`list_reference_architectures()`	List available RAs with critical capabilities
`get_reference_architecture(id)`	Full RA: capability map with MVP + BIC levels, vertical-specific notes

Semantic Constraints & Validation¶

Tool	Description
`get_constraints(object_id)`	Invariants and cardinality rules for a business object
`get_validation_rules(context_id)`	Pre/post-conditions for a process or capability

Traceability¶

Tool	Description
`trace_capability(id)`	Full vertical slice: services → APIs → events → BOs → maturity → patterns → processes

Search¶

Tool	Description
`search_catalog(query, type_filter?)`	Full-text search across all 8 catalog types; optional type filter

UCMI Assessment¶

Tool	Description
`run_assessment(profile_id?)`	UCMI score (0–4), band, domain scores, capability scores, prioritised gaps with next-step guidance
`score_capability(capability_id, current_level)`	Single-capability score card: current → next level description, gap, assessment questions
`list_assessment_profiles()`	List available retailer assessment profiles

Configure Your Agent¶

Claude Desktop¶

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "uc-bok": {
      "url": "https://uc-bok.rufy.lab.retexcloud.io/mcp"
    }
  }
}

Restart Claude Desktop. You'll see UC-BoK tools in the tool list.

Cursor¶

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "uc-bok": {
      "url": "https://uc-bok.rufy.lab.retexcloud.io/mcp"
    }
  }
}

GitHub Copilot (VS Code)¶

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "uc-bok": {
      "url": "https://uc-bok.rufy.lab.retexcloud.io/mcp"
    }
  }
}

Zed¶

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "uc-bok": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-remote", "https://uc-bok.rufy.lab.retexcloud.io/mcp"]
      }
    }
  }
}

Run Locally (stdio)¶

For local development or offline use:

git clone https://github.com/retex-iconic/uc-bok.git
cd uc-bok
pip install fastmcp pyyaml
make mcp

Claude Desktop (local stdio):

{
  "mcpServers": {
    "uc-bok-local": {
      "command": "python",
      "args": ["/path/to/uc-bok/scripts/mcp_server.py"]
    }
  }
}

Self-host with Docker¶

Single container — site + MCP server in one Python process:

git clone https://github.com/retex-iconic/uc-bok.git
cd uc-bok
pip install -r requirements.txt && make generate generate-apps indexes graphs site
HTTP_USER=admin HTTP_PASSWORD=secret docker compose up

MCP: http://localhost/mcp · Site: http://localhost/

Context Files (no agent required)¶

Resource	URL	Use
`llms.txt`	`/llms.txt`	Site index for LLMs (lightweight)
`llms-full.txt`	`/llms-full.txt`	Full catalog dump — paste into context
AI Context Bundle	this page	Structured 16KB summary — optimised for LLM context windows

Example Prompts¶

Once connected via MCP, ask your agent:

"Give me the full vertical slice for checkout — services, APIs, events, and maturity levels."

"What UCMI level do I need for each capability to run BOPIS? What's the minimum viable setup?"

"Run a UCMI assessment for acme-electronics-2026. Show domain scores and top 5 gaps with next steps."

"What invariants apply to the order business object? What validation rules govern the checkout process?"

"Compare the capability maps of fashion-retail and grocery-retail reference architectures."

"Search for everything related to returns across all catalog types."

"What events does the order-management capability emit? Which applications consume them?"