Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

docs/04-mcp/CLIENT_ONBOARDING.md

@@ -0,0 +1,22 @@
+# MCP client onboarding and bridge
+
+## Client lifecycle
+
+Each machine client is an independently scoped Hub record bound to one project and environment. New UI records are `pending` and their binding is disabled until an exact, real Authentik subject is activated. The control API returns a client ID, status, last-seen metadata, an Authentik service-account plan, and a safe configuration projection. It never returns a bearer token, app password, refresh token, or shared credential.
+
+Disable and revoke are separate audited actions. Both deny new requests immediately in the registry and remain bounded by a revocation cache ceiling of 60 seconds. A client cannot choose a different project or environment through an MCP request body.
+
+## Generated profiles
+
+- Native MCP 2026 uses Streamable HTTP and protocol revision `2026-07-28`.
+- Compatibility clients use the same scoped endpoint with revision `2025-11-25`.
+- The Codex stdio profile reads an Authentik app password from a user-only file, obtains a short-lived M2M token and refreshes it before expiry. Static bearer-token environment variables remain supported for compatibility.
+- Inspector uses an explicit LAN/internal endpoint and is enabled only through the Compose `inspector` profile.
+
+Configuration contains endpoint, protocol, transport, scopes, client ID, Authentik username and credential reference only. `scripts/authentik_provision_mcp_service_account.py`, `scripts/provision_machine_client.py`, and `scripts/install_codex_mcp.ps1` form the reproducible operator path.
+
+## Bridge safety
+
+The bridge accepts only MCP initialization/notification/ping, bounded tool, resource and prompt methods; rejects oversized or invalid messages; never shells out; never logs credentials; handles JSON and SSE responses; and never includes authorization material in responses. Direct remote OAuth remains the preferred future path once the deployed Authentik supports policy-bound Dynamic Client Registration.
+
+Reconciliation preserves only explicitly managed active clients. Pending clients remain disabled, operator-disabled clients stay disabled, and revoked clients cannot be silently reprovisioned.

docs/04-mcp/CODEX_INTEGRATION.md

