Files
Dashboard_Projects_Management/docs/research/project-documentation-wiki-evaluation.md
T
2026-10-20 14:17:46 +02:00

12 KiB
Raw Blame History

Project documentation and MCP evaluation

Research snapshot: 20 October 2026. Repository inspected at dd1ee39 with uncommitted local changes; this report makes no runtime changes.

Recommendation

Go for a small native Django documentation module; do not install or fork a wiki for the MVP. Treat the repository's Markdown files as the source of truth. Import a versioned, project-scoped snapshot into the database for browsing and MCP retrieval, then show its source commit and freshness on every read. This gives agents a bounded, searchable map of project context without rescanning the repository each time. The database index is a cache of a declared Git snapshot, not an independent authority.

The first milestone should be read-only documentation: upload a Markdown ZIP, review its preview, publish the imported snapshot, browse a tree, search, and use docs_list, docs_search, and docs_read over MCP. Do not accept MCP edits until there is a concrete export/reconciliation workflow. Later edits can be proposed revisions with an explicit base source commit and document hash, downloaded as Markdown ZIP or applied through a separately approved Git workflow. Never silently alter the published snapshot or repository.

Evidence in this project

Existing part Reuse / gap
projects/models.py: Project has git_repository_url, owner, and Membership; Card and CardRevision store Markdown and revisions Reuse project identity and access policy. The URL is metadata only; neither Django nor MCP clones repositories. Documents need their own path, source commit/hash, and version model, separate from Kanban cards.
projects/services.py: accessible() and project_for(..., write=True) Reuse for every document query and mutation. Owner/editor can import; viewer can read. Do not rely only on template visibility or Django's global model permissions.
projects/templatetags/project_markdown.py Python-Markdown plus nh3 already sanitizes rendered HTML. Extract a shared renderer function and use it for docs; add a controlled link resolver for relative .md links. Current sanitizer allows only http, https, and mailto URLs, so ordinary relative links are stripped until resolved.
projects/views.py, projects/urls.py Authenticated project pages and CSRF-protected POST patterns already exist. Add project-scoped docs routes and a navigation link without changing the board data model.
mcp_server/server.py MCP uses MCPServer, projects:read/projects:write, _project, _safe, and bounded list patterns. Add document tools through the same service layer. Current cards_search and search_global return full Markdown per hit; docs search should return short snippets and metadata to stay useful at scale.
config/settings.py SQLite is the configured database. Design search to work with SQLite first; consider SQLite FTS5 after profiling. PostgreSQL search is not a current dependency.
projects/attachments.py, docs/card-attachments.md Useful reference for private storage, upload limits, and provenance, but card attachments do not provide a navigable documentation tree or searchable document text.

Candidate comparison

