mooteam-mcp 0.2.0 → 0.3.0

package/docs/configuration.md

@@ -25,7 +25,11 @@ Never publish session tokens or credential-bearing download links.
 | `MOOTEAM_COMPANY_ALIAS` | Config `company` | Exact `X-MT-Company` header value |
 | `MOOTEAM_FILE_TOKEN` | Config `fileToken` | Optional fallback download token |
 | `MOOTEAM_ROLES_FILE` | `roles.json` beside the selected config file | Optional local participant roles |
-| `MOOTEAM_TIMEOUT_MS` | `30000` | Per-request and PDF extraction timeout, 1000–120000 |
+| `MOOTEAM_HISTORY` | Enabled | Set `off` to disable local history reads/writes |
+| `MOOTEAM_HISTORY_MAX_BYTES` | `1048576` | Compressed history budget per workspace, 16384–10485760 |
+| `MOOTEAM_HISTORY_MAX_TASKS` | `200` | Maximum retained task baselines, 1–2000 |
+| `MOOTEAM_HISTORY_DAYS` | `90` | Expire tasks after this many days without an observation, 1–365 |
+| `MOOTEAM_TIMEOUT_MS` | `30000` | Per-request and document worker timeout, 1000–120000 |
 | `MOOTEAM_MAX_PAGES` | `100` | Maximum pages in each API collection, 1–1000 |
 | `MOOTEAM_MAX_ATTACHMENT_BYTES` | `10485760` | Download limit, 1024–52428800 bytes |
 | `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error`, `silent` |
@@ -60,14 +64,51 @@ Missing files mean no configured roles. Invalid files or a mismatched company
 produce a warning and omit roles while preserving task reads. The file limit is
 1 MiB; role labels must contain 1–256 characters.
 
-You can tell a local coding assistant who does what and ask it to update this
-file. It should resolve names to user IDs, use only roles you explicitly supply,
+Tell the assistant who does what: it can use `list_participants`, then
+`set_participant_role` with the exact user ID, expected full name and
+`userConfirmed: true`. It must use only roles you explicitly supply,
 preserve other entries and the company value, and never publish the directory.
 If a name is ambiguous, clarify the person before assigning a role. Use a project
-override only when you specify that scope. No Moo.team write or MCP write tool is
-needed. Role labels provide context; they do not grant permissions or constitute
+override only when you specify that scope. `role: null` removes the selected
+scope. The tool writes only this local file and preserves other entries with an
+atomic replacement and cross-process lock. Role labels provide context; they do not grant permissions or constitute
 instructions to perform actions.
 
