@universal-mcp-toolkit/server-filesystem 0.1.0

package/.well-known/mcp-server.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/json",
+  "name": "filesystem",
+  "title": "FileSystem MCP Server",
+  "description": "Safe, allowlisted file listing, reading, and writing tools.",
+  "version": "0.1.0",
+  "packageName": "@universal-mcp-toolkit/server-filesystem",
+  "homepage": "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  "transports": [
+    "stdio",
+    "sse"
+  ],
+  "authentication": {
+    "mode": "environment-variables",
+    "required": [
+      "FILESYSTEM_ROOTS"
+    ]
+  },
+  "capabilities": {
+    "tools": true,
+    "resources": true,
+    "prompts": true
+  },
+  "tools": [
+    "list_files",
+    "read_file",
+    "write_file"
+  ],
+  "resources": [
+    "workspace"
+  ],
+  "prompts": [
+    "change-plan"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 universal-mcp-toolkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+import * as _universal_mcp_toolkit_core from '@universal-mcp-toolkit/core';
+import { ToolkitServer, ToolkitServerMetadata } from '@universal-mcp-toolkit/core';
+import { z } from 'zod';
+
+declare const metadata: ToolkitServerMetadata;
+declare const serverCard: _universal_mcp_toolkit_core.ToolkitServerCard;
+type FileEncoding = "utf8" | "base64";
+declare const fileEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    absolutePath: z.ZodString;
+    type: z.ZodEnum<{
+        file: "file";
+        directory: "directory";
+    }>;
+    sizeBytes: z.ZodNumber;
+    modifiedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+declare const workspaceSummarySchema: z.ZodObject<{
+    roots: z.ZodArray<z.ZodObject<{
+        root: z.ZodString;
+        available: z.ZodBoolean;
+    }, z.core.$strip>>;
+    maxReadBytes: z.ZodNumber;
+    maxWriteBytes: z.ZodNumber;
+    sampleEntries: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        absolutePath: z.ZodString;
+        type: z.ZodEnum<{
+            file: "file";
+            directory: "directory";
+        }>;
+        sizeBytes: z.ZodNumber;
+        modifiedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const listFilesOutputSchema: z.ZodObject<{
+    root: z.ZodString;
+    directory: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        absolutePath: z.ZodString;
+        type: z.ZodEnum<{
+            file: "file";
+            directory: "directory";
+        }>;
+        sizeBytes: z.ZodNumber;
+        modifiedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    truncated: z.ZodBoolean;
+}, z.core.$strip>;
+declare const readFileOutputSchema: z.ZodObject<{
+    path: z.ZodString;
+    absolutePath: z.ZodString;
+    encoding: z.ZodEnum<{
+        utf8: "utf8";
+        base64: "base64";
+    }>;
+    content: z.ZodString;
+    bytes: z.ZodNumber;
+}, z.core.$strip>;
+declare const writeFileOutputSchema: z.ZodObject<{
+    path: z.ZodString;
+    absolutePath: z.ZodString;
+    bytesWritten: z.ZodNumber;
+    created: z.ZodBoolean;
+    overwritten: z.ZodBoolean;
+}, z.core.$strip>;
+type FileEntry = z.infer<typeof fileEntrySchema>;
+type WorkspaceSummary = z.infer<typeof workspaceSummarySchema>;
+type ListFilesOutput = z.infer<typeof listFilesOutputSchema>;
+type ReadFileOutput = z.infer<typeof readFileOutputSchema>;
+type WriteFileOutput = z.infer<typeof writeFileOutputSchema>;
+interface FileSystemService {
+    listFiles(input: {
+        path?: string;
+        root?: string;
+        recursive: boolean;
+        maxEntries: number;
+    }): Promise<ListFilesOutput>;
+    readFile(input: {
+        path: string;
+        root?: string;
+        encoding: FileEncoding;
+        maxBytes?: number;
+    }): Promise<ReadFileOutput>;
+    writeFile(input: {
+        path: string;
+        root?: string;
+        content: string;
+        encoding: FileEncoding;
+        overwrite: boolean;
+        createDirectories: boolean;
+    }): Promise<WriteFileOutput>;
+    getWorkspaceSummary(): Promise<WorkspaceSummary>;
+}
+interface CreateFileSystemServerOptions {
+    service?: FileSystemService;
+    env?: NodeJS.ProcessEnv;
+}
+declare class DefaultFileSystemService implements FileSystemService {
+    private readonly roots;
+    private readonly maxReadBytes;
+    private readonly maxWriteBytes;
+    private constructor();
+    static fromEnv(source?: NodeJS.ProcessEnv): Promise<DefaultFileSystemService>;
+    listFiles(input: {
+        path?: string;
+        root?: string;
+        recursive: boolean;
+        maxEntries: number;
+    }): Promise<ListFilesOutput>;
+    readFile(input: {
+        path: string;
+        root?: string;
+        encoding: FileEncoding;
+        maxBytes?: number;
+    }): Promise<ReadFileOutput>;
+    writeFile(input: {
+        path: string;
+        root?: string;
+        content: string;
+        encoding: FileEncoding;
+        overwrite: boolean;
+        createDirectories: boolean;
+    }): Promise<WriteFileOutput>;
+    getWorkspaceSummary(): Promise<WorkspaceSummary>;
+    private resolveSafePath;
+    private selectRoot;
+}
+declare class FileSystemServer extends ToolkitServer {
+    private readonly service;
+    constructor(service: FileSystemService);
+}
+declare function createServer(options?: CreateFileSystemServerOptions): Promise<FileSystemServer>;
+declare function main(argv?: readonly string[]): Promise<void>;
+
+export { type CreateFileSystemServerOptions, DefaultFileSystemService, type FileEntry, FileSystemServer, type FileSystemService, type ListFilesOutput, type ReadFileOutput, type WorkspaceSummary, type WriteFileOutput, createServer, main, metadata, serverCard };

package/dist/index.js

@@ -0,0 +1,480 @@
+// src/index.ts
+import {
+  ConfigurationError,
+  createServerCard,
+  defineTool,
+  loadEnv,
+  parseRuntimeOptions,
+  runToolkitServer,
+  ToolkitServer,
+  ValidationError
+} from "@universal-mcp-toolkit/core";
+import { promises as fs } from "fs";
+import { dirname, isAbsolute, join, normalize, relative, resolve as resolvePath } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+var toolNames = ["list_files", "read_file", "write_file"];
+var resourceNames = ["workspace"];
+var promptNames = ["change-plan"];
+var metadata = {
+  id: "filesystem",
+  title: "FileSystem MCP Server",
+  description: "Safe, allowlisted file listing, reading, and writing tools.",
+  version: "0.1.0",
+  packageName: "@universal-mcp-toolkit/server-filesystem",
+  homepage: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  repositoryUrl: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  documentationUrl: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit/tree/main/servers/filesystem",
+  envVarNames: ["FILESYSTEM_ROOTS"],
+  transports: ["stdio", "sse"],
+  toolNames,
+  resourceNames,
+  promptNames
+};
+var serverCard = createServerCard(metadata);
+var envShape = {
+  FILESYSTEM_ROOTS: z.string().min(1),
+  FILESYSTEM_MAX_READ_BYTES: z.string().regex(/^\d+$/).optional(),
+  FILESYSTEM_MAX_WRITE_BYTES: z.string().regex(/^\d+$/).optional()
+};
+var encodingSchema = z.enum(["utf8", "base64"]);
+var fileEntrySchema = z.object({
+  path: z.string(),
+  absolutePath: z.string(),
+  type: z.enum(["file", "directory"]),
+  sizeBytes: z.number().int().nonnegative(),
+  modifiedAt: z.string().nullable()
+});
+var workspaceRootSchema = z.object({
+  root: z.string(),
+  available: z.boolean()
+});
+var workspaceSummarySchema = z.object({
+  roots: z.array(workspaceRootSchema),
+  maxReadBytes: z.number().int().positive(),
+  maxWriteBytes: z.number().int().positive(),
+  sampleEntries: z.array(fileEntrySchema)
+});
+var listFilesOutputSchema = z.object({
+  root: z.string(),
+  directory: z.string(),
+  entries: z.array(fileEntrySchema),
+  truncated: z.boolean()
+});
+var readFileOutputSchema = z.object({
+  path: z.string(),
+  absolutePath: z.string(),
+  encoding: encodingSchema,
+  content: z.string(),
+  bytes: z.number().int().nonnegative()
+});
+var writeFileOutputSchema = z.object({
+  path: z.string(),
+  absolutePath: z.string(),
+  bytesWritten: z.number().int().nonnegative(),
+  created: z.boolean(),
+  overwritten: z.boolean()
+});
+function resolveEnv(source = process.env) {
+  return loadEnv(envShape, source);
+}
+function parseLimit(raw, fallback) {
+  if (raw === void 0) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new ConfigurationError(`Expected a positive integer but received '${raw}'.`);
+  }
+  return parsed;
+}
+function normalizeForComparison(value) {
+  const resolved = normalize(resolvePath(value));
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function isPathInside(root, candidate) {
+  const relation = relative(root, candidate);
+  return relation === "" || !relation.startsWith("..") && !isAbsolute(relation);
+}
+async function ensureDirectory(path) {
+  const stat = await fs.stat(path).catch(() => void 0);
+  if (!stat || !stat.isDirectory()) {
+    throw new ConfigurationError(`Allowlisted root '${path}' must exist and be a directory.`);
+  }
+}
+async function findNearestExistingAncestor(path) {
+  let current = path;
+  while (true) {
+    const stat = await fs.lstat(current).catch(() => void 0);
+    if (stat) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return current;
+    }
+    current = parent;
+  }
+}
+function toRelativePath(root, absolutePath) {
+  const relativePath = relative(root, absolutePath);
+  return relativePath.length === 0 ? "." : relativePath;
+}
+function toTimestamp(date) {
+  return date.toISOString();
+}
+function splitRoots(raw) {
+  return raw.split(";").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+var DefaultFileSystemService = class _DefaultFileSystemService {
+  roots;
+  maxReadBytes;
+  maxWriteBytes;
+  constructor(roots, maxReadBytes, maxWriteBytes) {
+    this.roots = roots;
+    this.maxReadBytes = maxReadBytes;
+    this.maxWriteBytes = maxWriteBytes;
+  }
+  static async fromEnv(source = process.env) {
+    const env = resolveEnv(source);
+    const roots = splitRoots(env.FILESYSTEM_ROOTS);
+    if (roots.length === 0) {
+      throw new ConfigurationError("FILESYSTEM_ROOTS must contain at least one absolute path.");
+    }
+    const normalizedRoots = [];
+    for (const root of roots) {
+      if (!isAbsolute(root)) {
+        throw new ConfigurationError(`FILESYSTEM_ROOTS entry '${root}' must be an absolute path.`);
+      }
+      await ensureDirectory(root);
+      normalizedRoots.push({
+        root: resolvePath(root),
+        realRoot: await fs.realpath(root)
+      });
+    }
+    return new _DefaultFileSystemService(
+      normalizedRoots,
+      parseLimit(env.FILESYSTEM_MAX_READ_BYTES, 1024 * 1024),
+      parseLimit(env.FILESYSTEM_MAX_WRITE_BYTES, 1024 * 1024)
+    );
+  }
+  async listFiles(input) {
+    const resolvedPath = await this.resolveSafePath(input.path ?? ".", input.root);
+    const stat = await fs.stat(resolvedPath.absolutePath).catch(() => void 0);
+    if (!stat || !stat.isDirectory()) {
+      throw new ValidationError(`Path '${resolvedPath.absolutePath}' is not a directory.`);
+    }
+    const queue = [resolvedPath.absolutePath];
+    const entries = [];
+    let truncated = false;
+    while (queue.length > 0 && entries.length < input.maxEntries) {
+      const current = queue.shift();
+      if (!current) {
+        break;
+      }
+      const children = await fs.readdir(current, { withFileTypes: true });
+      for (const child of children) {
+        if (child.isSymbolicLink()) {
+          continue;
+        }
+        const childPath = join(current, child.name);
+        const childStat = await fs.stat(childPath);
+        const entry = {
+          path: toRelativePath(resolvedPath.root, childPath),
+          absolutePath: childPath,
+          type: child.isDirectory() ? "directory" : "file",
+          sizeBytes: child.isDirectory() ? 0 : childStat.size,
+          modifiedAt: toTimestamp(childStat.mtime)
+        };
+        entries.push(entry);
+        if (entries.length >= input.maxEntries) {
+          truncated = true;
+          break;
+        }
+        if (input.recursive && child.isDirectory()) {
+          queue.push(childPath);
+        }
+      }
+    }
+    if (queue.length > 0) {
+      truncated = true;
+    }
+    return {
+      root: resolvedPath.root,
+      directory: resolvedPath.absolutePath,
+      entries,
+      truncated
+    };
+  }
+  async readFile(input) {
+    const resolvedPath = await this.resolveSafePath(input.path, input.root);
+    const stat = await fs.stat(resolvedPath.absolutePath).catch(() => void 0);
+    if (!stat || !stat.isFile()) {
+      throw new ValidationError(`Path '${resolvedPath.absolutePath}' is not a file.`);
+    }
+    const effectiveMaxBytes = input.maxBytes ?? this.maxReadBytes;
+    if (stat.size > effectiveMaxBytes) {
+      throw new ValidationError(`File exceeds the allowed read size of ${effectiveMaxBytes} bytes.`);
+    }
+    const buffer = await fs.readFile(resolvedPath.absolutePath);
+    const content = input.encoding === "base64" ? buffer.toString("base64") : buffer.toString("utf8");
+    return {
+      path: resolvedPath.requestedPath,
+      absolutePath: resolvedPath.absolutePath,
+      encoding: input.encoding,
+      content,
+      bytes: buffer.byteLength
+    };
+  }
+  async writeFile(input) {
+    const resolvedPath = await this.resolveSafePath(input.path, input.root);
+    const buffer = input.encoding === "base64" ? Buffer.from(input.content, "base64") : Buffer.from(input.content, "utf8");
+    if (buffer.byteLength > this.maxWriteBytes) {
+      throw new ValidationError(`Content exceeds the allowed write size of ${this.maxWriteBytes} bytes.`);
+    }
+    const existingStat = await fs.stat(resolvedPath.absolutePath).catch(() => void 0);
+    if (existingStat?.isDirectory()) {
+      throw new ValidationError(`Path '${resolvedPath.absolutePath}' is a directory.`);
+    }
+    if (existingStat && !input.overwrite) {
+      throw new ValidationError(`Path '${resolvedPath.absolutePath}' already exists and overwrite=false.`);
+    }
+    const parent = dirname(resolvedPath.absolutePath);
+    if (input.createDirectories) {
+      await fs.mkdir(parent, { recursive: true });
+    } else {
+      const parentStat = await fs.stat(parent).catch(() => void 0);
+      if (!parentStat || !parentStat.isDirectory()) {
+        throw new ValidationError(`Parent directory '${parent}' does not exist.`);
+      }
+    }
+    await fs.writeFile(resolvedPath.absolutePath, buffer, { flag: input.overwrite ? "w" : "wx" });
+    return {
+      path: resolvedPath.requestedPath,
+      absolutePath: resolvedPath.absolutePath,
+      bytesWritten: buffer.byteLength,
+      created: !existingStat,
+      overwritten: Boolean(existingStat)
+    };
+  }
+  async getWorkspaceSummary() {
+    const sampleRoot = this.roots[0]?.root;
+    const sampleEntries = sampleRoot === void 0 ? [] : (await this.listFiles({ path: sampleRoot, recursive: false, maxEntries: 10 })).entries;
+    return {
+      roots: await Promise.all(
+        this.roots.map(async (root) => ({
+          root: root.root,
+          available: Boolean(await fs.stat(root.root).catch(() => void 0))
+        }))
+      ),
+      maxReadBytes: this.maxReadBytes,
+      maxWriteBytes: this.maxWriteBytes,
+      sampleEntries
+    };
+  }
+  async resolveSafePath(requestedPath, requestedRoot) {
+    const rootConfig = this.selectRoot(requestedRoot);
+    const candidate = isAbsolute(requestedPath) ? resolvePath(requestedPath) : resolvePath(rootConfig.root, requestedPath);
+    const normalizedRoot = normalizeForComparison(rootConfig.root);
+    const normalizedCandidate = normalizeForComparison(candidate);
+    if (!isPathInside(normalizedRoot, normalizedCandidate)) {
+      throw new ValidationError(`Path '${requestedPath}' resolves outside the allowlisted roots.`);
+    }
+    const ancestor = await findNearestExistingAncestor(candidate);
+    const realAncestor = await fs.realpath(ancestor).catch(() => ancestor);
+    const normalizedRealRoot = normalizeForComparison(rootConfig.realRoot);
+    const normalizedRealAncestor = normalizeForComparison(realAncestor);
+    if (!isPathInside(normalizedRealRoot, normalizedRealAncestor)) {
+      throw new ValidationError(`Path '${requestedPath}' resolves through an unsafe symlinked location.`);
+    }
+    const existingTarget = await fs.lstat(candidate).catch(() => void 0);
+    if (existingTarget) {
+      const realTarget = await fs.realpath(candidate).catch(() => candidate);
+      if (!isPathInside(normalizedRealRoot, normalizeForComparison(realTarget))) {
+        throw new ValidationError(`Path '${requestedPath}' resolves outside the allowlisted roots.`);
+      }
+    }
+    return {
+      root: rootConfig.root,
+      absolutePath: candidate,
+      requestedPath
+    };
+  }
+  selectRoot(requestedRoot) {
+    if (requestedRoot === void 0 || requestedRoot.trim().length === 0) {
+      const fallback = this.roots[0];
+      if (!fallback) {
+        throw new ConfigurationError("No filesystem roots are configured.");
+      }
+      return fallback;
+    }
+    const normalizedRequested = normalizeForComparison(requestedRoot);
+    const root = this.roots.find((entry) => normalizeForComparison(entry.root) === normalizedRequested);
+    if (!root) {
+      throw new ValidationError(`Root '${requestedRoot}' is not allowlisted.`);
+    }
+    return root;
+  }
+};
+var FileSystemServer = class extends ToolkitServer {
+  service;
+  constructor(service) {
+    super(metadata);
+    this.service = service;
+    this.registerTool(
+      defineTool({
+        name: "list_files",
+        title: "List files",
+        description: "List files under an allowlisted root directory.",
+        inputSchema: {
+          path: z.string().trim().min(1).optional(),
+          root: z.string().trim().min(1).optional(),
+          recursive: z.boolean().default(false),
+          maxEntries: z.number().int().min(1).max(200).default(50)
+        },
+        outputSchema: {
+          root: z.string(),
+          directory: z.string(),
+          entries: z.array(fileEntrySchema),
+          truncated: z.boolean()
+        },
+        handler: async ({ path, root, recursive, maxEntries }, context) => {
+          await context.log("info", "Listing files from an allowlisted root");
+          const request = { recursive, maxEntries };
+          if (path !== void 0) {
+            request.path = path;
+          }
+          if (root !== void 0) {
+            request.root = root;
+          }
+          return this.service.listFiles(request);
+        },
+        renderText: ({ directory, entries }) => `${directory}
+${entries.map((entry) => `${entry.type}: ${entry.path}`).join("\n")}`
+      })
+    );
+    this.registerTool(
+      defineTool({
+        name: "read_file",
+        title: "Read file",
+        description: "Read a file from an allowlisted root.",
+        inputSchema: {
+          path: z.string().trim().min(1),
+          root: z.string().trim().min(1).optional(),
+          encoding: encodingSchema.default("utf8"),
+          maxBytes: z.number().int().min(1).max(10 * 1024 * 1024).optional()
+        },
+        outputSchema: {
+          path: z.string(),
+          absolutePath: z.string(),
+          encoding: encodingSchema,
+          content: z.string(),
+          bytes: z.number().int().nonnegative()
+        },
+        handler: async ({ path, root, encoding, maxBytes }, context) => {
+          await context.log("info", `Reading file ${path}`);
+          const request = { path, encoding };
+          if (root !== void 0) {
+            request.root = root;
+          }
+          if (maxBytes !== void 0) {
+            request.maxBytes = maxBytes;
+          }
+          return this.service.readFile(request);
+        },
+        renderText: ({ absolutePath, content }) => `${absolutePath}
+${content}`
+      })
+    );
+    this.registerTool(
+      defineTool({
+        name: "write_file",
+        title: "Write file",
+        description: "Write a file inside an allowlisted root.",
+        inputSchema: {
+          path: z.string().trim().min(1),
+          root: z.string().trim().min(1).optional(),
+          content: z.string(),
+          encoding: encodingSchema.default("utf8"),
+          overwrite: z.boolean().default(false),
+          createDirectories: z.boolean().default(true)
+        },
+        outputSchema: {
+          path: z.string(),
+          absolutePath: z.string(),
+          bytesWritten: z.number().int().nonnegative(),
+          created: z.boolean(),
+          overwritten: z.boolean()
+        },
+        handler: async ({ path, root, content, encoding, overwrite, createDirectories }, context) => {
+          await context.log("info", `Writing file ${path}`);
+          const request = { path, content, encoding, overwrite, createDirectories };
+          if (root !== void 0) {
+            request.root = root;
+          }
+          return this.service.writeFile(request);
+        },
+        renderText: ({ absolutePath, bytesWritten }) => `Wrote ${bytesWritten} bytes to ${absolutePath}`
+      })
+    );
+    this.registerStaticResource(
+      "workspace",
+      "filesystem://workspace",
+      {
+        title: "Workspace summary",
+        description: "Configured allowlisted roots and a sample directory listing.",
+        mimeType: "application/json"
+      },
+      async (uri) => this.createJsonResource(uri.toString(), await this.service.getWorkspaceSummary())
+    );
+    this.registerPrompt(
+      "change-plan",
+      {
+        title: "Change plan prompt",
+        description: "Draft a careful filesystem change plan before editing local files.",
+        argsSchema: {
+          targetPath: z.string().trim().min(1),
+          goal: z.string().trim().min(1),
+          constraints: z.string().trim().min(1).optional()
+        }
+      },
+      async ({ targetPath, goal, constraints }) => this.createTextPrompt(
+        [
+          `Plan a safe file-system change for ${targetPath}.`,
+          `Goal: ${goal}.`,
+          constraints ? `Constraints: ${constraints}.` : "Include backups, validation, rollback, and scope-control steps.",
+          "Keep all work within allowlisted roots and call out any irreversible operations."
+        ].join(" ")
+      )
+    );
+  }
+};
+async function createServer(options = {}) {
+  const service = options.service ?? await DefaultFileSystemService.fromEnv(options.env);
+  return new FileSystemServer(service);
+}
+function isMainModule(metaUrl) {
+  const entry = process.argv[1];
+  return typeof entry === "string" && fileURLToPath(metaUrl) === resolvePath(entry);
+}
+async function main(argv = process.argv.slice(2)) {
+  const runtimeOptions = parseRuntimeOptions(argv);
+  await runToolkitServer(
+    {
+      createServer: () => createServer(),
+      serverCard
+    },
+    runtimeOptions
+  );
+}
+if (isMainModule(import.meta.url)) {
+  await main();
+}
+export {
+  DefaultFileSystemService,
+  FileSystemServer,
+  createServer,
+  main,
+  metadata,
+  serverCard
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@universal-mcp-toolkit/server-filesystem",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Safe sandboxed file read and write tools for local workflows.",
+  "license": "MIT",
+  "bin": {
+    "server-filesystem": "./dist/index.js",
+    "umt-filesystem": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Markgatcha/universal-mcp-toolkit.git"
+  },
+  "homepage": "https://github.com/Markgatcha/universal-mcp-toolkit#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    ".well-known"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "developer-tools",
+    "typescript",
+    "filesystem",
+    "files",
+    "local",
+    "sandbox"
+  ],
+  "dependencies": {
+    "@universal-mcp-toolkit/core": "0.1.0",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx watch src/index.ts",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rimraf dist"
+  }
+}