@imenam/mcp-documentor 1.0.48 → 1.0.51

package/README.md

@@ -13,6 +13,7 @@ Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI
 - **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
+- **Image support** — upload images to a project's assets via `upload_image` (local file path) or directly from the GUI editor; images are stored per-project and rendered inline in the viewer and in PDF exports
 
 ## Installation
 
@@ -80,6 +81,33 @@ Optional `.env` at the package root (directory containing `package.json` discove
 | `check_links` | Validate `related_docs`, `doc://` links, and `#heading` anchors |
 | `list_projects` | List all documentation projects |
 | `set_project` | Switch the active project **for the GUI only** (not for MCP tools) |
+| `upload_image` | Upload an image from a local file path to a project's assets; returns the markdown link to insert |
+
+## Images in documents
+
+Images can be embedded in any documentation entry using standard markdown syntax:
+
+```markdown
+![alt text](/api/images/my-project/screenshot.png)   <!-- local upload -->
+![alt text](https://example.com/diagram.png)          <!-- external URL -->
+```
+
+**Via the MCP tool** — use `upload_image` with the absolute path of the file on the server:
+
+```json
+{
+  "filename": "screenshot.png",
+  "filePath": "/absolute/path/to/screenshot.png",
+  "alt": "Architecture diagram"
+}
+```
+
+The tool copies the file into `.docs-data/projects/{project}/assets/` and returns the ready-to-use markdown snippet.
+
+**Via the GUI editor** — click the **🖼 Image** button in the editor toolbar to open the image panel:
+- **Upload tab** — pick a local file; it is uploaded automatically and the markdown link is inserted at the cursor position
+- **URL tab** — paste any external image URL; the markdown link is inserted at the cursor position
+- **Project images gallery** — click any previously uploaded image to re-insert it
 
 ## Data Storage
 

package/dist/src/gui-worker.js

@@ -543,6 +543,70 @@ app.get("/api/pdf", async (c) => {
             await browser.close();
     }
 });
+// --- Images ---
+const IMAGE_MIME = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+};
+function sanitizeImageFilename(name) {
+    return name.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function resolveImageFilename(assetsDir, baseName) {
+    const safe = sanitizeImageFilename(baseName);
+    if (!fs.existsSync(path.join(assetsDir, safe)))
+        return safe;
+    const ext = path.extname(safe);
+    const base = path.basename(safe, ext);
+    let i = 1;
+    while (fs.existsSync(path.join(assetsDir, `${base}-${i}${ext}`)))
+        i++;
+    return `${base}-${i}${ext}`;
+}
+app.post("/api/images", async (c) => {
+    const project = c.req.query("project");
+    if (!project)
+        return c.json({ error: "project is required" }, 400);
+    let body;
+    try {
+        body = await c.req.parseBody();
+    }
+    catch {
+        return c.json({ error: "Failed to parse multipart body" }, 400);
+    }
+    const file = body["file"];
+    if (!file || typeof file === "string")
+        return c.json({ error: "file field is required" }, 400);
+    const assetsDir = path.join(dataDir, "projects", project, "assets");
+    fs.mkdirSync(assetsDir, { recursive: true });
+    const finalName = resolveImageFilename(assetsDir, file.name ?? "image");
+    const buffer = Buffer.from(await file.arrayBuffer());
+    fs.writeFileSync(path.join(assetsDir, finalName), buffer);
+    return c.json({ url: `/api/images/${project}/${finalName}`, filename: finalName });
+});
+app.get("/api/images/:project", (c) => {
+    const project = c.req.param("project");
+    const assetsDir = path.join(dataDir, "projects", project, "assets");
+    if (!fs.existsSync(assetsDir))
+        return c.json([]);
+    const files = fs.readdirSync(assetsDir).filter((f) => /\.(png|jpe?g|gif|webp|svg)$/i.test(f));
+    return c.json(files.map((f) => ({ filename: f, url: `/api/images/${project}/${f}` })));
+});
+app.get("/api/images/:project/:filename", (c) => {
+    const project = c.req.param("project");
+    const filename = c.req.param("filename");
+    const filePath = path.join(dataDir, "projects", project, "assets", filename);
+    if (!fs.existsSync(filePath))
+        return c.notFound();
+    const ext = path.extname(filename).toLowerCase().slice(1);
+    const mime = IMAGE_MIME[ext] ?? "application/octet-stream";
+    return new Response(fs.readFileSync(filePath), {
+        headers: { "Content-Type": mime },
+    });
+});
 // Static files
 app.use("/assets/*", serveStatic({ root: path.relative(process.cwd(), absoluteStaticRoot) }));
 function getHtmlBaseHref(appPath) {

package/dist/src/index.js

@@ -37,6 +37,7 @@ import { restoreDocVersion } from "./tools/restore-doc-version.js";
 import { reindexEmbeddings } from "./tools/reindex-embeddings.js";
 import { prepareExportBundle } from "./tools/prepare-export-bundle.js";
 import { deleteExportBundle } from "./tools/delete-export-bundle.js";
+import { uploadImage } from "./tools/upload-image.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 function findProjectRoot(startDir) {
@@ -972,6 +973,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["id"],
                 },
             },
