Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

README.md

@@ -0,0 +1,62 @@
+# ITWorx MCP Hub
+
+A self-hosted governance platform for connecting AI clients to approved tools and knowledge. The Hub scopes capabilities by project, environment and client identity, while retaining policy decisions and audit attribution.
+
+## What it provides
+
+- A management UI for projects, readiness, policies, connector health and audit history.
+- An MCP dataplane and router with authenticated, bounded tool discovery and invocation.
+- Target-specific integrations for knowledge, Gitea, ProjectBrain, AppOps and infrastructure.
+- OIDC client onboarding and separately scoped service-to-service credentials.
+- Explicit deny-by-default authorization inside sensitive connectors.
+- PostgreSQL persistence, migrations, workers and recovery tooling.
+
+The gateway, API and normal connectors never receive a Docker socket. Only the dedicated read broker may access it, through its purpose-built read-only interface. There is no general shell, unrestricted SQL or arbitrary filesystem tool.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  Client[MCP client] --> Router[Authenticated dataplane]
+  UI[Management UI] --> API[Control API]
+  API --> DB[(PostgreSQL)]
+  Router --> Policy[Scoped connector authorization]
+  Policy --> Tools[Approved tools and knowledge]
+```
+
+`apps/web` contains the React management UI; `services` contains runtime services; `connectors` supplies integrations; `packages` holds shared policy/contracts. Compose definitions, image build contexts and database migrations live in `infrastructure`.
+
+## Deployment
+
+Requirements: Docker with Compose, Python 3.13, Node.js 24 and pnpm 10.33. The production stack is intentionally configuration-driven and has no universal one-command public demo.
+
+1. Copy `infrastructure/compose/.env.example` to an untracked `.env` in that directory.
+2. Replace every `REPLACE_*` input: dedicated host paths, bind addresses, OIDC issuer/client settings, project/resource bindings and immutable owned image references.
+3. Build the owned images from the supplied contexts and use immutable image digests. Provision the named secret files outside Git according to [Secret storage](infrastructure/secrets/README.md).
+4. Review [Compose requirements](infrastructure/compose/COMPOSE_REQUIREMENTS.md), configure TLS routing and run migrations before starting the full stack.
+5. Validate authentication, connector reachability and denied operations before onboarding clients.
+
+```bash
+cd infrastructure/compose
+docker compose --env-file .env config --quiet
+# Start only after required inputs, secret files and image references are reviewed.
+docker compose --env-file .env up -d
+```
+
+The public snapshot omits the owner's catalog project, workspace and resource bindings. Create your own scoped bindings before catalog reconciliation; no production project access is preconfigured.
+
+External OIDC, registries and connector services are operator-supplied dependencies. Do not substitute real production credentials into examples. Optional connectors can remain unconfigured. The development override is an engineering environment, not an internet-ready deployment.
+
+## Client onboarding and security
+
+See [Client onboarding](docs/04-mcp/CLIENT_ONBOARDING.md) and [Security invariants](docs/02-security/SECURITY_INVARIANTS.md). A visible tool is not authorization to use it: project, environment, resource identity and caller privileges are checked independently. Report issues privately according to [SECURITY.md](SECURITY.md).
+
+## Development
+
+Python dependencies are locked by `uv.lock`; Node workspaces are locked by `pnpm-lock.yaml`. Tests cover authorization, contracts and runtime behavior. Canonical `python scripts/verify.py` additionally checks private design/evidence metadata; that complete archival gate belongs to the private repository. For public source development, install locked dependencies and run the relevant unit/integration tests and `apps/web` build. Integration/browser tests require their documented external services.
+
+## Public source and license
+
+`ITWorx_MCP_Hub-Public` is automatically exported from canonical private `main`. It contains reviewed source, tests and reusable deployment definitions, with example domains and paths substituted for operational topology. Private Git history, live inventories, evidence, internal Actions and production-specific delivery overrides are excluded.
+
+The project remains proprietary under [LICENSE.md](LICENSE.md). Public visibility grants no additional reuse rights; third-party dependencies retain their licenses.