@@ -115,7 +115,8 @@ The generation step sends selected project content to the configured provider.
 - Search: up to 5,000 entries, 200 matches, 240 characters per matching line.
 - Documentation gathering: first 40 Markdown files among up to 2,000 entries; files over 40,000 bytes are skipped. Gathered file and Markdown context is limited to 24,000 characters. This is not a global prompt limit: tree/package context, an existing document and a caller-supplied question can add content according to the selected tool.
 - Listing skips build/dependency directories such as `node_modules`, `.git`, `.next`, `out`, `dist`, `prebuilt`, `.turbo` and `coverage`. It does not interpret `.gitignore`; files such as `.env` are not automatically excluded. Run only in a trusted project and select the content to expose.
-- Path checks use lexical containment; do not treat the process as an operating-system sandbox or assume symlink/junction isolation. Loading `project://config` can import JavaScript/TypeScript configuration.
+- Filesystem tools check both lexical paths and canonical filesystem paths. Reads and directory listings reject symlinks/junctions that resolve outside the project root. Writes also validate the nearest existing parent before creating directories and reject symbolic links at the destination, including links to internal files. Search skips linked files whose contents cannot be read safely.
+- These checks protect against links already present when a request is handled; they are not an operating-system sandbox against concurrent path replacement by another process. Run the server in a trusted project with appropriate filesystem permissions. Configuration loading and provider-selection persistence use separate filesystem paths; loading `project://config` can import JavaScript/TypeScript configuration.
 - Tool failures include `isError: true`. Missing resources return `Unavailable: ...`. Check the client's stderr log for startup errors; stdout is reserved for JSON-RPC.
 - If tools work but generation fails, verify provider selection, environment credentials, model availability and service connectivity.
 
 
@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { DocumentationService, patchManagedRegion, type DocKind, type AiProviderId } from "@gitpagedocs/tools";
+import { DocumentationService, RepositoryError, patchManagedRegion, type DocKind, type AiProviderId } from "@gitpagedocs/tools";
 import type { ServerContext } from "../context";
 import { text, safe } from "../result";
 import { repoListing, fileContext, packageContext, gitLog, docsContext } from "../gather";
