AndreasHeine/i3x2ua

**FastAPI gateway implementing the i3X API over OPC UA — exposes OPC UA address spaces as standardized REST and MCP endpoints with JSON responses, OpenAPI docs, and Server-Sent Event subscriptions. Built for teams that do not have deep OPC UA expertise.**
**Industrial Information Interoperability eXchange (i3X)**
> The Industrial Information Interoperability Exchange (i3X™) is an open, common API initiative proposed to address a growing interoperability challenge in modern manufacturing architectures: **manufacturing data silo proliferation and API chaos**. As manufacturers adopt heterogeneous software stacks from multiple vendors, the industry risks repeating past fragmentation seen with protocols, platforms, and namespaces - this time at the API layer.
Architecture Overview
The proxy authentication and certificate-provisioning components are deployment
concerns, not application services. The app does not enforce HTTP authentication;
the Docker Compose example configures Basic Auth at nginx, while Certbot/ACME
provisioning and renewal are handled separately.
Quick Start
Requirements:
- Python 3.14 to 3.15
- uv
- Optional: running OPC UA server
Install dependencies:
Use uv sync for runtime dependencies and uv sync --group dev when you need linting, typing, and test tooling.
Start API:
Start without OPC UA server (PowerShell):
Enable MCP support explicitly when you want the /mcp endpoints and MCP tool catalog to be available:
MCP with enhanced Schemas e.g. EnumValues, References, ModelingRules, ...
If you do not set I3X_ENABLE_MCP, the app starts without MCP support and /mcp returns 404.
Use encrypted OPC UA with the included sample client certificate (development/testing):
The OPC UA server may require manually trusting the sample client certificate before the secure session can be established.
If you create your own OPC UA client certificates, ensure they include OPC UA-compatible SAN and key usage fields (application URI, DNS names, clientAuth EKU, and signing/encipherment key usages) and match the server's exposed security mode/policy.
OpenAPI/Swagger:
- http://127.0.0.1:8000/openapi.json
- http://127.0.0.1:8000/docs
Operations are grouped in workflow order: **Exploratory** (address-space
discovery), **Query** (current and historical reads), **Update** (writes), and
**Subscribe** (data-change subscriptions), followed by **Diagnostics** and **MCP**.
The generated document includes request examples, i3X HTTP error envelopes,
subscription SSE wire format, sync overflow (206), optional-write failures
(501), and conditional-GET headers and bodyless 304 responses. Validation
errors return 400, not FastAPI's default 422. Bulk responses can use HTTP
200 while individual items fail: always inspect each item's success,
error, and responseDetail. Example element and subscription IDs are
placeholders; replace them with IDs returned by discovery or creation.
For production, configure HTTPS and authentication/authorization at the reverse
proxy; keep /v1/info public as required by i3X. The application does not enforce
an HTTP authentication scheme, and the OpenAPI document deliberately does not
claim otherwise. Subscription clientId is a scope identifier, not a credential.
Diagnostics and MCP are gateway extensions; restrict their exposure according
to your deployment policy. HTTP caching headers are not generated as MCP tool
arguments.
When running the nginx reverse proxy from docker compose up -d, use http://localhost:8080/ for the HTTP entrypoint or https://localhost:8443/ for the HTTPS entrypoint. 8443 is mapped to nginx's TLS port, so http://localhost:8443/ will return a 400 error by design.
API Surface
Active endpoints are exposed under /v1 for:
- info and metadata (/info, /namespaces, /objecttypes, /relationshiptypes)
- filtered type queries (/objecttypes/query, /relationshiptypes/query)
- object queries and values (/objects, /objects/list, /objects/related, /objects/value, /objects/history)
- subscriptions (/subscriptions, /subscriptions/register, /subscriptions/unregister, /subscriptions/sync, /subscriptions/list, /subscriptions/delete, /subscriptions/stream)