@@ -0,0 +1,65 @@
+# Codex integration
+
+## Production profile
+
+Codex uses one MCP server per project/environment. Production endpoints are:
+
+```text
+https://mcp.example.com/mcp/ludarium/prod
+https://mcp.example.com/mcp/vacatureradar/prod
+https://mcp.example.com/mcp/mobilityops/prod
+```
+
+The deployed Authentik `2025.12.6` supports M2M client credentials and app
+passwords, but not the policy-bound Dynamic Client Registration introduced in
+Authentik `2026.8`. Codex therefore uses the repository's stdio bridge. The
+bridge retrieves five-minute Authentik access tokens and refreshes them without
+putting tokens or app passwords in Codex configuration.
+
+Each profile requires:
+
+- a dedicated Authentik service account and app password;
+- the exact Authentik user UUID as the Hub client subject;
+- one active Hub binding to one project/environment;
+- a local credential file readable only by the current OS user;
+- a Codex stdio entry created by `scripts/install_codex_mcp.ps1`.
+
+## Operator sequence
+
+1. Generate the local credential with `scripts/new_codex_credential.ps1`.
+2. Pipe `scripts/authentik_provision_mcp_service_account.py` into the Authentik
+   container's `ak shell`, passing the credential through a temporary file.
+3. Run `scripts/provision_machine_client.py` in the control API container with
+   the exact returned subject UUID. Supply `--client-id` when activating a
+   pending UI-created record.
+4. Install the profile:
+
+```powershell
+.\scripts\install_codex_mcp.ps1 `
+  -Project '<project>' `
+  -Environment 'prod' `
+  -HubClientId '<hub-client-uuid>' `
+  -OAuthUsername 'svc-mcp-codex-<project>' `
+  -SecretFile '<user-only-credential-file>'
+```
+
+5. Restart Codex and verify the server with `codex mcp list`.
+6. Prove `initialize`, `tools/list`, one read-only invocation, audit creation,
+   and a cross-project denial.
+
+Never copy an app password into `config.toml`, a command argument, Git,
+evidence, UI output, logs or chat. Disabling/revoking the Hub client denies new
+calls even if an Authentik token has not yet expired.
+
+## Useful workflows
+
+Runtime connectors publish these user-invoked prompts:
+
+- `project-context-pack` and `pre-change-impact-review`;
+- `repository-change-review` and `release-readiness`;
+- `production-incident-triage` and `deployment-health-review`;
+- `fleet-operations-morning-brief`.
+
+The Gitea surface also exposes pull-request summaries, bounded changed-file
+metadata, and commit/CI statuses. The Unraid surface exposes an aggregate
+project summary in addition to container health, inspect and bounded logs.

docs/04-mcp/COMPATIBILITY_AND_VERSIONING.md

@@ -0,0 +1,32 @@
+# Compatibility and Versioning
+
+## Tool lifecycle
+
+- additive optional output fields are allowed within a major version;
+- required input changes or semantic breaks require a new major contract;
+- deprecated tools remain discoverable only for clients still bound to them and include replacement metadata;
+- removals require usage evidence and an announced date.
+
+## Gateway upgrades
+
+A ContextForge or SDK upgrade requires:
+
+1. backup;
+2. release-note review;
+3. clean-room test environment;
+4. MCP discovery and invocation matrix across supported revisions;
+5. auth/header/proxy tests;
+6. connector contract suite;
+7. rollback/restore proof;
+8. recorded version/digest update.
+
+## Client matrix
+
+At minimum test:
+
+- native 2026 remote MCP client;
+- compatible 2025-era client;
+- stdio bridge;
+- MCP Inspector;
+- project-bound machine client;
+- revoked/invalid client negative cases.

docs/04-mcp/ERROR_MODEL.md

@@ -0,0 +1,60 @@
+# Error Model
+
+## Stable categories
+
+- `AUTHENTICATION_REQUIRED`
+- `TOKEN_INVALID`
+- `ACCESS_DENIED`
+- `PROJECT_NOT_FOUND`
+- `RESOURCE_NOT_REGISTERED`
+- `CONNECTOR_DISABLED`
+- `CONNECTOR_UNAVAILABLE`
+- `TARGET_UNAVAILABLE`
+- `VALIDATION_FAILED`
+- `RATE_LIMITED`
+- `TIMEOUT`
+- `RESULT_TOO_LARGE`
+- `UPSTREAM_PROTOCOL_ERROR`
+- `INTERNAL_ERROR`
+
+## Response rules
+
+- do not reveal whether a forbidden resource exists when that leaks scope;
+- include a trace ID;
+- use retryability metadata;
+- keep user-facing messages useful but sanitized;
+- log detailed internal exceptions only in protected logs;
+- translate target-specific errors into stable categories while preserving a safe diagnostic code.
+- separate `retryable` from `safeToRetry`: transient writes may be retryable only
+  after their exact state is reconciled, never by blind transport replay;
+- identify the failed operation and subsystem without returning target URLs,
+  credentials, raw headers or stack traces;
+- include expected/actual state and a bounded recovery hint when optimistic state
+  changed;
+- keep the stateless MCP session usable after an operation error.
+
+Example:
+
+```json
+{
+  "error": {
+    "code": "CONNECTOR_UNAVAILABLE",
+    "category": "transient",
+    "message": "The Unraid inventory connector is temporarily unavailable.",
+    "operation": "unraid.container.health",
+    "subsystem": "upstream_unraid",
+    "retryable": true,
+    "safeToRetry": true,
+    "correlationId": "...",
+    "sessionId": null,
+    "upstreamStatus": 503,
+    "expectedState": null,
+    "actualState": null,
+    "recoveryHint": "Retry the unchanged read after the bounded backoff."
+  }
+}
+```
+
+The dataplane retries only MCP protocol reads and catalogued R1 tools, once.
+Connector-local Gitea GETs use at most three bounded attempts. R2, R3 and unknown
+operations are never automatically retried.

docs/04-mcp/KNOWLEDGE_INTAKE.md

@@ -0,0 +1,34 @@
+# ChatGPT to Knowledge Hub document intake
+
+The separate MCP Hub exposes ten focused tools at `/mcp/knowledge-hub/prod`: search and project context; scanned attachment text extraction; workspace roots, children and current page reads; attachment and caller-supplied Gitea text proposals; review submission; and status. `analyze_knowledge_files` and `extract_knowledge_files` advertise `_meta.openai/fileParams: ["files"]`. ContextForge omits connector tool metadata, so the dataplane restores this exact binding only for these two vetted attachment schemas on `knowledge-hub/prod`. The connector scans every source within fixed limits. Extraction returns real text in bounded pages with per-file coverage and an actor-bound authenticated continuation cursor; it has no proposal side effects. A proposal includes the selected create or update publication, and only a human reviewer in Knowledge Hub can approve or publish it.
+
+For early attachment validation failures, connector audit may include a fixed `input_reason` label such as `attachment_file_id_invalid`. The label identifies the rejected check only; attachment IDs, URLs, names, and content are never recorded.
+
+## Access boundaries
+
+- The ChatGPT OAuth identity must be bound in MCP Hub to the exact `knowledge-hub` project and `prod` environment. MCP Hub signs the connector identity assertion and applies the tool policy. A supplied target Knowledge Hub `project_id` must be in `KNOWLEDGE_HUB_ALLOWED_PROJECT_IDS`. Project context always requires this ID. When `project_id` is omitted, search, extraction, proposal creation, review submission and status use the token-scoped workspace only if `KNOWLEDGE_HUB_WORKSPACE_READ_ENABLED=true` and the signed connector identity is exactly `knowledge-hub/prod`. This setting defaults to `false`; an empty target project allowlist is accepted only when workspace access is enabled.
+- Workspace roots and children are cursor paged. Current page Markdown is character paged and carries an ETag; later slices require the same ETag. Select a parent page or workspace root for a create, or compare the complete current page and include its ETag for an update.
+- For Gitea sources, first read the complete file through the separate Gitea MCP. Pass the bounded UTF-8 text and caller-supplied `itworx-git://` URI, ref, commit and full Git blob SHA to `create_text_source_proposal`. The intake connector checks that the supplied text matches that SHA and scans it. `source_complete=true` and repository provenance remain caller assertions; the connector does not fetch a repository or independently verify its contents.
+- A publication Markdown body is limited to 32,000 characters and analysis to 32,000 characters. An attachment or PDF with no extractable text is rejected before a proposal can be created; OCR is outside this path. DOCX extraction reads the main document text and may omit header/footer content, so review those sections separately before submitting a proposal.
+- The connector uses a separate Knowledge Hub service account with exactly `knowledge:search`, `projects:read`, `pages:read`, and `ingestion:write`. It cannot approve or publish proposals. Its identity assertion uses a dedicated `knowledge_hub_ingestion_identity_key` secret mounted only in the dataplane and intake connector, separate from the other connector HMAC key.
+- The Knowledge Hub token is loaded only from `/run/secrets/knowledge_hub_ingestion_token`. Signed attachment download URLs and token values must not appear in logs, audit events, or persisted proposal analysis.
+- An internal retry of a failed proposal is available only with the current ETag, `retryEligible=true`, and a fresh operation key. It is not exposed as an MCP tool or a publication action.
+- The connector and scanner are opt in. The default `INGESTION_CONNECTOR_ENABLED=false` excludes the new project and gateway from reconciliation, leaving existing MCP routes available during staging. The default dataplane does not mount or require the new identity key; the final intake production overlay adds that mount when the intake route is activated.
+
+## Production activation
+
+The live `wiki.example.com` Authentik proxy requires a narrow unauthenticated-path exception for the connector's API routes. Its proxy provider uses:
+
+```text
+^/api/v1/(?:search|projects/[0-9a-fA-F-]{36}/context|pages(?:/roots|/[0-9a-fA-F-]{36}(?:/children)?)|ingestion-proposals(?:/[0-9a-fA-F-]{36}(?:/(?:sources|retry))?)?)$
+```
+
+This only passes requests to Knowledge Hub's own bearer authorization. An anonymous JSON request to each allowed route must return 401; `/` and unrelated API routes must continue to redirect to Authentik. Keep the exception aligned with the connector's fixed route allowlist.
+
+1. Deploy the Knowledge Hub admin preset that issues the four-scope intake token, including `pages:read`. Create the dedicated token in Beheer and place it in the operator-owned secret directory as `knowledge_hub_ingestion_token` with ownership matching the MCP Hub service UID/GID. Generate a separate random 32-byte-or-longer `knowledge_hub_ingestion_identity_key` in that directory. Keep both secrets out of Git and deployment logs.
+2. Verify a current backup and the pinned images. Set `KNOWLEDGE_HUB_ENDPOINT` to the actual HTTPS Knowledge Hub origin. Set `KNOWLEDGE_HUB_ALLOWED_PROJECT_IDS` to comma-separated UUIDs if project-scoped intake is needed; for workspace-only courses, keep it empty and explicitly set `KNOWLEDGE_HUB_WORKSPACE_READ_ENABLED=true` after reviewing the workspace-wide permission. Pin `CONNECTOR_INGESTION_IMAGE` to an immutable digest. Render Compose with `docker-compose.ingestion.prod.yml` **last**, after `docker-compose.prod.yml` and `docker-compose.autodeploy.yml`; inspect that the final connector image is the digest and `build` is absent before starting it.
+3. Start `ingestion-clamd` and `connector-ingestion` with the `knowledge-intake` Compose profile while `INGESTION_CONNECTOR_ENABLED=false`. Wait for current scanner signatures and connector readiness. Verify the four token scopes, a project context read when project intake is configured, and roots/current-page reads when workspace access is enabled.
+4. Add an enabled, exact OAuth client binding for `knowledge-hub/prod`. Set `INGESTION_CONNECTOR_ENABLED=true` on control API and worker, then restart only those services and verify gateway tool parity, project route, and all ten advertised tool schemas.
+5. Connect the MCP URL in ChatGPT. Exercise search, roots/children and a complete current-page read; attach a benign test PDF and read every extraction page; then create a complete proposal and submit it. Confirm it reaches `ReadyForReview`; approve/publish through the Knowledge Hub UI only. Check that a rejected file leaves no proposal or unscanned persisted source.
+
+If staging fails, disable the `knowledge-hub/prod` OAuth client binding, set `INGESTION_CONNECTOR_ENABLED=false`, and reconcile again before stopping the connector. This disables an already created intake virtual server as well. Retain proposal IDs and audit evidence for human review. Do not delete Knowledge Hub data to roll back the connector.

