Agent context — Project MCP workspace

This file orients an AI agent (or human) working in this repository: what the workspace is, how documentation is structured, constraints and conventions, and how to build and serve the docs locally.

Workspace description

Project MCP is a design and documentation repository for a Software Project Management MCP server and related applications. The repo currently contains:

  • Design docs in docs/: canonical definitions, architecture, data model, MCP surface, tech requirements, deployment, identifiers, gap analyses, implementation plan, testing, deployment plan, web app spec, and mobile app spec.
  • Documentation tooling: Jekyll (Ruby) in docs/ with a custom layout; docs are published to GitHub Pages via the Publish docs to GitHub Pages workflow.
  • No implementation yet: the plan describes a future .NET MCP server, Blazor web app, and Avalonia mobile app backed by PostgreSQL; code will be added when implementation starts.

The design is methodology-agnostic (no prescribed agile/waterfall). It covers enterprises, projects, work, work items, tasks, milestones, releases, requirements, issues, standards, keywords, and related entities, with a clear identifier scheme and MCP tool/resource surface.

Note: Work items and tasks are the same entity; a task is a work item with level = Task.

Constraints and conventions (for agents and edits)

These conventions have been established in this workspace and should be respected when editing or adding content. A formal, single-reference version is in 17 — Guardrails.

  1. Gap identifiers
    Gaps are tracked in 16 — Gap Analysis (TODO) with stable identifiers GAP-001+ when needed. Reference gaps by id in chat or in other docs. When a gap is remediated, mark the item with [x] and optionally add a “Resolved: …” note.

  2. Gap and remediation format
    Each gap is written as a todo: - [ ] **GAP-XXX** — **Title:** Description. *Remediate: …* so progress can be tracked by toggling the checkbox.

  3. Document numbering
    Design docs use a two-digit prefix (00–16) for ordering and stable filenames. New design docs should follow the next number (e.g. 17) and be added to the docs index.

  4. Cross-references in docs
    Links between docs use the built site form: [03 — Data Model](03-data-model.html) (.html), because the published site is generated by Jekyll. Source files remain .md.

  5. Docs index
    The canonical list of design docs is index. When adding a new doc, add a row to the table with title, link (.html), and a short description.

  6. Single source of truth
    Definitions live in 00 — Definitions, the data model in 03 — Data Model, the MCP surface in 04 — MCP Surface, identifiers in 08 — Identifiers. When changing an entity or concept, update the canonical doc and any references (including the gap tracker if it closes a gap).

  7. No hardcoded secrets
    Configuration (e.g. OAuth client IDs, DB URLs) is documented as env or config keys; no secrets in repo.

Table of contents — document descriptions

Doc Description
Index Documentation hub: table of all design docs with links. Start here for navigation.
00 — Definitions Canonical terms: Enterprise, Project, Requirement, Work (work item; same concept), Task, Milestone, Domain, System, Asset, Resource, Issue, Keyword, Standard. SUDO and scope rules.
01 — Overview Goal, scope, and high-level concepts; non-goals.
02 — Architecture Client, MCP server, PostgreSQL; handshake and scope; web app and mobile app in the architecture.
03 — Data Model Full entity set, PostgreSQL tables, relationships, change tracking (session_id, resource_id, correlation_id). Source of truth for schema.
04 — MCP Surface Context key, correlation_id, session scope; tools (scope_set/get, enterprise_, project_, requirement_, standard_, work_item_, task_, issue_, milestone_, release_, domain_, system_, asset_, resource_, keyword_, work_queue_*, association tools); resources (project://current/spec, /tasks, /plan, /requirements, /issues, enterprise://current/resources, work_item://{id}).
05 — Tech and Implementation Technology choices and implementation order; future integrations.
06 — Tech Requirements Runtime, protocol, storage, security, deployment, compatibility; methodology neutrality; configurable logging; Docker and Aspire.
07 — Deployment Docker containers, Aspire orchestration, App Host, configuration.
08 — Identifiers GUID + display slug + unique index rules; owner and hierarchy; examples for E, P, REQ, STD, WI (work/work item/task); Domain, System, Asset, Resource; Milestone, Release, Issue, Keyword prefixes.
09 — Gaps Analysis Historical snapshot of identified gaps; resolution status per category. Current gap tracking: 16.
10 — MCP Endpoint Diagrams Activity and sequence diagrams per MCP endpoint.
11 — Implementation Plan Phased implementation: Phase 0–12 (MCP server, extended entities, web app + API, mobile app). Task tables with dependencies and deliverables.
12 — Testing Plan Unit, integration, E2E, manual testing; Cursor agent CLI script test.
13 — Deployment Plan Local, Docker, Aspire, CI/CD, rollback.
14 — Project Web App Blazor (.NET 10) web app: tree, search, reports, Gantt, issues; OAuth2 (GitHub), claims, SUDO; Docker.
15 — Mobile App Avalonia UI phone app: OAuth2, task queue for assigned work items; same API and data model as web app.
16 — Gap Analysis (TODO) Remediation tracker (currently no open gaps). Use for future gaps and referencing by id.

Building and serving the documentation locally

The documentation is a Jekyll site in the docs/ directory. GitHub Pages builds it with Ruby 3.2 and publishes the _site output.

Prerequisites

  • Ruby 3.2 (or compatible; CI uses 3.2)
  • Bundler: gem install bundler if not present

Steps

  1. Go to the docs directory 
    cd docs
  2. Install dependencies 
    bundle install

    This installs Jekyll and plugins from docs/Gemfile (e.g. jekyll, jekyll-relative-links, kramdown-parser-gfm, webrick).

  3. Serve locally (with live reload) 
    bundle exec jekyll serve
    • Jekyll will build and serve at http://localhost:4000 by default.
    • The site is configured with baseurl: "/project-mcp" (see _config.yml), so the local root is http://localhost:4000/project-mcp/.
    • Use http://localhost:4000/project-mcp/ to open the index and follow links; relative links in the built pages assume this base path.
  4. Build only (no server) 
    bundle exec jekyll build

    Output is in _site. You can open _site/index.html in a browser, but for correct baseurl behavior use jekyll serve or serve _site with a server that handles the base path.

Optional: match production base URL

To avoid baseurl confusion when clicking around, run:

bundle exec jekyll serve --baseurl ""

Then the site is at http://localhost:4000/ and links use no prefix. Note: this differs from production (GitHub Pages serves at https://<user>.github.io/project-mcp/), so use the default baseurl if you want to mirror production link behavior.

CI

On push to main, the workflow Publish docs to GitHub Pages (.github/workflows/pages.yml) runs bundle exec jekyll build in docs/, uploads docs/_site, and deploys to GitHub Pages. The live site is at https://sharpninja.github.io/project-mcp/ (once Pages is enabled: Settings → Pages → Source: GitHub Actions).