file-share-mcp 1.0.1

package/README.md

@@ -0,0 +1,154 @@
+# File Share MCP
+
+An MCP server for bidirectional file sharing between AI agents and users, with a built-in web GUI.
+
+The agent can list, read, and notify about files. The user can upload, download, and delete files via the GUI — all through a shared local folder.
+
+## Features
+
+- **MCP Tools** for the AI agent:
+  - `get_shared_folder` — Get the current shared folder path
+  - `list_shared_files` — List all files available in the shared folder
+  - `share_file` — Notify the user that a file is ready to download
+  - `preview_file` — Read the content of a `.txt` or `.md` file (max 1 MB)
+- **Web GUI** — Upload, download, preview, and delete files from a browser
+- **Zero config** — works out of the box with sensible defaults (`~/.file-share-mcp`)
+- **Proxy-ready** — optional integration with the [file-share-mcp proxy](https://github.com/...)
+
+---
+
+## Quick Start with Cursor
+
+Add this to your Cursor MCP configuration (`~/.cursor/mcp.json` or your workspace `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "file-share": {
+      "command": "npx",
+      "args": ["-y", "file-share-mcp"]
+    }
+  }
+}
+```
+
+Once added, restart Cursor. The GUI will be available at **http://localhost:3005**.
+
+---
+
+## Quick Start with Claude Desktop
+
+Add this to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "file-share": {
+      "command": "npx",
+      "args": ["-y", "file-share-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Configuration (optional)
+
+All configuration is done via environment variables, passed in the MCP `env` block or in a `.env` file inside the package directory.
+
+| Variable | Default | Description |
+|---|---|---|
+| `GUI_PORT` | `3005` | Port for the web GUI |
+| `MCP_DATA_DIR` | `~/.file-share-mcp` | Directory for `configs.json` and persistent data |
+| `PROXY_URL` | _(none)_ | URL of the proxy server (optional) |
+| `PROXY_APP_PATH` | `/file-share` | Path to register on the proxy |
+| `PROXY_APP_NAME` | `File Share MCP` | Display name shown in the proxy dashboard |
+
+### Example: custom port and data directory
+
+```json
+{
+  "mcpServers": {
+    "file-share": {
+      "command": "npx",
+      "args": ["-y", "file-share-mcp"],
+      "env": {
+        "GUI_PORT": "3010",
+        "MCP_DATA_DIR": "C:/Users/YourName/my-shared-files"
+      }
+    }
+  }
+}
+```
+
+### Example: with proxy integration
+
+```json
+{
+  "mcpServers": {
+    "file-share": {
+      "command": "npx",
+      "args": ["-y", "file-share-mcp"],
+      "env": {
+        "PROXY_URL": "http://localhost:3000",
+        "PROXY_APP_PATH": "/file-share",
+        "PROXY_APP_NAME": "File Share MCP"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Data & Logs
+
+By default, all user data is stored in `~/.file-share-mcp/`:
+
+```
+~/.file-share-mcp/
+├── configs.json       # Saved configuration (shared folder path, etc.)
+├── shared/            # Default shared folder
+└── logs/
+    └── server.log     # Application logs
+```
+
+This directory survives package updates and reinstalls.
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+cd gui && npm install && cd ..
+
+# Build (backend + frontend)
+npm run build
+
+# Start
+npm start
+```
+
+### Project structure
+
+```
+src/
+├── mcp-server.ts       # MCP server (MASTER process)
+├── gui.ts              # Express GUI server (WORKER process)
+└── utils/
+    ├── config-manager.ts
+    ├── file-manager.ts
+    ├── logger.ts
+    └── generate-version.ts
+gui/                    # React + Vite frontend (builds to ../public/)
+public/                 # Built frontend (served by the GUI server)
+```
+
+---
+
+## License
+
+ISC

package/dist/gui.js

@@ -0,0 +1,235 @@
+import express from 'express';
+import multer from 'multer';
+import cors from 'cors';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+import axios from 'axios';
+import { setupLogging } from './utils/logger.js';
+import { getConfig, saveConfig } from './utils/config-manager.js';
+import { getSharedFiles, validateSafePath, deleteFile } from './utils/file-manager.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+setupLogging('GUI');
+const app = express();
+app.use(cors());
+app.use(express.json());
+// Protect stdout - setupLogging already redirects console.log/error
+// but we want to be sure no other library writes to stdout.
+// Multer configuration for file uploads
+const storage = multer.diskStorage({
+    destination: (req, file, cb) => {
+        const config = getConfig();
+        if (!fs.existsSync(config.shared_folder_path)) {
+            fs.mkdirSync(config.shared_folder_path, { recursive: true });
+        }
+        cb(null, config.shared_folder_path);
+    },
+    filename: (req, file, cb) => {
+        cb(null, file.originalname);
+    }
+});
+const upload = multer({ storage });
+// Endpoints
+app.get('/proxy/health', (req, res) => {
+    res.json({ status: 'healthy' });
+});
+app.get('/api/files', (req, res) => {
+    try {
+        const files = getSharedFiles();
+        res.json(files);
+    }
+    catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+app.get('/api/download/:filename', (req, res) => {
+    try {
+        const safePath = validateSafePath(req.params.filename);
+        if (fs.existsSync(safePath)) {
+            res.download(safePath);
+        }
+        else {
+            res.status(404).send('File not found');
+        }
+    }
+    catch (error) {
+        res.status(400).send(error.message);
+    }
+});
+app.delete('/api/files/:filename', (req, res) => {
+    try {
+        deleteFile(req.params.filename);
+        res.json({ message: 'File deleted successfully' });
+    }
+    catch (error) {
+        res.status(400).json({ error: error.message });
+    }
+});
+const PREVIEWABLE_EXTENSIONS = ['.txt', '.md'];
+const PREVIEW_MAX_SIZE = 1024 * 1024; // 1 MB
+app.get('/api/preview/:filename', (req, res) => {
+    try {
+        const ext = path.extname(req.params.filename).toLowerCase();
+        if (!PREVIEWABLE_EXTENSIONS.includes(ext)) {
+            return res.status(400).json({ error: 'Preview not supported for this file type' });
+        }
+        const safePath = validateSafePath(req.params.filename);
+        if (!fs.existsSync(safePath)) {
+            return res.status(404).json({ error: 'File not found' });
+        }
+        const stats = fs.statSync(safePath);
+        if (stats.size > PREVIEW_MAX_SIZE) {
+            return res.status(400).json({ error: 'File too large to preview (max 1 MB)' });
+        }
+        const content = fs.readFileSync(safePath, 'utf-8');
+        res.json({ content, type: ext === '.md' ? 'markdown' : 'text' });
+    }
+    catch (error) {
+        res.status(400).json({ error: error.message });
+    }
+});
+app.post('/api/upload', upload.single('file'), (req, res) => {
+    if (req.file) {
+        res.json({ message: 'File uploaded successfully', filename: req.file.filename });
+    }
+    else {
+        res.status(400).json({ error: 'No file uploaded' });
+    }
+});
+app.get('/api/config', (req, res) => {
+    const config = getConfig();
+    res.json({
+        shared_folder_path: config.shared_folder_path,
+        mcp_data_dir: config.MCP_DATA_DIR
+    });
+});
+app.post('/api/config', (req, res) => {
+    try {
+        const { shared_folder_path } = req.body;
+        if (!shared_folder_path) {
+            return res.status(400).json({ error: 'shared_folder_path is required' });
+        }
+        saveConfig({ shared_folder_path });
+        res.json({ message: 'Configuration updated successfully' });
+    }
+    catch (error) {
+        res.status(500).json({ error: error.message });
+    }
+});
+// GET /api/configurations — Convention méta-config proxy
+app.get('/api/configurations', (req, res) => {
+    const config = getConfig();
+    res.json({
+        configurations: [{
+                id: 'default',
+                name: 'Configuration actuelle',
+                description: `Dossier partagé: ${config.shared_folder_path}`,
+                active: true
+            }]
+    });
+});
+// POST /api/configurations/apply — Convention méta-config proxy
+app.post('/api/configurations/apply', (req, res) => {
+    const { configId } = req.body;
+    if (configId === 'default') {
+        return res.json({ success: true, appliedConfig: 'default' });
+    }
+    return res.status(404).json({ success: false, error: `Configuration "${configId}" not found` });
+});
+// SPA Support fallback
+const publicDir = path.resolve(__dirname, '../public');
+app.use(express.static(publicDir));
+app.get(/^(?!\/api\/|\/proxy\/)/, (req, res) => {
+    const indexHtml = path.join(publicDir, 'index.html');
+    if (fs.existsSync(indexHtml)) {
+        res.sendFile(indexHtml);
+    }
+    else {
+        res.status(404).send('GUI not built yet. Run build process.');
+    }
+});
+// Proxy registration & server startup
+const config = getConfig();
+async function registerWithProxy() {
+    if (!config.PROXY_URL || !config.PROXY_APP_PATH)
+        return null;
+    try {
+        // Check if proxy is up
+        await axios.get(`${config.PROXY_URL}/proxy/health`, { timeout: 2000 });
+        const response = await axios.post(`${config.PROXY_URL}/proxy/register`, {
+            path: config.PROXY_APP_PATH,
+            name: config.PROXY_APP_NAME
+        }, { timeout: 2000 });
+        const assignedPort = response.data.port;
+        console.log(`Successfully registered with proxy at ${config.PROXY_URL}${config.PROXY_APP_PATH} (port ${assignedPort})`);
+        return assignedPort;
+    }
+    catch (error) {
+        console.error(`Failed to register with proxy: ${error.message}`);
+        return null;
+    }
+}
+async function unregisterFromProxy() {
+    if (!config.PROXY_URL || !config.PROXY_APP_PATH)
+        return;
+    try {
+        await axios.delete(`${config.PROXY_URL}/proxy/unregister`, {
+            data: { path: config.PROXY_APP_PATH },
+            timeout: 2000
+        });
+        console.log(`Unregistered from proxy`);
+    }
+    catch (error) {
+        // Ignore error on shutdown
+    }
+}
+let server;
+async function startServer() {
+    let port;
+    if (config.PROXY_URL) {
+        const assignedPort = await registerWithProxy();
+        if (assignedPort) {
+            port = assignedPort;
+        }
+        else {
+            console.error(`Could not register with proxy. Falling back to standalone mode on port ${config.GUI_PORT}.`);
+            port = config.GUI_PORT;
+        }
+    }
+    else {
+        port = config.GUI_PORT;
+    }
+    server = app.listen(port, () => {
+        console.log(`GUI API server listening on port ${port}`);
+    });
+    server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+            console.error(`PORT CONFLICT: Port ${port} is already in use.`);
+        }
+    });
+}
+startServer();
+// IPC and signals
+process.on('message', async (msg) => {
+    if (msg === 'STOP') {
+        console.log('GUI received STOP signal');
+        await unregisterFromProxy();
+        server?.close(() => process.exit(0));
+    }
+});
+process.on('error', (err) => {
+    if (err.code === 'ERR_IPC_CHANNEL_CLOSED') {
+        console.error('[IPC] Channel closed (expected on disconnect).');
+        return;
+    }
+    console.error(`[Process] Error: ${err.message}`);
+});
+process.on('disconnect', () => {
+    console.error('Disconnected from parent, exiting.');
+    process.exit(0);
+});
+process.on('SIGTERM', async () => {
+    await unregisterFromProxy();
+    process.exit(0);
+});

package/dist/mcp-server.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { fork } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+import { setupLogging } from './utils/logger.js';
+import { getConfig } from './utils/config-manager.js';
+import { getSharedFiles, validateSafePath } from './utils/file-manager.js';
+import { VERSION } from './version.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+setupLogging('MASTER');
+const server = new Server({
+    name: 'file-share-mcp',
+    version: VERSION,
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+let guiProcess = null;
+/**
+ * Envoi IPC robuste — vérifie que le canal est connecté avant d'envoyer
+ */
+function safeSend(proc, message) {
+    if (proc && typeof proc.send === 'function' && proc.connected) {
+        try {
+            return proc.send(message);
+        }
+        catch (err) {
+            console.error(`[IPC] Failed to send message: ${err.message}`);
+            return false;
+        }
+    }
+    return false;
+}
+function startGui() {
+    if (guiProcess) {
+        guiProcess.kill();
+    }
+    const guiPath = path.join(__dirname, 'gui.js');
+    guiProcess = fork(guiPath, [], {
+        stdio: ['ignore', 'pipe', 'inherit', 'ipc'],
+        env: { ...process.env }
+    });
+    // Redirect GUI stdout to stderr to protect JSON-RPC
+    guiProcess.stdout?.on('data', (data) => {
+        process.stderr.write(data);
+    });
+    guiProcess.on('message', (message) => {
+        if (message === 'RESTART') {
+            console.log('GUI requested restart...');
+            startGui();
+        }
+        else if (message === 'STOP') {
+            console.log('GUI requested stop...');
+            cleanup().then(() => process.exit(0));
+        }
+    });
+    guiProcess.on('exit', (code) => {
+        if (code !== 0 && code !== null) {
+            console.error(`GUI process exited with code ${code}. Restarting...`);
+            setTimeout(startGui, 2000);
+        }
+    });
+}
+async function cleanup() {
+    console.log('Cleaning up...');
+    if (guiProcess) {
+        safeSend(guiProcess, 'STOP');
+        // Give it a moment to stop gracefully
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        guiProcess.kill();
+    }
+}
+process.on('SIGINT', async () => {
+    await cleanup();
+    process.exit(0);
+});
+process.on('SIGTERM', async () => {
+    await cleanup();
+    process.exit(0);
+});
+// Tool Definitions
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'get_shared_folder',
+                description: 'Get the current path of the shared folder where files are stored.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'list_shared_files',
+                description: 'List all files currently available in the shared folder.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'share_file',
+                description: 'Notify the user that a file is available in the shared folder. This tool does not move files, it just informs the user. IMPORTANT: You must provide the ABSOLUTE path to the file.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        filename: {
+                            type: 'string',
+                            description: 'The absolute path of the file to share.',
+                        },
+                    },
+                    required: ['filename'],
+                },
+            },
+            {
+                name: 'preview_file',
+                description: 'Preview the content of a .txt or .md (Markdown) file from the shared folder. Returns the raw text content (max 1 MB).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        filename: {
+                            type: 'string',
+                            description: 'The name of the file to preview (filename only, not the full path).',
+                        },
+                    },
+                    required: ['filename'],
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'get_shared_folder': {
+                const config = getConfig();
+                return {
+                    content: [{ type: 'text', text: `Shared folder path: ${config.shared_folder_path}` }],
+                };
+            }
+            case 'list_shared_files': {
+                const files = getSharedFiles();
+                if (files.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: 'The shared folder is empty.' }],
+                    };
+                }
+                const fileList = files.map(f => `- ${f.name} (${(f.size / 1024).toFixed(2)} KB)`).join('\n');
+                return {
+                    content: [{ type: 'text', text: `Files in shared folder:\n${fileList}` }],
+                };
+            }
+            case 'share_file': {
+                const { filename } = z.object({ filename: z.string() }).parse(args);
+                return {
+                    content: [{ type: 'text', text: `File "${filename}" has been shared and is visible in the GUI.` }],
+                };
+            }
+            case 'preview_file': {
+                const { filename } = z.object({ filename: z.string() }).parse(args);
+                const ext = path.extname(filename).toLowerCase();
+                if (!['.txt', '.md'].includes(ext)) {
+                    return {
+                        content: [{ type: 'text', text: `Error: Preview is only supported for .txt and .md files.` }],
+                        isError: true,
+                    };
+                }
+                const safePath = validateSafePath(filename);
+                if (!fs.existsSync(safePath)) {
+                    return {
+                        content: [{ type: 'text', text: `Error: File "${filename}" not found in shared folder.` }],
+                        isError: true,
+                    };
+                }
+                const stats = fs.statSync(safePath);
+                if (stats.size > 1024 * 1024) {
+                    return {
+                        content: [{ type: 'text', text: `Error: File too large to preview (max 1 MB).` }],
+                        isError: true,
+                    };
+                }
+                const content = fs.readFileSync(safePath, 'utf-8');
+                return {
+                    content: [{ type: 'text', text: content }],
+                };
+            }
+            default:
+                throw new Error(`Tool not found: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error.message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.log('File Share MCP Server started');
+    startGui();
+}
+main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});

package/dist/utils/config-manager.js

@@ -0,0 +1,58 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.resolve(__dirname, '../../');
+const envPath = path.join(rootDir, '.env');
+// User-level base dir that survives package updates
+const USER_BASE_DIR = path.join(os.homedir(), '.file-share-mcp');
+const DEFAULT_CONFIG = {
+    shared_folder_path: path.join(USER_BASE_DIR, 'shared'),
+};
+export function getConfig() {
+    dotenv.config({ path: envPath, override: true });
+    const dataDirEnv = process.env.MCP_DATA_DIR;
+    const dataDir = dataDirEnv
+        ? (path.isAbsolute(dataDirEnv) ? dataDirEnv : path.resolve(rootDir, dataDirEnv))
+        : USER_BASE_DIR;
+    if (!fs.existsSync(dataDir)) {
+        fs.mkdirSync(dataDir, { recursive: true });
+    }
+    const configsPath = path.join(dataDir, 'configs.json');
+    let currentConfig = { ...DEFAULT_CONFIG };
+    if (fs.existsSync(configsPath)) {
+        try {
+            const saved = JSON.parse(fs.readFileSync(configsPath, 'utf-8'));
+            currentConfig = { ...currentConfig, ...saved };
+        }
+        catch (err) {
+            console.error('Failed to parse configs.json:', err);
+        }
+    }
+    else {
+        fs.writeFileSync(configsPath, JSON.stringify(currentConfig, null, 2));
+    }
+    return {
+        ...currentConfig,
+        GUI_PORT: parseInt(process.env.GUI_PORT || '3005', 10),
+        PROXY_URL: process.env.PROXY_URL,
+        PROXY_APP_PATH: process.env.PROXY_APP_PATH || '/file-share',
+        PROXY_APP_NAME: process.env.PROXY_APP_NAME || 'File Share MCP',
+        MCP_DATA_DIR: dataDir,
+    };
+}
+export function saveConfig(newConfig) {
+    const fullConfig = getConfig();
+    const configsPath = path.join(fullConfig.MCP_DATA_DIR, 'configs.json');
+    const configToSave = {
+        shared_folder_path: newConfig.shared_folder_path || fullConfig.shared_folder_path,
+    };
+    fs.writeFileSync(configsPath, JSON.stringify(configToSave, null, 2));
+    // Ensure shared folder exists
+    if (!fs.existsSync(configToSave.shared_folder_path)) {
+        fs.mkdirSync(configToSave.shared_folder_path, { recursive: true });
+    }
+}

package/dist/utils/file-manager.js

@@ -0,0 +1,39 @@
+import fs from 'fs';
+import path from 'path';
+import { getConfig } from './config-manager.js';
+export function getSharedFiles() {
+    const { shared_folder_path } = getConfig();
+    if (!fs.existsSync(shared_folder_path)) {
+        fs.mkdirSync(shared_folder_path, { recursive: true });
+        return [];
+    }
+    return fs.readdirSync(shared_folder_path).filter(file => {
+        const filePath = path.join(shared_folder_path, file);
+        return fs.statSync(filePath).isFile();
+    }).map(file => {
+        const filePath = path.join(shared_folder_path, file);
+        const stats = fs.statSync(filePath);
+        return {
+            name: file,
+            size: stats.size,
+            mtime: stats.mtime,
+            extension: path.extname(file).toLowerCase(),
+        };
+    });
+}
+export function validateSafePath(filename) {
+    const { shared_folder_path } = getConfig();
+    const safeName = path.basename(filename);
+    const fullPath = path.join(shared_folder_path, safeName);
+    // Extra safety check
+    if (!fullPath.startsWith(path.resolve(shared_folder_path))) {
+        throw new Error('Path traversal detected');
+    }
+    return fullPath;
+}
+export function deleteFile(filename) {
+    const fullPath = validateSafePath(filename);
+    if (fs.existsSync(fullPath)) {
+        fs.unlinkSync(fullPath);
+    }
+}