Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817
This commit is contained in:
Public Source Publisher committed
commit
ad8ad252a9
825 files changed
+124216
No files matched your search
@@ -0,0 +1,162 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user