+## Compact local history
+
+`get_task_context` tracks changes by default; set `trackChanges: false` to leave
+the baseline unchanged. `get_task_changes` compares and advances the same baseline.
+The first complete read establishes a baseline. Attachment reads, search and related
+task reads never advance it. Missing/incomplete comments preserve the previous
+baseline. A late response cannot overwrite an observation that started later.
+
+One `history-<workspace-hash>.json.gz` sits beside the selected config file.
+It contains semantic hashes of task fields, comments and file metadata, source IDs,
+status IDs/values, observation timestamps and short change events. It contains no
+task titles, descriptions, discussion text, participant names or attachment bytes.
+It is a change detector, not a backup: old text cannot be reconstructed, and edits
+made and reverted between reads cannot be detected. A missing comment/file means
+"no longer visible", not confirmed deletion. Changing local roles does not create
+an edit to the source discussion.
+
+The defaults are 1 MiB compressed, 200 tasks, 90 days since last observation and
+20 events per task. At most five recent events are returned. Expiry and oldest-task
+eviction run during tracked reads; an evicted task starts a new baseline next time.
+Each returned ID list is capped at 100 and includes full counts/truncation flags.
+Uncompressed state is also bounded to 16 MiB. An individual baseline that cannot
+fit is skipped with a warning, preserving the existing file.
+
+An atomic save temporarily needs up to one additional file of the configured
+size plus a small lock file. Normal completion removes temporary files. A crash
+can leave a lock/temp file: stop all MCP processes before removing those leftovers.
+Corrupt, oversized, busy or inaccessible state produces a warning and is preserved;
+task reads still work. To reset a corrupt baseline, stop MCP and remove its history
+file. Setting `MOOTEAM_HISTORY=off` does not remove an existing history file.
+
+Keep the configuration directory private to your OS account, including its
+inherited permissions on Windows: atomic replacements inherit directory ACLs.
+History is gzip-compressed, not encrypted.
+
 ## Stdio clients
 
 ```json
@@ -115,8 +156,11 @@ in the host's environment to keep credentials in another location.
   pagination metadata was missing, or the configured page cap was reached.
 
 Operational logs go to stderr and omit credentials, full URLs and task content.
-No task database or attachment cache is written to disk. PDF text extraction uses
-a worker with a timeout and bounded V8 heap; this is not a general-purpose sandbox.
+Only compact history and local roles are maintained on disk. Attachments are fetched
+into RAM, processed and released; neither originals nor extracted/rendered content
+are written as files. PDF/Office/ZIP processing uses workers with timeouts and a
+256 MiB V8 heap cap, plus explicit byte limits. Native allocations are outside the
+V8 heap cap; this is not a general-purpose sandbox.
 
 ## See also
 

package/docs/development.md

@@ -11,7 +11,8 @@ npm pack --dry-run
 
 Tests use synthetic data and an injected fetch implementation. No credentials or
 network access are needed for the test suite. The protocol test starts a separate
-stdio server and verifies tool discovery, task reads and image blocks.
+stdio server and verifies tool discovery, task reads, history, local roles, search
+and image blocks. Synthetic Office/ZIP/PDF fixtures are constructed in memory.
 
 For a live read-only check, configure local credentials and run `mooteam-mcp --check`.
 Set `MOOTEAM_SMOKE_TASK` and optionally `MOOTEAM_SMOKE_FILE`, then run `npm run smoke`.
@@ -32,22 +33,67 @@ MCP stdio → tool handlers → task context / attachment services → GET-only
 | `src/api-client.ts` | Fixed API origin, auth, bounded GETs and pagination |
 | `src/task-context.ts` | Task/comment assembly, authors and file ownership |
 | `src/roles.ts` | Bounded local role directory, workspace scope and project overrides |
+| `src/local-state.ts` | Bounded reads, cross-process locks and atomic local state replacement |
+| `src/history.ts` | Compressed semantic fingerprints, changes and retention/size eviction |
+| `src/search.ts` | Project/participant discovery and bounded task collection search |
+| `src/related.ts` | Parent/subtask/link traversal with provenance and attempt/depth limits |
 | `src/rich-text.ts` | Rich-text conversion with explicit limitations |
 | `src/attachments.ts` | File validation, format dispatch and output bounds |
-| `src/pdf-worker.ts` | Isolated PDF text extraction |
+| `src/pdf-worker.ts` | Isolated PDF text extraction and selected-page rendering |
+| `src/documents.ts`, `src/document-worker.ts` | Isolated bounded ZIP/OOXML text extraction |
 
-Runtime dependencies are the official MCP server SDK v2, Zod and PDF.js.
+Runtime dependencies are the official MCP server SDK v2, Zod, PDF.js,
+`@napi-rs/canvas` for PDF rendering, `yauzl` for bounded ZIP streams and `saxes`
+for XML parsing without DTDs/external entities.
 MCP SDK's stdio compatibility support handles older protocol clients.
 There is no LLM API dependency and no hosted proxy.
 
+Only explicit task tool reads update history. The full normalized comment set is
+associated with a context object in a WeakMap, so returned pagination and internal
+attachment ownership checks cannot corrupt or consume baselines. History stores
+hashes and IDs, never rich bodies. Local role updates require user-supplied roles
+and exact API name/ID resolution. Moo.team requests remain GET-only; MCP tools
+that modify local files are annotated as local writes.
+
+Document parsers receive byte arrays and return text/images over worker messages.
+They never extract archives onto the filesystem. Limits include 1000 archive
+entries, 8 MiB per inflated member, 24 MiB total inflation, 100000 XML elements,
+128 nesting levels, 10000 spreadsheet cells and requested character/page limits.
+PDF images are capped at 4 million pixels per page and 5 MiB total PNG bytes.
+Parser stdout/stderr is consumed privately so document content cannot enter MCP
+protocol output or application logs. Every extraction reports its limitations.
+
 ## Release
 
-1. Run tests and type checking.
-2. Run `npm pack --dry-run` and inspect the package allowlist.
-3. Check staged source contains no tokens, private task data or local configuration.
-4. Commit and push reviewed source.
-5. Publish with `npm publish --access public` using your own npm account.
-6. Verify the published version and install it in a clean directory.
+Releases run automatically from `.github/workflows/release.yml` after a push to
+`main`. Pull requests and other branches only run checks. To prepare a release:
+
+```sh
+npm run release:version -- patch
+```
+
+Use `minor` or `major` when appropriate. This updates package.json and the lockfile;
+the CLI and MCP protocol read that same version. Commit the reviewed changes and
+push to main. Never include local credentials, participant directories or real
+task fixtures in the commit.
+
+The workflow runs the Windows/Linux and Node 22/24 checks first. If the version is
+newer than npm's latest release, it builds, checks the package file allowlist,
+publishes to npm, verifies the registry commit, then creates a `vVERSION` tag and
+GitHub Release with generated notes. Unchanged published versions are skipped.
+Only stable versions are supported by this workflow.
+
+Publishing uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
+with OIDC: package `mooteam-mcp`, repository `Mostok/mooteam-mcp`, workflow filename
+`release.yml`, and direct `npm publish` permission. No npm token or Moo.team
+credentials are stored in Actions. Only the publish job can request an OIDC token;
+only the GitHub Release job can write repository metadata.
+
+If a run fails, use **Re-run failed jobs** on that run. A version already published
+from the same commit is not republished; verification and GitHub Release creation
+can resume. Do not move an existing release tag. A new commit without a new version
+does not repair an older release; retry the original run instead. `workflow_dispatch`
+is available on main and runs the same checks and release guards.
 
 Only `dist`, `docs`, README, package metadata and LICENSE ship in the npm package.
 Internal plans, editor settings, tests, local credentials and development helpers

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mooteam-mcp",
-  "version": "0.2.0",
-  "description": "Read-only Moo.team MCP server: task context, attributed comments and attachments through the API.",
+  "version": "0.3.0",
+  "description": "Moo.team MCP: GET-only task context, search, compact local history, participant roles and in-memory attachments.",
   "type": "module",
   "bin": {
     "mooteam-mcp": "dist/cli.js"
@@ -20,7 +20,8 @@
     "test": "npm run build && node --test test/*.test.mjs",
     "check": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build",
-    "smoke": "node scripts/smoke.mjs"
+    "smoke": "node scripts/smoke.mjs",
+    "release:version": "npm version --no-git-tag-version"
   },
   "keywords": [
     "mcp",
@@ -40,12 +41,16 @@
   "homepage": "https://github.com/Mostok/mooteam-mcp#readme",
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
+    "@napi-rs/canvas": "^1.0.9",
     "pdfjs-dist": "^6.3.289",
+    "saxes": "^6.0.0",
+    "yauzl": "^3.4.0",
     "zod": "^4.5.4"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",
     "@types/node": "^22.0.0",
+    "@types/yauzl": "^3.4.0",
     "typescript": "^5.9.3"
   }
 }