docs/04-mcp/MCP_PROTOCOL_PROFILE.md

@@ -0,0 +1,34 @@
+# MCP Protocol Profile
+
+## Supported revisions
+
+- primary: `2026-07-28`;
+- compatibility: `2025-11-25` and earlier revisions supported by ContextForge/SDK v2.
+
+## Transports
+
+- remote dataplane and connectors: Streamable HTTP;
+- local bridge and tests: stdio;
+- no custom WebSocket protocol.
+
+## Server behavior
+
+- explicit server identity and version;
+- tool/resource list responses are cacheable only within correct project/client scope;
+- structured outputs are validated against declared output schemas;
+- requests and results include correlation metadata;
+- maximum request body at or below 4 MiB;
+- per-tool timeouts and output budgets are stricter than global limits;
+- protocol errors are distinct from target-system errors.
+
+## 2026 headers
+
+Where available, `Mcp-Method` and `Mcp-Name` can support routing, metrics, and rate limits. They are hints from a validated protocol path, not the sole authorization input. Compatibility traffic may require bounded body parsing by trusted components.
+
+## Durable work
+
+Do not depend on MCP Tasks in v1. Use `operation_id` in the management domain and expose status through ordinary Hub APIs/resources when needed. Add a protocol adapter only after the official SDK supports the extension.
+
+## Client bridge
+
+A local bridge may translate stdio to remote HTTPS. It stores credentials in the local OS-protected environment/configuration and never prints tokens. The bridge is optional; native remote MCP is preferred.

