@imenam/mcp-documentor 1.0.58 → 1.0.59

package/README.md

@@ -8,6 +8,7 @@ Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI
 
 - **Create & update docs** — write markdown documentation entries linked to source files; prefer partial edits via `patch_doc`
 - **Staleness tracking** — automatically detects when tracked files have changed since the last doc update
+- **Portable code references** — tracked-file paths are stored relative to a configurable code root (`MCP_DOCUMENTOR_CODE_ROOT`), so synced docs resolve their source files on any machine regardless of where the repos live
 - **Semantic search** — find relevant docs by meaning (requires an OpenAI API key)
 - **Multi-project support** — organize docs into separate projects; MCP tools work across projects; `set_project` only changes what the GUI shows
 - **GUI** — built-in web interface when a proxy is configured (`PROXY_URL`); without it, the GUI worker is not started
@@ -32,6 +33,7 @@ Global install exposes:
 
 - `mcp-documentor` — MCP server
 - `mcp-documentor-migrate` — CLI helper for migrating inline doc links (see `scripts/migrate-links.js`)
+- `mcp-documentor-migrate-paths` — one-shot migration of tracked-file paths from absolute to code-root-relative (see [Portable tracked-file paths](#portable-tracked-file-paths))
 
 ## MCP Configuration
 
@@ -59,9 +61,11 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `MCP_DOCUMENTOR_OPENAI_MODEL` | No | Embedding model (default: `text-embedding-3-small`) |
 | `PROXY_URL` | No | URL of the proxy server to register and launch the GUI |
 | `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
+| `MCP_DOCUMENTOR_CODE_ROOT` | No | Base directory that tracked-file paths are stored relative to, keeping docs portable across machines (see [Portable tracked-file paths](#portable-tracked-file-paths)) |
+| `MCP_DOCUMENTOR_CODE_ROOTS` | No | JSON map of per-project code-root overrides, e.g. `{"my-proj":"/srv/my-proj"}` |
 | `READ_ONLY` | No | When set to `1`/`true`/`yes`, disables all create/update/delete tools and GUI write actions (read-only mode) |
 | `MCP_DOCUMENTOR_SYNC_REMOTE` | No | HTTPS URL of the private GitHub repo to sync with; enables GitHub sync when set |
-| `MCP_DOCUMENTOR_SYNC_BRANCH` | No | Branch to sync (default: `main`) |
+| `MCP_DOCUMENTOR_SYNC_BRANCH` | No | Branch of the documentation sync repo to push/pull docs on (default: `main`) |
 | `MCP_DOCUMENTOR_SYNC_TOKEN` | No | Fine-grained GitHub PAT used for HTTPS auth (see GitHub sync) |
 | `SYNC_PULL_ON_START` | No | Set to `false` to disable the automatic pull at server startup |
 
@@ -148,7 +152,7 @@ The sync target is **administrator-controlled**: the repository, branch and toke
       "args": ["-y", "@imenam/mcp-documentor"],
       "env": {
         "MCP_DOCUMENTOR_SYNC_REMOTE": "https://github.com/<you>/my-docs.git",
-        "MCP_DOCUMENTOR_SYNC_BRANCH": "main",            // optional, defaults to "main"
+        "MCP_DOCUMENTOR_SYNC_BRANCH": "main",            // branch of the docs sync repo, optional, defaults to "main"
         "MCP_DOCUMENTOR_SYNC_TOKEN": "github_pat_..."
       }
     }
@@ -177,6 +181,50 @@ then run `push_docs` to publish the resolution. If you have **uncommitted** loca
 
 > Read-only machines (`READ_ONLY=1`) can still `pull_docs` and `sync_status`, but `push_docs`, `sync_docs`, and `resolve_sync_conflict` are disabled.
 
+## Portable tracked-file paths
+
+When docs are synced across machines, absolute tracked-file paths break: the codebase rarely lives at the same absolute location everywhere. To stay portable, tracked-file paths are stored **relative to a configurable code root** and resolved back to absolute paths on demand.
+
+Agents keep passing **absolute** paths to `create_doc` / `update_doc` (and in `[copy-from-codebase|…]` tags) as usual — the conversion to a stored relative path happens automatically server-side. No change in how the agent works.
+
+### Configuration
+
+Set the code root per machine (it is machine-local, so it lives in the environment, never in the synced data):
+
+```jsonc
+{
+  "env": {
+    "MCP_DOCUMENTOR_CODE_ROOT": "/home/you/code/repos",
+    // optional per-project overrides when repos don't share a common parent:
+    "MCP_DOCUMENTOR_CODE_ROOTS": "{\"my-proj\":\"/srv/my-proj\"}"
+  }
+}
+```
+
+Resolution precedence: `MCP_DOCUMENTOR_CODE_ROOTS[project]` → `MCP_DOCUMENTOR_CODE_ROOT` → none.
+
+| Stored path | On read |
+|---|---|
+| Relative + code root configured | resolved against the root |
+| Relative + **no** root on this machine | reported as `unverifiable` (source absent) instead of a false `stale` |
+| Absolute (legacy, or file outside the root) | used as-is |
+
+The feature is **opt-in**: with no code root configured, behaviour is unchanged (paths stored and resolved as absolute).
+
+### Migrating existing docs
+
+Docs created before this feature store absolute paths. Convert them in one shot with the bundled `mcp-documentor-migrate-paths`:
+
+```bash
+MCP_DOCUMENTOR_CODE_ROOT="/home/you/code/repos" \
+MCP_DATA_DIR="/path/to/your/data" \
+  npx -p @imenam/mcp-documentor mcp-documentor-migrate-paths --dry-run
+```
+
+Review the report (`converted` / `kept absolute (outside root)` / `projects skipped`), then re-run without `--dry-run`. Finally publish with `sync_docs` (never commit the data dir by hand). The data dir is resolved like the server: `--data-dir` flag → `MCP_DATA_DIR` → package-relative fallback.
+
+This is a **one-time** operation, and must run on the machine whose OS/filesystem **created** the stored absolute paths (path semantics differ between Windows and POSIX). Once migrated and synced, every other machine just `pull_docs` and sets its own `MCP_DOCUMENTOR_CODE_ROOT` — no migration needed.
+
 ## Data Storage
 
 By default, data lives under **`.docs-data`** next to the resolved package root (the folder that contains `package.json` for the running install). Set **`MCP_DATA_DIR`** to use another directory. Contents include projects, SQLite/embeddings, and logs under `.docs-data/logs`. This tree is **not** part of the npm package; it is created at runtime.

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.58";
+export declare const APP_VERSION = "1.0.59";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.58';
+export const APP_VERSION = '1.0.59';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.58",
+  "version": "1.0.59",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",