@@ -19,6 +19,11 @@ async function generate(
 
 const providerOpt = z.string().optional().describe("Override the configured AI provider id.");
 
+function isMissingFile(error: unknown): boolean {
+  const cause = error instanceof RepositoryError ? error.cause : undefined;
+  return typeof cause === "object" && cause !== null && "code" in cause && cause.code === "ENOENT";
+}
+
 /** Documentation generators and analyzers (AI-backed, delegating to tools). */
 export function registerDocsTools(server: McpServer, ctx: ServerContext): void {
   const def = (
@@ -81,8 +86,8 @@ export function registerDocsTools(server: McpServer, ctx: ServerContext): void {
       let existing = "";
       try {
         existing = await ctx.files.read(path);
-      } catch {
-        existing = "";
+      } catch (error) {
+        if (!isMissingFile(error)) throw error;
       }
       const generated = await generate(
         ctx,
 
@@ -0,0 +1,136 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
+import { createServer } from "../src/server";
+
+const FIXTURE_PREFIX = path.join(os.tmpdir(), "gpd-mcp-containment-");
+const EXTERNAL_CONTENT = "# External fixture\nOUTSIDE_MARKER\n";
+const providerRequest = vi.fn<typeof fetch>(async () => new Response(
+  'data: {"choices":[{"delta":{"content":"Generated documentation"}}]}\n\ndata: [DONE]\n\n',
+  { status: 200 },
+));
+let fixture: string;
+let root: string;
+let outside: string;
+let client: Client;
+let server: ReturnType<typeof createServer>;
+
+function toolText(result: unknown): string {
+  return CallToolResultSchema.parse(result).content.flatMap((block) => block.type === "text" ? [block.text] : []).join("\n");
+}
+
+beforeEach(async () => {
+  fixture = mkdtempSync(FIXTURE_PREFIX);
+  root = path.join(fixture, "root");
+  outside = path.join(fixture, "outside");
+  mkdirSync(path.join(root, "docs"), { recursive: true });
+  mkdirSync(outside);
+  writeFileSync(path.join(outside, "secret.md"), EXTERNAL_CONTENT, "utf8");
+  symlinkSync(outside, path.join(root, "docs", "linked"), process.platform === "win32" ? "junction" : "dir");
+  providerRequest.mockClear();
+  vi.stubEnv("OPENAI_API_KEY", "fixture-key");
+  vi.stubGlobal("fetch", providerRequest);
+  server = createServer(root);
+  client = new Client({ name: "filesystem-containment-test", version: "1.0.0" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+afterEach(async () => {
+  await client?.close();
+  await server?.close();
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+  if (!path.resolve(fixture).startsWith(FIXTURE_PREFIX)) throw new Error("Unexpected fixture path");
+  rmSync(fixture, { recursive: true, force: true });
+});
+
+describe("MCP filesystem containment", () => {
+  it("rejects documentation updates through an external directory link before contacting the provider", async () => {
+    const result = await client.callTool({ name: "update_documentation", arguments: { path: "docs/linked/secret.md" } });
+    expect(result.isError).toBe(true);
+    expect(toolText(result)).toMatch(/^VALIDATION_ERROR: Path escapes the project root/);
+    expect(providerRequest).not.toHaveBeenCalled();
+    expect(readFileSync(path.join(outside, "secret.md"), "utf8")).toBe(EXTERNAL_CONTENT);
+  });
+
+  it("rejects writes through an external directory link without replacing the external file", async () => {
+    const result = await client.callTool({
+      name: "write_file",
+      arguments: { path: "docs/linked/secret.md", content: "# Replacement\n" },
+    });
+    expect(result.isError).toBe(true);
+    expect(toolText(result)).toMatch(/^VALIDATION_ERROR: /);
+    expect(readFileSync(path.join(outside, "secret.md"), "utf8")).toBe(EXTERNAL_CONTENT);
+  });
+
+  it("rejects new documentation beneath an external directory link before contacting the provider", async () => {
+    const result = await client.callTool({
+      name: "update_documentation",
+      arguments: { path: "docs/linked/new/guide.md" },
+    });
+    expect(result.isError).toBe(true);
+    expect(toolText(result)).toMatch(/^VALIDATION_ERROR: Path escapes the project root/);
+    expect(providerRequest).not.toHaveBeenCalled();
+    expect(existsSync(path.join(outside, "new"))).toBe(false);
+    expect(readFileSync(path.join(outside, "secret.md"), "utf8")).toBe(EXTERNAL_CONTENT);
+  });
+
+  it("rejects reading an external file through a symbolic link", async () => {
+    symlinkSync(path.join(outside, "secret.md"), path.join(root, "linked.md"), "file");
+    const result = await client.callTool({ name: "read_file", arguments: { path: "linked.md" } });
+    expect(result.isError).toBe(true);
+    expect(toolText(result)).toMatch(/^VALIDATION_ERROR: Path escapes the project root/);
+    expect(toolText(result)).not.toContain(EXTERNAL_CONTENT);
+  });
+
+  it("rejects listing an external directory through a link", async () => {
+    const result = await client.callTool({
+      name: "list_files",
+      arguments: { path: "docs/linked", recursive: true },
+    });
+    expect(result.isError).toBe(true);
+    expect(toolText(result)).toMatch(/^VALIDATION_ERROR: Path escapes the project root/);
+    expect(toolText(result)).not.toContain("secret.md");
+  });
+
+  it("searches internal files without returning content from external file links", async () => {
+    symlinkSync(path.join(outside, "secret.md"), path.join(root, "linked.md"), "file");
+    writeFileSync(path.join(root, "docs", "internal.md"), "# Internal\nOUTSIDE_MARKER inside root\n", "utf8");
+    const result = await client.callTool({
+      name: "search_project",
+      arguments: { query: "OUTSIDE_MARKER", extension: ".md" },
+    });
+    expect(result.isError).not.toBe(true);
+    expect(JSON.parse(toolText(result))).toEqual([
+      { file: "docs/internal.md", line: 2, text: "OUTSIDE_MARKER inside root" },
+    ]);
+  });
+
+  it("rejects creating files beneath an external directory link without creating external directories", async () => {
+    const result = await client.callTool({
+      name: "write_file",
+      arguments: { path: "docs/linked/new/guide.md", content: "# New document\n" },
+    });
+    expect(result.isError).toBe(true);
+    expect(toolText(result)).toMatch(/^VALIDATION_ERROR: Path escapes the project root/);
+    expect(existsSync(path.join(outside, "new"))).toBe(false);
+    expect(readFileSync(path.join(outside, "secret.md"), "utf8")).toBe(EXTERNAL_CONTENT);
+  });
+
+  it("rejects writing through a file link without replacing the external file", async () => {
+    symlinkSync(path.join(outside, "secret.md"), path.join(root, "linked.md"), "file");
+    const result = await client.callTool({
+      name: "write_file",
+      arguments: { path: "linked.md", content: "# Replacement\n" },
+    });
+    expect(result.isError).toBe(true);
+    expect(toolText(result)).toMatch(/^VALIDATION_ERROR: /);
+    expect(readFileSync(path.join(outside, "secret.md"), "utf8")).toBe(EXTERNAL_CONTENT);
+  });
+
+});
@@ -14,7 +14,7 @@ The **shared business-logic core** of the [Git Page Docs](../README.md) monorepo
 | `config-format/` | Browser-safe `compactSiteIcons` / `expandSiteIcons` and `applyRouteDefaults` / `factorRouteDefaults` for compact configuration and inherited route values |
 | `logger/` | Level-filtered logger with **secret redaction** |
 | `errors/` | `AppError` + typed subclasses |
-| `filesystem/` | `FileService` (list/read/write/search with lexical root containment; filesystem symlinks/junctions still require trusted deployment boundaries) |
+| `filesystem/` | `FileService` (list/read/write/search with lexical and canonical root containment; validates existing parents before creating files and rejects destination symlinks on writes; concurrent path replacement still requires trusted filesystem boundaries) |
 | `documentation/` | `DocumentationService`, `patchManagedRegion`, `DocUpdater` |
 | `i18n/` | Language bundles (`site.languages` toggles in `config.json` + `langs/<lang>.json`): `loadConfigLanguageBundles`, `applyLanguageBundles` (fold into `site.langmenu` / `translations`), `filterEnabledLanguages`, `splitLanguageBundles` (generator side); browser-safe |
 | `ports/` | Type-only contracts (logger, cache, crypto, security, config, ai) |
 
@@ -1,5 +1,6 @@
 import path from "node:path";
-import { readFile, writeFile, mkdir, readdir, stat } from "node:fs/promises";
+import type { Stats } from "node:fs";
+import { readFile, writeFile, mkdir, readdir, stat, realpath, lstat } from "node:fs/promises";
 import { RepositoryError, ValidationError } from "../errors/app-error";
 
 const DEFAULT_IGNORE = new Set([
@@ -60,36 +61,93 @@ function compareCodeUnits(a: string, b: string): number {
   return 0;
 }
 
+async function inspectExistingPath(absolute: string): Promise<Stats | undefined> {
+  try {
+    return await lstat(absolute);
+  } catch (cause) {
+    if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") return undefined;
+    throw cause;
+  }
+}
+
+function assertContained(root: string, absolute: string, requestedPath: string): void {
+  const relative = path.relative(root, absolute);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new ValidationError(`Path escapes the project root: ${requestedPath}`);
+  }
+}
+
+interface ResolvedPath {
+  absolute: string;
+  symbolicLink: boolean;
+}
+
 /**
  * Root-bounded filesystem service. All paths are resolved relative to `root`
  * and may not escape it — the single safe FS surface for the CLI and MCP.
  */
 export class FileService {
-  constructor(private readonly root: string) {}
+  private readonly root: string;
+
+  constructor(root: string) {
+    this.root = path.resolve(root);
+  }
 
   private resolveInside(relativePath: string): string {
     const abs = path.resolve(this.root, relativePath);
-    const rel = path.relative(this.root, abs);
-    if (rel.startsWith("..") || path.isAbsolute(rel)) {
-      throw new ValidationError(`Path escapes the project root: ${relativePath}`);
-    }
+    assertContained(this.root, abs, relativePath);
     return abs;
   }
 
   private toRel(abs: string): string {
     return path.relative(this.root, abs).split(path.sep).join("/");
   }
 
+  private async resolvePhysicalPath(relativePath: string): Promise<ResolvedPath> {
+    const requested = this.resolveInside(relativePath);
+    try {
+      const root = await realpath(this.root);
+      let ancestor = requested;
+      const missing: string[] = [];
+      let existing = await inspectExistingPath(ancestor);
+      while (!existing) {
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor) throw new RepositoryError(`Cannot resolve path: ${relativePath}`);
+        missing.unshift(path.basename(ancestor));
+        ancestor = parent;
+        existing = await inspectExistingPath(ancestor);
+      }
+      const resolved = await realpath(ancestor).catch((cause) => {
+        if (existing.isSymbolicLink()) {
+          throw new ValidationError(`Cannot resolve symbolic link: ${relativePath}`, { cause });
+        }
+        throw cause;
+      });
+      assertContained(root, resolved, relativePath);
+      return { absolute: path.join(resolved, ...missing), symbolicLink: missing.length === 0 && existing.isSymbolicLink() };
+    } catch (cause) {
+      if (cause instanceof ValidationError || cause instanceof RepositoryError) throw cause;
+      throw new RepositoryError(`Cannot resolve path: ${relativePath}`, { cause });
+    }
+  }
+
+  private async resolveWritablePath(relativePath: string): Promise<string> {
+    const resolved = await this.resolvePhysicalPath(relativePath);
+    if (resolved.symbolicLink) throw new ValidationError(`Cannot write through a symbolic link: ${relativePath}`);
+    return resolved.absolute;
+  }
+
   async list(relativeDir = ".", options: ListOptions = {}): Promise<string[]> {
     const { recursive = false, maxEntries = 2000 } = options;
     const start = this.resolveInside(relativeDir);
     const out: string[] = [];
 
     const walk = async (dir: string): Promise<void> => {
       if (out.length >= maxEntries) return;
+      const resolved = await this.resolvePhysicalPath(this.toRel(dir));
       let entries: import("node:fs").Dirent[];
       try {
-        entries = await readdir(dir, { withFileTypes: true });
+        entries = await readdir(resolved.absolute, { withFileTypes: true });
       } catch (cause) {
         throw new RepositoryError(`Cannot read directory: ${this.toRel(dir)}`, { cause });
       }
@@ -107,7 +165,7 @@ export class FileService {
   }
 
   async read(relativePath: string, maxBytes = 512_000): Promise<string> {
-    const abs = this.resolveInside(relativePath);
+    const { absolute: abs } = await this.resolvePhysicalPath(relativePath);
     const info = await stat(abs).catch((cause) => {
       throw new RepositoryError(`File not found: ${relativePath}`, { cause });
     });
@@ -118,10 +176,11 @@ export class FileService {
   }
 
   async write(relativePath: string, content: string): Promise<string> {
-    const abs = this.resolveInside(relativePath);
+    const abs = await this.resolveWritablePath(relativePath);
     await mkdir(path.dirname(abs), { recursive: true });
-    await writeFile(abs, content, "utf8");
-    return this.toRel(abs);
+    const target = await this.resolveWritablePath(relativePath);
+    await writeFile(target, content, "utf8");
+    return this.toRel(this.resolveInside(relativePath));
   }
 
   /** Directories are skipped; an explicit extension filter replaces the text-extension default. */