Candidate Current release / licence Fit and integration cost Verdict
django-wakawaka 1.7, 7 Feb 2026; MIT. Its published compatibility matrix ends at Django 5.2, with no declared Django 6.1 test. Small dependency, but its model has a global slug, no project foreign key; views query all pages and use global Django permissions. Its page template uses `urlize wikify
django-wiki (wiki) 0.13.0, 31 Jul 2026; GPL-3.0. Package metadata requires Django>=4.2,<6.1 and several app dependencies. Mature, revisioned wiki with Markdown and tree features, but dependency constraint conflicts with this repo's Django>=6.1,<6.2. Its plugin and renderer stack would add a second content system. No-go on current stack.
Waliki 0.8.1, 26 Mar 2017; BSD. Git-backed premise is attractive, but its published documentation targets Django 1.8/1.9-era Python. No evidence of current Django 6.1 compatibility. No-go; major port/fork risk.
djiki 0.9, 1 May 2022; BSD-3-Clause. Its inspected models use globally unique page titles/language, not project-scoped file paths. Published classifiers stop at Python 3.10, with no current Django 6.1 evidence. No-go for this use case.
Native Django docs module No new wiki dependency or third-party licence Smallest domain fit: project/path uniqueness, Git provenance, import preview, permission checks, MCP output shape, and existing sanitizer can be designed together. Recommended.

The Wakawaka renderer verdict is especially clear: there is no Markdown renderer to replace. A template override could call safe_markdown, but the default CamelCase substitution and global data model still conflict with normal repository Markdown. Forking it would create long-term maintenance without removing the custom work.

Proposed shape

  1. ProjectDocument: project, normalized case-preserving POSIX path (e.g. README.md, docs/architecture/mcp.md), raw Markdown, content SHA-256, title extracted from heading or filename, revision, source commit, imported time, and status. Unique (project, path); index (project, path) and search fields. A separate DocumentRevision stores immutable previous content, actor, timestamp, and source/proposal type if editing is added.
  2. DocumentSnapshot or import batch records project, source commit supplied by uploader, ZIP hash, imported time, counts, and outcome. Record whether the commit was verified against a trusted repository checkout; an uploader-supplied SHA alone is unverified provenance. A published snapshot stays queryable until a complete replacement succeeds. Display freshness as "as of commit X / imported at Y"; do not claim current Git state unless verified.
  3. Navigation is generated from paths, with README.md as landing page when present and AGENTS.md visible as a first-class context file. Preserve exact Markdown text for MCP. Resolve relative links against the source document's parent path; rewrite only links to imported documents and anchors. External links retain the current sanitizer's URL restrictions. Report broken internal links on import.
  4. A project docs page offers tree, search, raw/view modes, source commit, stale/unverified badge, and import/export controls for editors. Missing docs state explains how to upload an archive. Use normal login, CSRF, and project authorization. Do not show a success state after a partial import failure.

MCP contract and agent context

Tool Return shape / controls
docs_list(project, prefix?, cursor?, limit?) Paths, titles, hashes, revision, snapshot/commit, modified time; stable path order, at most 100 items, cursor pagination.
docs_search(query, project?, cursor?, limit?) Search only accessible projects; path/title, bounded excerpt, project ID, commit/hash, and direct read locator. Limit query and excerpt size. Search metadata first, full text second. Do not return whole files per hit.
docs_read(project, path, revision?, start_line?, line_count?) Exact Markdown or a bounded line window, total line count, hash, source commit, verified/stale status, canonical path. Reject invalid paths and excessive output; permit explicit paging for large files.

For the user's memory goal, start each work session with docs_list or targeted docs_search, then docs_read for the few relevant files. A small curated docs/PROJECT_CONTEXT.md or existing AGENTS.md can point to architecture, conventions, deployment, and current decisions; the index should not auto-concatenate all documents into every response. Keep path/hash/commit in replies so the agent can tell when context is old and inspect live source before changing code. The docs index reduces repeated discovery, but it cannot guarantee that unimported code changes are reflected.

Later docs_create/docs_update should require projects:write, project editor rights, normalized path, size cap, and expected_revision plus base_source_commit/content hash. Store proposals separately from published Git-backed content. Guard deletion as a proposal or tombstone, with explicit export and conflict handling. No direct Git fetch/push, credentials, or arbitrary filesystem paths in MVP.

ZIP workflow and controls

Preview before commit: accept only UTF-8 .md files from declared roots (README.md, AGENTS.md, docs/** or a selected docs subtree); display additions, changes, removals, broken links, and conflict warnings. Reject duplicate normalized paths, absolute paths, .., backslashes or ambiguous separators, symlinks and other nonregular entries, hidden control files, and oversized archives. Bound compressed bytes, expanded bytes, file count, per-file bytes, compression ratio, and nesting depth; inspect ZIP metadata before reading and stream under limits. Normalize Unicode and define case-collision behavior. Require the expected previous snapshot ID/commit before a re-import; publish atomically. Export Markdown paths plus a manifest with source commit and hashes; exclude server-only metadata and secrets. Import must never extract directly into the repository or execute contents.

Work estimate and stages

These are rough engineering estimates, not commitments; integration and review may change them.

Stage Scope Estimate
1 Models/migrations, service authorization, path validation, snapshot provenance, tests 2–3 days
2 ZIP preview/import/export, limits, link checks, atomic replacement, tests 2–4 days
3 Browsing/search UI, renderer/link adapter, accessible states 2–3 days
4 Read-only MCP tools, pagination/output limits, permission tests 1–2 days
Later Proposed edits/reconciliation/export, conflict handling 2–4 days after workflow decision

An MVP is roughly 7–12 engineering days. The main uncertainties are archive scale, exact desired Git provenance, and whether a read-only import meets the workflow. No implementation is blocked by a missing wiki library.

Decisions before implementation

  • Choose the ingestion boundary: manual ZIP upload first (recommended) or trusted server-side checkout. The current Git URL is metadata and must not become an arbitrary fetch target without host allowlisting, credential design, and SSRF controls.
  • Choose whether the initial import mirrors only tracked documentation files or allows uploaded notes not in Git. If Git is authoritative, label non-Git notes separately.
  • Decide when a snapshot is considered stale. An import timestamp alone cannot prove repository freshness; a trusted commit check or explicit manual refresh is needed.
  • Decide whether cross-project docs_search should be enabled for every authorized membership or opt-in for sensitive projects. The existing MCP search_global searches across all accessible projects, so the former is consistent with present behavior.

Sources and inspection method

Local sources: requirements.txt, config/settings.py, projects/models.py, projects/services.py, projects/views.py, projects/templatetags/project_markdown.py, mcp_server/server.py, projects/attachments.py, and README.md. Upstream release metadata came from the linked PyPI pages; package source distributions were inspected directly for models, views, templates, and dependency declarations. These findings establish design fit, not runtime compatibility tests against Django 6.1.