# 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.