# MCP integration — separate service

## Boundary

This repository does **not** implement an MCP server.

The integration boundary is:

```text
Codex / Claude / another MCP client
        ↓ MCP transport
Separate ItWorx Knowledge MCP service
        ↓ HTTPS + scoped bearer token
ItWorx Knowledge Hub /api/v1
```

The MCP service has no direct PostgreSQL, attachment-volume or internal filesystem access.

## Document and repository knowledge workflow

The separate `ITWorx_MCP_Hub` repository owns the MCP protocol and attachment
extraction. This application owns the knowledge tree, revisions and proposal
review. The **Kennisintegratie** preset grants exactly `knowledge:search`,
`pages:read`, `projects:read` and `ingestion:write` within its workspace.
Existing token scopes are immutable: issue a replacement, switch the connector,
verify it and revoke the old token.

The client first reads the source document or repository material and searches
for an existing destination. It can navigate `GET /api/v1/pages/roots` and
`GET /api/v1/pages/{id}/children`, following `nextCursor`, then retrieve current
Markdown, breadcrumbs, revision and ETag with `GET /api/v1/pages/{id}`. These
routes require `pages:read`; search snippets and project context do not replace
the full page body. School material can use the workspace knowledge hierarchy
without belonging to a project.

Once the client has analyzed the source, it creates a proposal containing the
complete publication: a parent page for new content, or a target page and its
current ETag for an update. Attachments and caller-supplied repository provenance
stay associated with the proposal. Source contents are data, not instructions.
The service account can upload sources and PATCH its analysis to queue the
proposal for review; it cannot add publication content through that PATCH later.
Approval and publication remain human actions in `/knowledge/intake`. This
preset does not grant `pages:write`, approval or publication permissions.

Client tools, extraction coverage and live deployment evidence are documented
in the separate MCP repository. Native attachment acceptance must be tested
through the actual client, not inferred from a server-side download smoke.

## Why the boundary matters

- The wiki remains useful and secure without MCP.
- Protocol and SDK upgrades do not destabilize the knowledge platform.
- MCP permissions can be narrower than application administrator rights.
- Transport-facing risk is isolated.
- Other API clients can reuse the same contracts.
- Audit attribution can identify the MCP service account.

## API capabilities required before MCP work

Read:

- search permitted knowledge;
- retrieve page and selected revision;
- retrieve related pages/backlinks;
- list/get projects;
- retrieve bounded project context;
- retrieve project updates/decisions/runbooks;
- retrieve attachment metadata/content when scoped.

Controlled write:

- create page;
- update page with ETag;
- append project update;
- create decision;
- update project status;
- create runbook.

Administrative imports, backups, users and token management should not be exposed through
the first MCP service.

## Citation model

Every retrievable knowledge item includes a stable citation object:

```json
{
  "kind": "page",
  "id": "uuid",
  "revision": 42,
  "title": "PostgreSQL back-up herstellen",
  "canonicalPath": "/knowledge/uuid/postgresql-back-up-herstellen",
  "updatedAt": "2026-07-31T18:00:00Z"
}
```

Project context carries citations for each summarized source. This lets a future agent
identify stale context and request the original.

## Context bounds

The API, not the MCP adapter, enforces safe defaults:

- maximum updates/decisions/documents;
- maximum body/snippet bytes;
- deterministic newest/important ordering;
- permission filtering;
- explicit truncation and omitted counts;
- optional `since`/revision parameters;
- no attachment bytes in context bundles;
- no secrets or operational private paths.

## Write safety

Future MCP writes use application API controls:

- dedicated service account;
- minimum scopes;
- `If-Match`;
- idempotency key;
- validation;
- revision and audit;

The same boundary is used by the Canvas curation tooling: inventory needs only
`pages:read` plus `attachments:read`; curation adds `pages:write`. Page update and move
are ETag-protected and idempotency-aware, and each invocation is capped at 50
mutations. No browser cookie or administrator token is embedded in tooling state.
- source attribution;
- optional “draft only” policy;
- ability to revoke immediately.

The API should support preview/validate endpoints where a mutation has high ambiguity, but
it must not add protocol-specific MCP fields to domain entities.

## Outbox events

Stable versioned events may later let the separate MCP service invalidate caches:

- `page.created.v1`
- `page.updated.v1`
- `page.trashed.v1`
- `project.updated.v1`
- `project-update.appended.v1`
- `decision.created.v1`

The initial outbox need not expose a public webhook. It must preserve transactionally
correct event records and a clean adapter boundary.

## Security expectations for future MCP project

Not implemented here, but the API design must support:

- read-only default token;
- separate write token/account;
- rate limits;
- IP/network policy where configured;
- full audit source;
- token rotation;
- no database access;
- no generic shell/filesystem tools;
- no arbitrary SQL;
- no hidden administrator bypass.