+            {
+                name: "upload_image",
+                description: "Upload an image to a project's assets from a local file path and get back the markdown link to insert in a document. Returns the URL and a ready-to-use markdown snippet: ![alt](/api/images/{project}/{filename}).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        filename: { type: "string", description: "Filename with extension, e.g. 'screenshot.png'" },
+                        filePath: { type: "string", description: "Absolute path to the image file on the server" },
+                        project: { type: "string", description: "Target project (defaults to current project)" },
+                        alt: { type: "string", description: "Alt text for the markdown image link (optional)" },
+                    },
+                    required: ["filename", "filePath"],
+                },
+            },
         ],
     };
 });
@@ -1041,6 +1056,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 return result;
             }
+            case "upload_image":
+                return await uploadImage(storageEngine, args);
             default:
                 throw new Error(`Tool not found: ${name}`);
         }

package/dist/src/tools/upload-image.d.ts

@@ -0,0 +1,14 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+export declare function uploadImage(storageEngine: StorageEngine, args: unknown): Promise<{
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/src/tools/upload-image.js

@@ -0,0 +1,55 @@
+import fs from "fs";
+import path from "path";
+import { z } from "zod";
+const UploadImageArgsSchema = z.object({
+    filename: z.string().min(1),
+    filePath: z.string(),
+    project: z.string().optional(),
+    alt: z.string().optional(),
+});
+function sanitizeFilename(name) {
+    return name.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function resolveFilename(assetsDir, baseName) {
+    const safe = sanitizeFilename(baseName);
+    if (!fs.existsSync(path.join(assetsDir, safe)))
+        return safe;
+    const ext = path.extname(safe);
+    const base = path.basename(safe, ext);
+    let i = 1;
+    while (fs.existsSync(path.join(assetsDir, `${base}-${i}${ext}`)))
+        i++;
+    return `${base}-${i}${ext}`;
+}
+export async function uploadImage(storageEngine, args) {
+    try {
+        const validated = UploadImageArgsSchema.parse(args);
+        const config = storageEngine.getConfig();
+        const project = validated.project ?? config.currentProject;
+        if (!fs.existsSync(validated.filePath)) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `File not found: ${validated.filePath}` }],
+            };
+        }
+        const assetsDir = path.join(storageEngine.getDataDir(), "projects", project, "assets");
+        fs.mkdirSync(assetsDir, { recursive: true });
+        const finalName = resolveFilename(assetsDir, validated.filename);
+        fs.copyFileSync(validated.filePath, path.join(assetsDir, finalName));
+        const url = `/api/images/${project}/${finalName}`;
+        const alt = validated.alt ?? "";
+        const markdownLink = `![${alt}](${url})`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Image uploaded successfully.\nFilename: ${finalName}\nURL: ${url}\nMarkdown: ${markdownLink}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error uploading image: ${message}` }] };
+    }
+}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.48";
+export declare const APP_VERSION = "1.0.51";

package/dist/src/version.js

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

package/gui/dist/assets/{arc-CTYsyt8O.js → arc-CCHCB-wD.js}

@@ -1 +1 @@
-import{a0 as ln,a1 as an,a2 as y,a3 as tn,a4 as H,a5 as q,a6 as _,a7 as un,a8 as rn,a9 as L,aa as o,ab as B,ac as sn,ad as on,ae as fn}from"./index-BMSuP895.js";function cn(l){return l.innerRadius}function yn(l){return l.outerRadius}function gn(l){return l.startAngle}function dn(l){return l.endAngle}function mn(l){return l&&l.padAngle}function pn(l,h,I,D,v,A,C,a){var O=I-l,i=D-h,n=C-v,d=a-A,u=d*O-n*i;if(!(u*u<y))return u=(n*(h-A)-d*(l-v))/u,[l+u*O,h+u*i]}function W(l,h,I,D,v,A,C){var a=l-I,O=h-D,i=(C?A:-A)/L(a*a+O*O),n=i*O,d=-i*a,u=l+n,s=h+d,f=I+n,c=D+d,F=(u+f)/2,t=(s+c)/2,m=f-u,g=c-s,R=m*m+g*g,T=v-A,P=u*c-f*s,S=(g<0?-1:1)*L(fn(0,T*T*R-P*P)),j=(P*g-m*S)/R,z=(-P*m-g*S)/R,w=(P*g+m*S)/R,p=(-P*m+g*S)/R,x=j-F,e=z-t,r=w-F,G=p-t;return x*x+e*e>r*r+G*G&&(j=w,z=p),{cx:j,cy:z,x01:-n,y01:-d,x11:j*(v/T-1),y11:z*(v/T-1)}}function hn(){var l=cn,h=yn,I=B(0),D=null,v=gn,A=dn,C=mn,a=null,O=ln(i);function i(){var n,d,u=+l.apply(this,arguments),s=+h.apply(this,arguments),f=v.apply(this,arguments)-an,c=A.apply(this,arguments)-an,F=un(c-f),t=c>f;if(a||(a=n=O()),s<u&&(d=s,s=u,u=d),!(s>y))a.moveTo(0,0);else if(F>tn-y)a.moveTo(s*H(f),s*q(f)),a.arc(0,0,s,f,c,!t),u>y&&(a.moveTo(u*H(c),u*q(c)),a.arc(0,0,u,c,f,t));else{var m=f,g=c,R=f,T=c,P=F,S=F,j=C.apply(this,arguments)/2,z=j>y&&(D?+D.apply(this,arguments):L(u*u+s*s)),w=_(un(s-u)/2,+I.apply(this,arguments)),p=w,x=w,e,r;if(z>y){var G=sn(z/u*q(j)),M=sn(z/s*q(j));(P-=G*2)>y?(G*=t?1:-1,R+=G,T-=G):(P=0,R=T=(f+c)/2),(S-=M*2)>y?(M*=t?1:-1,m+=M,g-=M):(S=0,m=g=(f+c)/2)}var J=s*H(m),K=s*q(m),N=u*H(T),Q=u*q(T);if(w>y){var U=s*H(g),V=s*q(g),X=u*H(R),Y=u*q(R),E;if(F<rn)if(E=pn(J,K,X,Y,U,V,N,Q)){var Z=J-E[0],$=K-E[1],b=U-E[0],k=V-E[1],nn=1/q(on((Z*b+$*k)/(L(Z*Z+$*$)*L(b*b+k*k)))/2),en=L(E[0]*E[0]+E[1]*E[1]);p=_(w,(u-en)/(nn-1)),x=_(w,(s-en)/(nn+1))}else p=x=0}S>y?x>y?(e=W(X,Y,J,K,s,x,t),r=W(U,V,N,Q,s,x,t),a.moveTo(e.cx+e.x01,e.cy+e.y01),x<w?a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,s,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),!t),a.arc(r.cx,r.cy,x,o(r.y11,r.x11),o(r.y01,r.x01),!t))):(a.moveTo(J,K),a.arc(0,0,s,m,g,!t)):a.moveTo(J,K),!(u>y)||!(P>y)?a.lineTo(N,Q):p>y?(e=W(N,Q,U,V,u,-p,t),r=W(J,K,X,Y,u,-p,t),a.lineTo(e.cx+e.x01,e.cy+e.y01),p<w?a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,u,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),t),a.arc(r.cx,r.cy,p,o(r.y11,r.x11),o(r.y01,r.x01),!t))):a.arc(0,0,u,T,R,t)}if(a.closePath(),n)return a=null,n+""||null}return i.centroid=function(){var n=(+l.apply(this,arguments)+ +h.apply(this,arguments))/2,d=(+v.apply(this,arguments)+ +A.apply(this,arguments))/2-rn/2;return[H(d)*n,q(d)*n]},i.innerRadius=function(n){return arguments.length?(l=typeof n=="function"?n:B(+n),i):l},i.outerRadius=function(n){return arguments.length?(h=typeof n=="function"?n:B(+n),i):h},i.cornerRadius=function(n){return arguments.length?(I=typeof n=="function"?n:B(+n),i):I},i.padRadius=function(n){return arguments.length?(D=n==null?null:typeof n=="function"?n:B(+n),i):D},i.startAngle=function(n){return arguments.length?(v=typeof n=="function"?n:B(+n),i):v},i.endAngle=function(n){return arguments.length?(A=typeof n=="function"?n:B(+n),i):A},i.padAngle=function(n){return arguments.length?(C=typeof n=="function"?n:B(+n),i):C},i.context=function(n){return arguments.length?(a=n??null,i):a},i}export{hn as d};
+import{a0 as ln,a1 as an,a2 as y,a3 as tn,a4 as H,a5 as q,a6 as _,a7 as un,a8 as rn,a9 as L,aa as o,ab as B,ac as sn,ad as on,ae as fn}from"./index-BwW5YDD1.js";function cn(l){return l.innerRadius}function yn(l){return l.outerRadius}function gn(l){return l.startAngle}function dn(l){return l.endAngle}function mn(l){return l&&l.padAngle}function pn(l,h,I,D,v,A,C,a){var O=I-l,i=D-h,n=C-v,d=a-A,u=d*O-n*i;if(!(u*u<y))return u=(n*(h-A)-d*(l-v))/u,[l+u*O,h+u*i]}function W(l,h,I,D,v,A,C){var a=l-I,O=h-D,i=(C?A:-A)/L(a*a+O*O),n=i*O,d=-i*a,u=l+n,s=h+d,f=I+n,c=D+d,F=(u+f)/2,t=(s+c)/2,m=f-u,g=c-s,R=m*m+g*g,T=v-A,P=u*c-f*s,S=(g<0?-1:1)*L(fn(0,T*T*R-P*P)),j=(P*g-m*S)/R,z=(-P*m-g*S)/R,w=(P*g+m*S)/R,p=(-P*m+g*S)/R,x=j-F,e=z-t,r=w-F,G=p-t;return x*x+e*e>r*r+G*G&&(j=w,z=p),{cx:j,cy:z,x01:-n,y01:-d,x11:j*(v/T-1),y11:z*(v/T-1)}}function hn(){var l=cn,h=yn,I=B(0),D=null,v=gn,A=dn,C=mn,a=null,O=ln(i);function i(){var n,d,u=+l.apply(this,arguments),s=+h.apply(this,arguments),f=v.apply(this,arguments)-an,c=A.apply(this,arguments)-an,F=un(c-f),t=c>f;if(a||(a=n=O()),s<u&&(d=s,s=u,u=d),!(s>y))a.moveTo(0,0);else if(F>tn-y)a.moveTo(s*H(f),s*q(f)),a.arc(0,0,s,f,c,!t),u>y&&(a.moveTo(u*H(c),u*q(c)),a.arc(0,0,u,c,f,t));else{var m=f,g=c,R=f,T=c,P=F,S=F,j=C.apply(this,arguments)/2,z=j>y&&(D?+D.apply(this,arguments):L(u*u+s*s)),w=_(un(s-u)/2,+I.apply(this,arguments)),p=w,x=w,e,r;if(z>y){var G=sn(z/u*q(j)),M=sn(z/s*q(j));(P-=G*2)>y?(G*=t?1:-1,R+=G,T-=G):(P=0,R=T=(f+c)/2),(S-=M*2)>y?(M*=t?1:-1,m+=M,g-=M):(S=0,m=g=(f+c)/2)}var J=s*H(m),K=s*q(m),N=u*H(T),Q=u*q(T);if(w>y){var U=s*H(g),V=s*q(g),X=u*H(R),Y=u*q(R),E;if(F<rn)if(E=pn(J,K,X,Y,U,V,N,Q)){var Z=J-E[0],$=K-E[1],b=U-E[0],k=V-E[1],nn=1/q(on((Z*b+$*k)/(L(Z*Z+$*$)*L(b*b+k*k)))/2),en=L(E[0]*E[0]+E[1]*E[1]);p=_(w,(u-en)/(nn-1)),x=_(w,(s-en)/(nn+1))}else p=x=0}S>y?x>y?(e=W(X,Y,J,K,s,x,t),r=W(U,V,N,Q,s,x,t),a.moveTo(e.cx+e.x01,e.cy+e.y01),x<w?a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,x,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,s,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),!t),a.arc(r.cx,r.cy,x,o(r.y11,r.x11),o(r.y01,r.x01),!t))):(a.moveTo(J,K),a.arc(0,0,s,m,g,!t)):a.moveTo(J,K),!(u>y)||!(P>y)?a.lineTo(N,Q):p>y?(e=W(N,Q,U,V,u,-p,t),r=W(J,K,X,Y,u,-p,t),a.lineTo(e.cx+e.x01,e.cy+e.y01),p<w?a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(r.y01,r.x01),!t):(a.arc(e.cx,e.cy,p,o(e.y01,e.x01),o(e.y11,e.x11),!t),a.arc(0,0,u,o(e.cy+e.y11,e.cx+e.x11),o(r.cy+r.y11,r.cx+r.x11),t),a.arc(r.cx,r.cy,p,o(r.y11,r.x11),o(r.y01,r.x01),!t))):a.arc(0,0,u,T,R,t)}if(a.closePath(),n)return a=null,n+""||null}return i.centroid=function(){var n=(+l.apply(this,arguments)+ +h.apply(this,arguments))/2,d=(+v.apply(this,arguments)+ +A.apply(this,arguments))/2-rn/2;return[H(d)*n,q(d)*n]},i.innerRadius=function(n){return arguments.length?(l=typeof n=="function"?n:B(+n),i):l},i.outerRadius=function(n){return arguments.length?(h=typeof n=="function"?n:B(+n),i):h},i.cornerRadius=function(n){return arguments.length?(I=typeof n=="function"?n:B(+n),i):I},i.padRadius=function(n){return arguments.length?(D=n==null?null:typeof n=="function"?n:B(+n),i):D},i.startAngle=function(n){return arguments.length?(v=typeof n=="function"?n:B(+n),i):v},i.endAngle=function(n){return arguments.length?(A=typeof n=="function"?n:B(+n),i):A},i.padAngle=function(n){return arguments.length?(C=typeof n=="function"?n:B(+n),i):C},i.context=function(n){return arguments.length?(a=n??null,i):a},i}export{hn as d};