@imenam/mcp-documentor 1.0.23 → 1.0.24

package/README.md

@@ -6,12 +6,13 @@ Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI
 
 ## Features
 
-- **Create & update docs** — write markdown documentation entries linked to source files
+- **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
 - **Semantic search** — find relevant docs by meaning (requires an OpenAI API key)
-- **Multi-project support** — organize docs into separate projects and switch between them
-- **GUI** — built-in web interface to browse and read documentation
+- **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
 - **Proxy-aware** — integrates with the [proxy-setup](https://github.com/Imena/proxy-setup) for GUI exposure
+- **Links & structure** — `check_links`, `get_doc_tree`, `move_doc`, and `git_diff_doc` for maintenance workflows
 
 ## Installation
 
@@ -25,6 +26,11 @@ Or install globally:
 npm install -g @imenam/mcp-documentor
 ```
 
+Global install exposes:
+
+- `mcp-documentor` — MCP server
+- `mcp-documentor-migrate` — CLI helper for migrating inline doc links (see `scripts/migrate-links.js`)
+
 ## MCP Configuration
 
 Add to your MCP client config (e.g. Cursor `mcp.json`):
@@ -47,8 +53,12 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 
 | Variable | Required | Description |
 |---|---|---|
-| `OPENAI_API_KEY` | No | Enables semantic search via OpenAI embeddings |
-| `PROXY_URL` | No | URL of the proxy server to register the GUI |
+| `OPENAI_API_KEY` | No | Enables semantic search via OpenAI embeddings (`search_docs`) |
+| `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) |
+
+Optional `.env` at the package root (directory containing `package.json` discovered from the installed binary) is loaded when present.
 
 ## Available Tools
 
@@ -57,17 +67,23 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `create_doc` | Create a new documentation entry linked to source files |
 | `get_doc` | Retrieve a documentation entry with full content |
 | `get_doc_metadata` | Get metadata and freshness status without loading content |
-| `list_docs` | List all docs in the current project with staleness indicators |
-| `update_doc` | Update an existing documentation entry |
-| `search_docs` | Search docs by keyword or semantic similarity |
-| `check_freshness` | Check if a doc is up-to-date relative to its tracked files |
-| `refresh_file_snapshot` | Mark files as up-to-date without editing the doc content |
+| `list_docs` | List docs with staleness indicators (optionally filter by project) |
+| `get_doc_tree` | Return folder/doc structure for a project (or all projects) |
+| `update_doc` | Fully replace content and/or metadata (prefer `patch_doc` for small edits) |
+| `patch_doc` | Search-and-replace a fragment of a doc’s content |
+| `move_doc` | Change a doc’s path (folder/name); use after renames to fix links |
+| `delete_doc` | Permanently delete a documentation entry |
+| `search_docs` | Semantic search over docs (natural language; requires OpenAI) |
+| `check_freshness` | Staleness for one doc or a full project scan |
+| `refresh_file_snapshot` | Mark tracked files as up-to-date without editing the doc |
+| `git_diff_doc` | Git diff for tracked files vs snapshot baseline |
+| `check_links` | Validate `related_docs`, `doc://` links, and `#heading` anchors |
 | `list_projects` | List all documentation projects |
-| `set_project` | Switch to a different project |
+| `set_project` | Switch the active project **for the GUI only** (not for MCP tools) |
 
 ## Data Storage
 
-Documentation is stored locally in a `data/` directory next to the server process. This directory is **not** included in the npm package — it is created at runtime in the working directory.
+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.
 
 ## License
 

package/dist/shared/schemas/doc.schema.d.ts

@@ -60,6 +60,7 @@ export declare const CreateDocArgsSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const UpdateDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
     content: z.ZodOptional<z.ZodString>;
     tracked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/shared/schemas/doc.schema.js

@@ -32,6 +32,7 @@ export const CreateDocArgsSchema = z.object({
 });
 export const UpdateDocArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry to update, e.g. 'backend/auth/authentication' or 'authentication' for root docs"),
+    title: z.string().optional().describe("Title of the documentation entry"),
     content: z.string().optional().describe("New content (replaces existing)"),
     tracked_files: z.array(z.string()).optional().describe("New list of file paths (replaces existing)"),
     tags: z.array(z.string()).optional().describe("New tags (replaces existing)"),

package/dist/src/index.js

@@ -437,6 +437,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     type: "object",
                     properties: {
                         path: { type: "string", description: "Path of the documentation entry to update, e.g. 'backend/auth/authentication' or 'authentication' for root docs" },
+                        title: {
+                            type: "string",
+                            description: "New display title stored in frontmatter. Does not rename the file or change the document path — use move_doc to relocate or rename on disk.",
+                        },
                         content: { type: "string", description: "New content (replaces existing). Supports [text](doc://target-doc-path) to link inline to other documents, and [text](#heading-slug) to link to headings within this document. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql." },
                         tracked_files: {
                             type: "array",

package/dist/src/tools/update-doc.js

@@ -24,6 +24,9 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             return { isError: true, content: [{ type: "text", text: `Documentation entry "${validated.path}" not found in any project.` }] };
         }
         const { doc, project: resolvedProject } = resolved;
+        if (validated.title !== undefined) {
+            doc.title = validated.title;
+        }
         if (validated.content !== undefined) {
             doc.content = validated.content;
         }
@@ -45,6 +48,8 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             }
         }
         const changes = [];
+        if (validated.title !== undefined)
+            changes.push(`title (${doc.title})`);
         if (validated.content !== undefined)
             changes.push("content");
         if (validated.tracked_files !== undefined)

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.23";
+export declare const APP_VERSION = "1.0.24";

package/dist/src/version.js

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

package/package.json

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