163 lines
5.4 KiB
Markdown
163 lines
5.4 KiB
Markdown
# 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.
|