docs/04-mcp/RESOURCES_AND_PROMPTS.md

@@ -0,0 +1,29 @@
+# Resources and Prompts
+
+## Resource URI schemes
+
+```text
+itworx-project://<project>/<environment>/status
+itworx-docs://<project>/<source>/<path-or-id>
+itworx-git://<project>/<repository>/<ref>/<path>
+itworx-unraid://<project>/<environment>/container/<registered-ref>
+itworx-audit://event/<id>
+```
+
+Rules:
+
+- custom URIs do not reveal physical server paths;
+- identifiers are canonical and encoded once;
+- resource access repeats project/client authorization;
+- large resources use metadata plus bounded retrieval;
+- symlink and path containment rules apply before reading content.
+
+## Initial prompts
+
+- `project-health-review`;
+- `incident-triage`;
+- `repository-onboarding`;
+- `release-readiness-review`;
+- `security-posture-review`.
+
+Prompts structure a user-initiated workflow. They do not grant permissions, hide tool calls, or autonomously execute write actions.

docs/04-mcp/TOOL_CONTRACTS.md

@@ -0,0 +1,62 @@
+# Tool Contracts
+
+## Naming
+
+```text
+<domain>.<resource>.<action>
+```
+
+Examples:
+
+```text
+project.status.get
+gitea.repository.list
+gitea.file.read
+knowledge.document.search
+unraid.container.list
+unraid.container.inspect
+unraid.container.logs
+```
+
+Names are lowercase ASCII, dot-separated, stable, and globally unique within the Hub. Do not include project names in canonical tool names; project scope comes from the virtual server and identity context.
+
+## Required manifest fields
+
+- canonical name and semantic version;
+- title and managed description;
+- connector type;
+- input and output JSON Schema;
+- risk class;
+- required capability and scopes;
+- allowed environment classes;
+- timeout, rate, row/item, and byte limits;
+- redaction profile;
+- idempotency and side-effect annotation;
+- lifecycle status and replacement when deprecated.
+
+## Inputs
+
+- reject unknown fields by default;
+- use enums and bounded strings;
+- use opaque registered references rather than raw paths/URLs;
+- pagination uses bounded `limit` and opaque cursor;
+- environment/project are not accepted when endpoint context already determines them.
+
+## Outputs
+
+- structured data first;
+- stable machine-readable error code;
+- explicit truncation and cursor;
+- source and generated time metadata;
+- no secrets, raw auth headers, or unbounded logs;
+- validate against the output schema before returning.
+
+## Side effects
+
+Every v1.0 tool is `readOnly: true`. The v1.1 Gitea exception is an exact R2
+allowlist of six tools: branch, issue, comment, bounded file and pull-request
+creation/update. MCP annotations must truthfully mark them non-read-only and
+the client must confirm the external action. The server independently enforces
+the project binding, R2 policy, separate write credential, safe change-branch
+namespace, input budgets and target allowlist. A tool whose target API might
+mutate through a GET-like endpoint remains prohibited.