73 lines
5.2 KiB
Markdown
73 lines
5.2 KiB
Markdown
# 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
|
|
|
|
Container deployment requires Docker with Compose, configured images and external services. Source development/build tooling uses 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).
|
|
|
|
## Onboard one client before expanding access
|
|
|
|
1. Register one project, environment and client identity with explicit resource bindings.
|
|
2. Configure only the connector required for that use case and inspect its readiness.
|
|
3. Discover the client's permitted tools and invoke one bounded read operation.
|
|
4. Check the corresponding policy decision and audit attribution.
|
|
5. Confirm that an out-of-scope request is denied before granting additional capabilities.
|
|
|
|
Tool discovery, connector reachability and authorization are separate checks. An empty tool list can reflect missing bindings or denied scope; it is not a reason to grant global access. Preserve database state, external secret files and the deployment configuration together for recovery.
|
|
|
|
## 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.
|